Files

Git Manager GUI 3c112ea75f Upload via Git Manager GUI

2026-05-14 08:07:13 +02:00

12 KiB

Raw Blame History

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

Projektstruktur
Setup & Abhängigkeiten
Entwicklung starten
Wichtige Module
Neue Features hinzufügen
Build & Release
Debugging & Testing
Code-Konventionen
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

# 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:

# App neu starten
npm start

# Oder im laufenden Fenster: DevTools öffnen
# Strg+Shift+I → Reload (Strg+R)

DevTools debuggen

// In main.js, beim Erstellen des Fensters:
mainWindow.webContents.openDevTools();

// Oder per Shortcut im laufenden Fenster:
// Strg+Shift+I

Logs anschauen

# 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:

// 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:

// 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.

// 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.

// 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

/**
 * 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

// 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

// 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

# Electron App als .exe packagen
npm run build

# Output: dist/git-manager-gui-Setup-2.x.x.exe

Version erhöhen

Version in package.json updaten: "version": "2.1.4"
Changelog aktualisieren (optional)
Build ausführen
GitHub Release erstellen mit der .exe

Debugging & Testing

Unit Tests schreiben

Jest ist konfiguriert. Test-Datei Vorlage:

// __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:

npm test

# Mit Coverage:
npm test -- --coverage

# Watch Mode:
npm test -- --watch

Debugging im DevTools

// 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

// 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

// 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

// 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

// 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

// 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

In Settings.jsx UI-Control hinzufügen

<label>Neue Option</label>
<input type="checkbox" onChange={(e) => setSetting('newOption', e.target.checked)} />

In renderer.js speichern

async function saveSettings(settings) {
    const result = await window.electronAPI.saveSettings(settings);
    // ...
}

In main.js Handler

ipcMain.handle('saveSettings', async (event, settings) => {
    // Validation und Speicherung
    return { ok: true };
});

In index.html Button hinzufügen

<button id="btnMyFeature" title="Mein Feature">🎯 Feature</button>

In renderer.js Event-Handler

if ($('btnMyFeature')) {
    $('btnMyFeature').onclick = () => {
        myFeatureHandler();
    };
}

Neue Kontextmenü-Option

In showRepoContextMenu() Item hinzufügen

items.push({
    label: '🎯 Meine Aktion',
    click: () => myActionHandler(owner, repo)
});

Handler implementieren

function myActionHandler(owner, repo) {
    // Logik...
}

Neue API-Methode aufrufen

In src/git/apiHandler.js ergänzen
In main.js IPC-Handler anlegen

In renderer.js aufrufen:

const result = await window.electronAPI.myNewMethod({ param1, param2 });

Troubleshooting für Entwickler

App startet nicht

# 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"

# 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

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

12 KiB Raw Blame History