Repository Maintainer
Systematischer Workflow zur Umwandlung fragmentierter GitHub-Profile in saubere, wartbare und professionelle Repositories.
Überblick
Führen Sie die Bereinigung in 6 Phasen durch. Überspringen Sie nicht zutreffende Phasen. Holen Sie bei zerstörerischen Aktionen (Löschen, Umbenennen, Zusammenführen) immer die Bestätigung des Benutzers ein.
Kernprinzipien (Nicht verhandelbar)
Jedes Repository – neu oder alt, aktiv oder archiviert – muss diese vier grundlegenden Dokumente besitzen. Betrachten Sie eine Bereinigung erst dann als abgeschlossen, wenn alle vier überprüft wurden.
| Dokument | Regel | Warum |
|---|---|---|
| LICENSE | Jedes öffentliche Repository erhält eine LICENSE. Standard ist MIT, sofern der Benutzer nichts anderes angibt. | Ohne Lizenz ist der Code standardmäßig „Alle Rechte vorbehalten". Niemand kann ihn legal nutzen. |
| README.md | Muss mindestens enthalten: Projektname, ein Satz Beschreibung und ggf. Installations-/Verwendungsanweisungen. | Das erste, was jeder Besucher sieht. Ein leeres oder fehlendes README signalisiert Aufgabe. |
| .gitignore | Muss zur primären Sprache passen (Python/PHP/Node/usw.). Keine Build-Artefakte, Caches, Env-Dateien oder IDE-Konfigurationen committen. | Verhindert versehentliches Durchsickern von Geheimnissen und hält Diffs lesbar. |
| GitHub Beschreibung | Das Feld description darf niemals leer sein. Ein Satz in klarem Deutsch (oder passend zur Sprache des Repos). | Erscheint in Suchergebnissen, Profil-Pins und Social Cards. |
Wenn einem Repository eines der vier Dokumente fehlt, hat die Behebung Priorität vor Zusammenführen, Umbenennen oder Refactoring.
Phase 1: Scannen und Diagnose
Komplette Repo-Liste über die GitHub-API abrufen:
curl -sH "Authorization: Bearer TOKEN" \
"https://api.github.com/user/repos?per_page=100&affiliation=owner"
Für jedes Repository prüfen:
- Fehlende
LICENSE,.gitignore,README.md - Leeres
description-Feld - Inkonsistenzen in der Benennung (gemischte Groß-/Kleinschreibung, übermäßig lange Namen)
- Offensichtliche Duplikate oder Serien (z. B.
projekt,projekt-v2,projekt-mineru) - Namen mit
outdated,deprecated,old,test
Phase 2: Fundamentaldokumente standardisieren
Für jedes aktive Repository sicherstellen, dass der minimale Dateisatz vorhanden ist:
| Datei | Regel |
|---|---|
LICENSE | Standard ist MIT, sofern der Benutzer nichts anderes angibt |
.gitignore | Muss zur primären Sprache passen (Python/PHP/Node) |
README.md | Muss vorhanden sein; bei Platzhaltern neu schreiben |
| GitHub Beschreibung | Ein-Satz-Zusammenfassung über die API |
Massenaktualisierung über die GitHub Contents API (PUT /repos/{owner}/{repo}/contents/{path}).
Wichtig: PowerShell Here-Strings beschädigen Codeblöcke mit drei Backticks in Markdown. Verwenden Sie Python-Skripte für die README-Massenerstellung, um Probleme mit der Maskierung von ` zu vermeiden.
Phase 3: Umgang mit veralteten Repositories
Entscheidungsbaum:
| Bedingung | Aktion |
|---|---|
Name enthält outdated / deprecated / old | Archivieren oder löschen |
| Durch neueres Repository ersetzt | Archivieren + README-Nachfolgelink |
| Öffentliches Repo enthält durchgesickerte Secrets (API-Keys) in der Historie | Löschen (Archivieren behält die Historie bei) |
| Privates Repo enthält Keys, Passwörter, private Konfiguration oder personenbezogene Daten | Benutzer darf Leck-Regeln ignorieren; als akzeptablen privaten Zustand behandeln, es sei denn, er bittet um Bereinigung |
| Als Referenz nützlich, aber ungepflegt | Archivieren |
Archivierte Repositories sind schreibgeschützt. Um ein archiviertes Repository zu ändern (umbenennen, README aktualisieren), zuerst dearchivieren (PATCH {"archived": false}), Änderungen vornehmen, dann erneut archivieren.
Phase 4: Zusammenhängende Repositories zusammenführen
Wenn 2+ Repos Varianten desselben Systems sind (verschiedene Backends, Engines, Adapter):
Option A – Monorepo (Empfohlen)
Ein neues, sauberes Repository (ohne Historie) erstellen. Jede Variante in eigenem engines/{name}/-Unterverzeichnis platzieren.
projekt-suite/
├── main.py # Standard-Engine
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
Einstiegspunkt und Konfiguration jeder Engine beibehalten. Root-README aktualisieren, um den Wechsel zu erklären.
Option B – Git-Submodul Repos unabhängig lassen. Submodule im übergeordneten Projekt hinzufügen. Verwenden, wenn die Historie wichtiger ist als Einfachheit.
Option C – Unabhängig lassen + verlinken Nicht zusammenführen. Cross-Links in READMEs hinzufügen. Verwenden, wenn sich die Varianten erheblich unterschieden haben.
Wenn die Historie Secrets enthält: Immer ein neues, sauberes Repository erstellen und den aktuellen Snapshot kopieren (per Zip-Download + Neu-Commit). git merge oder git submodule nicht verwenden, da die Historie-Leaks bestehen bleiben.
Phase 5: Repositories umbenennen
API-Patch: PATCH /repos/{owner}/{repo} mit {"name": "neuer-name"}.
Richtlinien:
- Nur Kleinbuchstaben, Bindestriche erlaubt
- Maximal 3-4 Wörter
- Überflüssige Wörter entfernen (
based-on,design-and-development) - Bei archivierten Repos ggf.
-outdatedanhängen, wenn nicht bereits vorhanden
GitHub leitet alte URLs für eine gewisse Zeit automatisch weiter, aber Lesezeichen und Skripte könnten brechen. Vor dem Umbenennen von gestarnten oder geforkten Repos die Bestätigung des Benutzers einholen.
Phase 6: Refactoring auf Code-Ebene
Nachdem die Remote-Struktur bereinigt ist, den Code in den Repos refactorn:
- Einheitliche Terminologie – Hartcodierte Markennamen durch generische Begriffe ersetzen (
GPTProcessor→LLMProcessor), während die tatsächlichen API-Modell-IDs (gpt-4,gpt-5) erhalten bleiben. - Dateien umbenennen – Die GitHub Contents API hat keine Umbenennungsfunktion; neue Datei mit aktualisiertem Inhalt erstellen, alte Datei löschen.
- Verzeichnisstruktur überarbeiten – Muster wie
engines/,variants/odercore/+adapters/für Projekte mit mehreren Varianten verwenden.
Große lokale Refactorings an Remote pushen
Wenn der Benutzer Code lokal herunterlädt, umfangreiche Änderungen vornimmt (Datei-Umbenennungen, Variablen-Umbenennungen, strukturelle Umschreibungen) und zurück ins Remote-Repository pushen muss.
Pre-Push-Scanner auf Secrets (VERPFLICHTEND)
Vor dem Push muss ein Scan auf Secret-Leaks durchgeführt werden. Bei Fund sofort melden und den Push stoppen.
Ausnahme für private Repos: Wenn das Ziel-Repository nachweislich privat ist, können Leaks von Keys, Passwörtern, privaten Konfigurationen, personenbezogenen Daten und anderen sensiblen Informationen ignoriert werden. Der Scan dient als Hinweis, blockiert aber nicht den Push und erfordert keine Löschung/Neuerstellung des Repos oder Austausch gegen Umgebungsvariablen, es sei denn, der Benutzer fordert eine Bereinigung oder plant, das Repo öffentlich zu machen.
Scan-Modus (beide Läufe sind erforderlich – nur den Token-Regex zu laufen lässt Klartext-Passwörter aus):
① Token/API-Key mit hoher Entropie:
grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
--include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
--include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
--exclude-dir=".git" .
② Klartext-Passwörter / Credential-Helper (vom Token-Regex nicht erfasst; in der Praxis wurde askpass.sh mit echo "<sudo password>" übersehen und landete per Init-Commit auf GitHub):
git ls-files -z | xargs -0 grep -nIE "password|passwd|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
| grep -vE "\.md:|getenv|getpass|placeholder|example"
# Und isolierte askpass.sh / *_secret* / .pgpass / .npmrc-Dateien manuell prüfen – diese Dateien sind selbst die Credentials
Bei öffentlichen Repos führt jeder Treffer sofort zur unten beschriebenen Zwangsverarbeitung. Bei privaten Repos wird der Benutzer nur gewarnt, es gibt keine Blockade. Beachten Sie: Gescannt wird git ls-files (bereits getrackte Dateien); durch .gitignore ausgeschlossene Dateien zählen nicht als Leak, aber bereits committete Dateien bleiben auch dann in der Historie, wenn sie jetzt in .gitignore sind.
Meldeformat:
[LEAK] scripts/eval.py:15 — sk-xxxx (hartcodierter Fallback)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (hartcodierter Standardwert)
Zwangsverarbeitung bei Leak-Fund:
- Benutzer sofort informieren, in welcher Datei in welcher Zeile
- Durch Umgebungsvariable ersetzen (
os.getenv("API_KEY")ohne Standardwert) - Bereits nach Remote gepusht: Benutzer informieren, nach Bestätigung Repo löschen und neu erstellen (Git-Historie lässt sich durch Force-Push nicht vollständig entfernen)
- Benutzer muss den Key beim entsprechenden Dienst widerrufen
Pre-Push-Checkliste
Vor dem Push muss Folgendes ausgeführt werden:
git status
Sicherstellen, dass Folgendes nicht vorliegt:
- Untracked files – Neue, nicht verfolgte Dateien (häufig vergessen: docs/, scripts/, config-Vorlagen)
- Changes not staged – Änderungen, die nicht hinzugefügt wurden
- Changes to be committed enthält Dateien, die nicht hochgeladen werden sollten (Schlüssel, persönliche Daten, temporäre Skripte)
Bevor dies bestätigt ist, ist ein direkter Push verboten.
Entscheidungsbaum
| Situation | Empfohlene Aktion |
|---|---|
Lokales Repo hat kein .git (heruntergeladene Zip / kopierte Dateien) | Siehe Szenario A unten |
Lokal ist git clone mit Historie, Remote unverändert | Normal git add → commit → push |
Lokal ist git clone, Remote hat neue Commits | git pull --rebase oder merge, Konflikte lösen, pushen |
Lokal ist git clone, Änderungen sind massive Umbenennungen + Umschreibungen | Siehe Szenario B unten |
| Remote-Historie erhalten, aber gesamten Code ersetzen | Siehe Szenario C unten |
Szenario A: Lokal hat keine Git-Historie
Tritt am häufigsten auf, wenn der Benutzer eine Zip herunterlädt, umfangreich bearbeitet und dann zurück synchronisieren möchte.
Option A1 – Force Push (Persönliche / Solo-Projekte)
# Im lokalen Projektordner
git init
git add .
git commit -m "refactor: major rewrite"
git remote add origin https://github.com/BESITZER/REPO.git
git branch -M main
git push -u origin main --force
⚠️ Zerstört die Remote-Historie. Nur verwenden, wenn der Benutzer bestätigt, dass die Remote-Historie entbehrlich ist.
Option A2 – Remote-Historie erhalten (Empfohlen für wertvolle Repos)
git clone https://github.com/BESITZER/REPO.git temp-repo
cp -r temp-repo/.git ./ihr-lokales-projekt/
cd ihr-lokales-projekt
git add .
git commit -m "refactor: major rewrite"
git push
Dies behält alle vorherigen Commits und hängt den Refactor als einzelnen neuen Commit an.
Option A3 – Neues sauberes Repository Wenn die Umschreibung so radikal ist, dass es sich im Wesentlichen um ein neues Projekt handelt:
- Neues Repo auf GitHub erstellen (muss
descriptionenthalten oder sofort per PATCH setzen) - Lokalen Code dorthin pushen
- Altes Repo mit Nachfolgelink im README archivieren
Szenario B: Massive Umbenennungen + Umschreibungen in einem geklonten Repo
Wichtige Regel: Niemals Dateiumbenennungen und Inhaltsänderungen im selben Commit mischen. Git behandelt dies als „Alte Datei löschen + Neue Datei erstellen" und verliert die Historie.
Schrittweise Commit-Strategie:
# Schritt 1: Nur umbenennen
git mv altes_module.py neues_module.py
git mv alte_utils/ neue_utils/
git commit -m "refactor: Module umbenennen"
# Schritt 2: Variablen-/Klassen umbenennen
git add .
git commit -m "refactor: Variablen und Klassen umbenennen"
# Schritt 3: Logik-Änderungen
git add .
git commit -m "feat: Kernlogik aktualisieren"
Wenn der Benutzer bereits alles im Arbeitsverzeichnis vermischt hat:
# Aktuelle Änderungen stashen, in Schritten wiedereinspielen
git stash push -m "gemischter Refactor"
# Nur Umbenennungen wiederherstellen (git mv oder manuelles mv + git add verwenden)
git mv alte_datei neue_datei
git commit -m "refactor: Dateien umbenennen"
# Inhaltsänderungen wiederherstellen
git stash pop
# Ggf. Konflikte lösen, dann committen
Szenario C: Gesamten Code ersetzen, aber Historie behalten
Nützlich, wenn der Benutzer einen Neuanfang machen möchte, aber Stars/Issues/URL behalten will.
git checkout --orphan fresh-start
git rm -rf .
# Neuen lokalen Code hier einfügen
git add .
git commit -m "init: clean rewrite"
git branch -D main
git branch -m main
git push -u origin main --force
Erkennung von Umbenennungen prüfen
Nach dem Push überprüfen, ob Git die Umbenennungen korrekt verfolgt:
git log --follow -- neue_datei.py
Wenn die Historie unterbrochen ist (Datei als brandneu angezeigt wird), wurden Umbenennung und Inhaltsänderung zusammen committet.
Sicherheit und Compliance
- GitHub-Token: Wenn ein PAT benötigt wird, im Agenten-Gedächtnis suchen (kein konkreter Pfad/Konto/Wert hier). Den Token-Wert niemals in eine Datei schreiben, die gepusht wird (einschließlich dieser Skill, README, Konfiguration) – sobald ein Token-haltiger Inhalt gepusht wird, wird er durch GitHub-Secret-Scanning widerrufen.
- Token-Hygiene: Nach Bulk-Operationen den Benutzer anweisen, das PAT sofort unter
https://github.com/settings/tokenszu widerrufen. - Ausnahme für private Repos: Wenn ein Repo privat ist, kann der Agent Leaks von Keys, Passwörtern, privater Konfiguration, personenbezogenen Daten und anderen sensiblen Informationen ignorieren. Push nicht blockieren, keine Zwangsbereinigung durchführen oder Löschung empfehlen, nur weil die private Historie Secrets enthält, es sei denn, der Benutzer verlangt es oder das Repo könnte öffentlich werden.
- Öffentliche Secret-Historie: Wenn ein öffentliches Repository jemals API-Keys committet hat, ist das Löschen des Repos der einzige Weg, die Historie von GitHub zu entfernen. Force-Push einer bereinigten Historie garantiert keine Entfernung aus den Backup-Systemen von GitHub.
- Archivierte öffentliche Repos mit Secrets: Wenn Löschung inakzeptabel ist, das Repo mindestens aus der öffentlichen Sichtbarkeit entfernen (privat machen) oder löschen und mit sauberem Code neu erstellen.
Technische Referenz
Encoding-Fallen (Windows)
PowerShell verwendet standardmäßig CP1252 für die Standardausgabe, was chinesische Zeichen und Markdown-Codeblöcke zerstört. Immer neu konfigurieren:
import sys
sys.stdout.reconfigure(encoding='utf-8')
Bei Verwendung von Invoke-RestMethod in PowerShell mit JSON-Bodies, die Backticks oder drei Backticks enthalten, Python-Skripte für die Inhaltsgenerierung bevorzugen, um zu vermeiden, dass ``` in ` umgewandelt wird.
GitHub-API-Muster
Repository erstellen (niemals description weglassen):
api_call("POST", "/user/repos", {
"name": "repo-name",
"private": True,
"description": "Ein-Satz-Zusammenfassung."
})
Datei erstellen/aktualisieren:
import base64, json, urllib.request
payload = {
"message": "Commit-Nachricht",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": existing_sha # für Aktualisierungen erforderlich
}
req = urllib.request.Request(
f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
method="PUT",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {token}", ...}
)
Archivieren/Dearchivieren:
api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})
Repository umbenennen:
api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "neuer-name"})
Repository löschen:
api_call("DELETE", f"/repos/{owner}/{repo}")
Massen-Download ohne Clone
Repo-Snapshot als Zip herunterladen, um langsames git clone über instabile Netzwerke zu vermeiden:
curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip
Mitgelieferte Ressourcen
scripts/repo_analyzer.py– GitHub-Repos des Benutzers scannen und Bereinigungsempfehlungen generierenscripts/bulk_file_updater.py– LICENSE, .gitignore, README per GitHub-API in Batches erstellen/aktualisieren