From 3c112ea75f0df7bc14bad37e444af0112dc91b75 Mon Sep 17 00:00:00 2001 From: Git Manager GUI Date: Thu, 14 May 2026 08:07:13 +0200 Subject: [PATCH] Upload via Git Manager GUI --- DEV_GUIDE.md | 535 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 535 insertions(+) create mode 100644 DEV_GUIDE.md diff --git a/DEV_GUIDE.md b/DEV_GUIDE.md new file mode 100644 index 0000000..71c0408 --- /dev/null +++ b/DEV_GUIDE.md @@ -0,0 +1,535 @@ +# Entwicklerhandbuch — Git Manager Explorer Pro + +Dieses Dokument richtet sich an Entwickler, die an **Git Manager Explorer Pro** beitragen oder das Projekt erweitern möchten. + +--- + +## Inhaltsverzeichnis + +1. [Projektstruktur](#projektstruktur) +2. [Setup & Abhängigkeiten](#setup--abhängigkeiten) +3. [Entwicklung starten](#entwicklung-starten) +4. [Wichtige Module](#wichtige-module) +5. [Neue Features hinzufügen](#neue-features-hinzufügen) +6. [Build & Release](#build--release) +7. [Debugging & Testing](#debugging--testing) +8. [Code-Konventionen](#code-konventionen) +9. [Häufige Aufgaben](#häufige-aufgaben) + +--- + +## Projektstruktur + +``` +git-manager-gui/ +├── main.js # Electron Main Process — Fenster, Menü, IPC +├── preload.js # Preload Script — sichere Electron API für Renderer +├── renderer/ # Frontend (React/Vanilla JS) +│ ├── App.jsx # React-Komponente (optional, optional genutzt) +│ ├── Settings.jsx # Settings-Modal +│ ├── index.html # HTML Entry Point +│ ├── index.js # Renderer Init +│ ├── renderer.js # Hauptlogik: UI, Grid, Editor, API-Calls +│ ├── style.css # Styling +│ └── modules/ # Feature-Module +│ ├── editor.js # Editor-Funktion (Syntax Highlighting, etc.) +│ ├── gitea.js # Gitea API Wrapper +│ ├── github.js # GitHub API Wrapper +│ ├── progress.js # Progress-Bar & Ladeindikatoren +│ ├── state.js # State Management (Favoriten, Verlauf, etc.) +│ └── ui.js # UI Helpers (Dialoge, Toast, etc.) +├── src/ # Backend (Node.js Main Process) +│ ├── git/ +│ │ ├── gitHandler.js # Git CLI Wrapper (Commits, Tags, etc.) +│ │ └── apiHandler.js # Gitea/GitHub API HTTP Client +│ ├── backup/ +│ │ ├── BackupManager.js # Backup/Restore Logik +│ │ ├── BackupProvider.js # Provider Interface +│ │ └── LocalProvider.js # Lokale Datei-Provider +│ └── utils/ +│ └── helpers.js # Allgemeine Hilfsfunktionen +├── __tests__/ +│ └── gitHandler.test.js # Jest Unit Tests +├── updater.js # App-Update-Logik +├── package.json # Dependencies & Scripts +├── HANDBUCH.html # Benutzerhandbuch (HTML) +└── README.md # Projekt-Übersicht + +``` + +--- + +## Setup & Abhängigkeiten + +### Voraussetzungen +- **Node.js** 16+ (empfohlen: LTS) +- **npm** 7+ +- **Git** (für Git-Operationen) +- **Visual Studio Code** (optional, empfohlen) + +### Installation + +```bash +# Repository klonen +git clone https://github.com/dein-username/git-manager-gui.git +cd git-manager-gui + +# Dependencies installieren +npm install + +# App starten +npm start +``` + +### Wichtige Dependencies + +| Package | Verwendung | +|---------|-----------| +| `electron` | Desktop-Framework | +| `sqlite3` | Lokale Datenspeicherung (Favoriten, Verlauf) | +| `axios` | HTTP-Requests zu Gitea/GitHub APIs | +| `crypto` | Verschlüsselung von Credentials | +| `jest` | Testing Framework | + +--- + +## Entwicklung starten + +### Dev-Server / Hot Reload + +Es gibt aktuell keinen automatischen Hot Reload. Nach Code-Änderungen: + +```bash +# App neu starten +npm start + +# Oder im laufenden Fenster: DevTools öffnen +# Strg+Shift+I → Reload (Strg+R) +``` + +### DevTools debuggen + +```javascript +// In main.js, beim Erstellen des Fensters: +mainWindow.webContents.openDevTools(); + +// Oder per Shortcut im laufenden Fenster: +// Strg+Shift+I +``` + +### Logs anschauen + +```bash +# Logs der letzten Session anschauen: +# Windows: %APPDATA%\git-manager-gui\logs\ +# oder direkt im app data folder + +# Mit Winston logger (falls implementiert): +npm run logs +``` + +--- + +## Wichtige Module + +### `renderer/renderer.js` — Hauptlogik + +Das Herzstück der App. Enthält: + +- **Globale State-Variablen**: `favorites`, `recentRepos`, `currentState`, `pinnedRepos` +- **Grid-Rendering**: `loadRepos()`, `loadGiteaRepos()`, `loadGithubRepos()` +- **Kontext-Menü**: `showRepoContextMenu()` +- **Datei-Explorer**: `loadRepoContents()`, `renderExplorer()` +- **Editor**: `openFileEditor()`, mit Speichern & Syntax-Highlighting +- **Favoriten/Verlauf**: `addToFavorites()`, `addToRecent()` + +**Wichtige Funktionen:** + +```javascript +// Repository-Liste laden +loadRepos() → loadGiteaRepos() oder loadGithubRepos() + +// Repository öffnen (Datei-Explorer) +loadRepoContents(owner, repo, path) + +// Datei bearbeiten +openFileEditor(owner, repo, path, content) + +// Favoriten hinzufügen +async addToFavorites(owner, repo, cloneUrl, platform) + +// Settings speichern +async saveSettings(settings) +``` + +### `src/git/gitHandler.js` — Git-Operationen + +Wrapper um Git CLI. Beispiele: + +```javascript +// Commits einsehen +const commits = await getCommitLog(repoPath, branch); + +// Tags auflisten +const tags = await getTagList(repoPath); + +// Branch wechseln +await checkoutBranch(repoPath, branchName); + +// Lokales Repo klonen +await cloneRepository(cloneUrl, targetPath); +``` + +### `src/git/apiHandler.js` — API-Calls + +HTTP-Wrapper für Gitea/GitHub APIs. + +```javascript +// Gitea Repositories auflisten +const repos = await getGiteaRepos(url, token, username); + +// GitHub Repositories +const repos = await getGithubRepos(token); + +// Repository erstellen +await createGiteaRepo(url, token, { name, description, private }); + +// Datei speichern +await updateGiteaFile(url, token, owner, repo, path, content, message); +``` + +### `renderer/modules/state.js` — State Management + +Persistiert Favoriten, Verlauf und Settings. + +```javascript +// State laden/speichern +loadState() → returns { favorites, recent, pinnedRepos } +saveState(state) → speichert lokal + +// Helpers +addFavorite(repo) +removeFavorite(repo) +addRecentRepo(repo) +clearRecent() +``` + +--- + +## Neue Features hinzufügen + +### Beispiel: Neuer API-Endpoint integrieren + +#### Schritt 1: API-Wrapper in `src/git/apiHandler.js` ergänzen + +```javascript +/** + * Gitea Webhook auflisten + */ +async function getGiteaWebhooks(url, token, owner, repo) { + const path = `/api/v1/repos/${owner}/${repo}/hooks`; + return axios.get(`${url}${path}`, { + headers: { 'Authorization': `token ${token}` } + }).then(r => r.data); +} + +module.exports = { getGiteaWebhooks, /* ... other functions */ }; +``` + +#### Schritt 2: IPC-Handler in `main.js` ergänzen + +```javascript +// In ipcMain.handle() Bereich: +ipcMain.handle('getGiteaWebhooks', async (event, { url, token, owner, repo }) => { + try { + const webhooks = await apiHandler.getGiteaWebhooks(url, token, owner, repo); + return { ok: true, webhooks }; + } catch (err) { + return { ok: false, error: err.message }; + } +}); +``` + +#### Schritt 3: UI in `renderer/renderer.js` hinzufügen + +```javascript +// Button im Repo-Kontextmenü: +if (option === 'webhooks') { + const webhooks = await window.electronAPI.getGiteaWebhooks({ + url: currentState.giteaUrl, + token: credentials.giteaToken, + owner, + repo + }); + if (webhooks.ok) { + showWebhookList(webhooks.webhooks); + } else { + showError('Webhooks laden fehlgeschlagen: ' + webhooks.error); + } +} +``` + +--- + +## Build & Release + +### Production Build + +```bash +# Electron App als .exe packagen +npm run build + +# Output: dist/git-manager-gui-Setup-2.x.x.exe +``` + +### Version erhöhen + +1. Version in `package.json` updaten: `"version": "2.1.4"` +2. Changelog aktualisieren (optional) +3. Build ausführen +4. GitHub Release erstellen mit der .exe + +--- + +## Debugging & Testing + +### Unit Tests schreiben + +Jest ist konfiguriert. Test-Datei Vorlage: + +```javascript +// __tests__/myFeature.test.js +const { myFunction } = require('../src/git/gitHandler'); + +describe('Git Handler', () => { + it('should parse commit log', () => { + const result = myFunction(testData); + expect(result.length).toBe(3); + expect(result[0].sha).toMatch(/^[a-f0-9]{7}/); + }); +}); +``` + +Tests starten: + +```bash +npm test + +# Mit Coverage: +npm test -- --coverage + +# Watch Mode: +npm test -- --watch +``` + +### Debugging im DevTools + +```javascript +// Im renderer.js oder irgendwo im Renderer: +console.log('Debug Info:', data); + +// Öffne DevTools: Strg+Shift+I +// Console Tab → alle Logs sichtbar +``` + +### Main Process debuggen + +```javascript +// In main.js: +console.log('Main Process Log:', data); + +// Logs erscheinen in der Terminal-Console +// wenn die App mit npm start gestartet wurde +``` + +--- + +## Code-Konventionen + +### Variablen & Funktionen + +```javascript +// camelCase für Variablen und Funktionen +const repoName = "mein-projekt"; +function loadRepositories() { } + +// SCREAMING_SNAKE_CASE für Konstanten +const MAX_RETRIES = 5; +const DEFAULT_TIMEOUT = 3000; + +// Präfixe für Boolean-Variablen +const isPrivate = true; +const hasCredentials = false; +const shouldRetry = true; +``` + +### Async/Await + +```javascript +// Immer try-catch für async Funktionen +async function loadData() { + try { + const data = await fetchFromAPI(); + return { ok: true, data }; + } catch (error) { + console.error('Error:', error); + return { ok: false, error: error.message }; + } +} +``` + +### Kommentare + +```javascript +// Kurze Inline-Kommentare über Code +const delay = 1000; // Millisekunden + +/** + * Längere Beschreibung vor Funktion + * @param {string} repoName - Name des Repositories + * @returns {Promise} Result mit { ok, data, error } + */ +async function loadRepository(repoName) { + // Implementierung +} +``` + +### Fehlerbehandlung + +```javascript +// Immer aussagekräftige Fehlermeldungen +if (!token) { + return { ok: false, error: 'missing-token' }; +} + +// Oder sprechend für Benutzer: +if (!token) { + return { ok: false, error: 'Gitea Token nicht gespeichert. Bitte Settings öffnen.' }; +} +``` + +--- + +## Häufige Aufgaben + +### Neue Einstellung hinzufügen + +1. **In `Settings.jsx` UI-Control hinzufügen** + ```jsx + + setSetting('newOption', e.target.checked)} /> + ``` + +2. **In `renderer.js` speichern** + ```javascript + async function saveSettings(settings) { + const result = await window.electronAPI.saveSettings(settings); + // ... + } + ``` + +3. **In `main.js` Handler** + ```javascript + ipcMain.handle('saveSettings', async (event, settings) => { + // Validation und Speicherung + return { ok: true }; + }); + ``` + +### Neuer Button in der Toolbar + +1. **In `index.html` Button hinzufügen** + ```html + + ``` + +2. **In `renderer.js` Event-Handler** + ```javascript + if ($('btnMyFeature')) { + $('btnMyFeature').onclick = () => { + myFeatureHandler(); + }; + } + ``` + +### Neue Kontextmenü-Option + +1. **In `showRepoContextMenu()` Item hinzufügen** + ```javascript + items.push({ + label: '🎯 Meine Aktion', + click: () => myActionHandler(owner, repo) + }); + ``` + +2. **Handler implementieren** + ```javascript + function myActionHandler(owner, repo) { + // Logik... + } + ``` + +### Neue API-Methode aufrufen + +1. **In `src/git/apiHandler.js` ergänzen** +2. **In `main.js` IPC-Handler anlegen** +3. **In `renderer.js` aufrufen:** + ```javascript + const result = await window.electronAPI.myNewMethod({ param1, param2 }); + ``` + +--- + +## Troubleshooting für Entwickler + +### App startet nicht +```bash +# Node/npm Version prüfen +node --version # sollte >= 16 +npm --version # sollte >= 7 + +# Dependencies neu installieren +rm -r node_modules +npm install +npm start +``` + +### Fehler: "Cannot find module" +```bash +# Dependencies aktualisieren +npm install + +# Cache löschen +npm cache clean --force +``` + +### Axios/API-Calls schlagen fehl +- URL/Token in Settings prüfen +- Gitea-Server online? `curl https://git.example.com/api/v1/user` +- Token noch gültig? Im Gitea-Interface regenerieren +- Firewall/VPN blockiert? + +### Datei-Upload funktioniert nicht +- Lokale Temp-Pfade prüfen (in `main.js`) +- Git-Auth konfiguriert? +- Ausreichend Festplatte? + +--- + +## Ressourcen + +- [Electron Dokumentation](https://www.electronjs.org/docs) +- [Gitea API](https://docs.gitea.io/en-us/api-usage/) +- [GitHub API v3](https://docs.github.com/en/rest) +- [Jest Testing](https://jestjs.io/docs/getting-started) + +--- + +## Lizenz & Beitragen + +Dieses Projekt ist unter der **MIT-Lizenz** lizenziert. +Für Beiträge bitte einen **Pull Request** einreichen mit aussagekräftiger Beschreibung. + +--- + +**Letzte Aktualisierung:** 13. Mai 2026 | **Ersteller:** M_Viper