536 lines
12 KiB
Markdown
536 lines
12 KiB
Markdown
# 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<Object>} 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
|
|
<label>Neue Option</label>
|
|
<input type="checkbox" onChange={(e) => 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
|
|
<button id="btnMyFeature" title="Mein Feature">🎯 Feature</button>
|
|
```
|
|
|
|
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
|