Git-Repository-Organizer

Was macht Git-Repository-Organizer?

Jede Schlussfolgerung auf einen aktuellen Git-Snapshot stützen. Behandle Referenzen, ausgecheckte Verzeichnisse, nicht committete Dateien und gehostete Remotes als separate Zustandsebenen.

Betriebsmodus auswählen

Den engsten Modus ableiten, der durch die Anfrage autorisiert wird:

• Analyze (Analysieren): Prüfen und berichten, ohne Referenzen, Index oder Worktree-Inhalte zu ändern. Verwende git ls-remote, wenn die aktuelle Remote-Wahrheit wichtig ist; rufe nicht ab, merge, pull, commit, rebase, lösche nicht, push nicht, erstelle keine Tracking-Branches oder wechsle Worktrees nur zur Analyse.
• Refresh (Aktualisieren): Remote-Tracking-Referenzen abrufen, dann berichten. Integriere keinen Branch nur, weil Referenzen abgerufen wurden.
• Commit (Committen): Änderungen nur im benannten Worktree organisieren und committen.
• Integrate (Integrieren): Nur die benannten Branches über einen sauberen Integrations-Worktree mergen, rebasen oder cherry-picken.
• Clean up (Bereinigen): Nur Branches oder Worktrees entfernen, die unter der Entscheidungsmatrix als sicher nachgewiesen wurden.
• Synchronize (Synchronisieren): Nur die benannten Referenzen pushen oder fast-forwarden, nach dem Aktualisieren und erneuten Prüfen.

Wenn „整理 (aufräumen)“ oder „同步 (synchronisieren)“ nicht eindeutig Mutationen autorisiert, zuerst inventarisieren und die genauen vorgeschlagenen Operationen präsentieren. Vor dem Löschen von Remote-Referenzen, Force-Push, Umschreiben gemeinsamer Historie, Verwerfen von Änderungen oder Force-Entfernen eines Worktrees explizite Bestätigung einholen.

Aktuelle Momentaufnahme erstellen

1. Das tatsächliche Repository und das gemeinsame Git-Verzeichnis finden. Niemals annehmen, dass das aktuelle Arbeitsverzeichnis das Repository-Root ist.
2. Projektanweisungen wie AGENTS.md lesen, bevor gehandelt wird.
3. Im Analyze-Modus Live-Remote-Tipps überprüfen, ohne Remote-Tracking-Referenzen zu aktualisieren:

git ls-remote --symref --heads REMOTE

Klarstellen, dass lokale Remote-Tracking-Referenzen zwischengespeichert und unverändert bleiben. Im Refresh-Modus oder unmittelbar vor einer explizit angeforderten Remote-Mutation ausführen:

git fetch --all --prune --no-tags

Standardmäßig no-tags verwenden. Das Abrufen von Branches und das Abrufen von Tags sind separate Operationen; niemals automatisch einen widersprüchlichen lokalen Tag überschreiben.

Das Abrufen aktualisiert nur Remote-Tracking-Referenzen. Im Refresh-Modus dort anhalten und jeden lokalen Branch mit seinem Remote-Gegenstück vergleichen, ohne eine Seite zu integrieren:

• Niemals mergen oder pullen, nur um eine Prüfung aktuell aussehen zu lassen. Ein lokaler Branch kann legitim voraus, zurück oder abgewichen sein; diesen Zustand melden.
• Niemals committen, stashen, snapshot, wechseln, zurücksetzen oder anderweitig einen schmutzigen Worktree nur zur Analyse berühren. Den schmutzigen Zustand aufzeichnen und als Mutationsblocker behandeln.
• Lokale Branches, deren Remote gelöscht wurde (upstream gone) oder die nie gepusht wurden, bleiben lokal; dies im Bericht explizit vermerken.
• Nur in den Synchronize- oder Integrate-Modus wechseln, wenn der Benutzer diese Mutation explizit anfordert. Die Prüfung unmittelbar davor erneut ausführen, in dem Worktree arbeiten, der den Branch besitzt, und die Entscheidungsmatrix anwenden.

4. Das gebündelte, schreibgeschützte Audit ausführen:

python3 scripts/audit_git_state.py --repo /absoluter/pfad --format markdown
python3 scripts/audit_git_state.py --repo /absoluter/pfad --base main --format json

Skripte relativ zu diesem Skill-Verzeichnis auflösen, nicht zum Ziel-Repository.

5. Einzigartige Commits und geänderte Dateien für jeden Branch prüfen, der behalten, integriert oder gelöscht werden könnte:

git log --left-right --cherry-pick --oneline BASE...BRANCH
git diff --stat BASE...BRANCH
git diff --name-status BASE...BRANCH

Repräsentative Diffs lesen, bevor die Branch-Funktionalität beschrieben wird. Die Funktion nicht aus einem Branch-Namen ableiten.

6. Jeden abgetrennten Worktree vor der Bereinigung klassifizieren:

git merge-base --is-ancestor HEAD BASE && echo "BEREITS in BASE enthalten"

Sowohl gegen die lokale Basis als auch gegen die Remote-Basis prüfen (z.B. main und github/main). Ein sauberer, abgetrennter HEAD, der ein Vorfahre der Remote-Basis ist, ist bereits gemergt – er muss nicht reintegriert werden und benötigt keinen Recovery-Branch; es handelt sich wahrscheinlich um einen Überrest eines Verifizierungsskripts und kann nach Bestätigung sicher entfernt werden. Ein abgetrennter HEAD, der kein Vorfahre ist, kann einzigartige Commits enthalten; vor dem Entfernen einen Recovery-Branch bei HEAD erstellen, selbst wenn der Worktree sauber aussieht. Nicht versionierte Dateien prüfen und generierte Artefakte (Testausgaben, Build-Verzeichnisse) von handgeschriebener Arbeit trennen, bevor ein Force-Remove durchgeführt wird.

7. Die Ausgabe proportional zur Entscheidung halten. Das JSON-Audit und die Bulk-Ref/Worktree/Diff-Listen in eine temporäre Datei schreiben und nur die Zusammenfassungen lesen. Tiefgehende Diffs nur für Branches, die Integrations- oder Löschkandidaten sind; keine Branch-für-Branch-Logs und vollständigen Diffs in den Kontext großer Repositorys einfügen.

8. Das Audit unmittelbar vor dem endgültigen Bericht und vor jeder Mutation erneut ausführen. Repositorys können sich während der Analyse ändern; den Snapshot-Zeitpunkt und die Tip-Hashes in das Ergebnis aufnehmen. Auch auf gleichzeitige Aktivitäten achten: Eine Referenz, ein Worktree oder ein Remote-Branch, der von einem anderen Prozess seit dem letzten Snapshot erstellt oder gelöscht wurde (z.B. ein Merge-Kandidaten-Branch), ändert den Plan; den Plan erneut präsentieren, anstatt auf veraltete Ziele zu reagieren.

Das Zustandsmodell präzise halten

• Das normale Checkout des Repositorys ist der primäre Worktree. Er erscheint in git worktree list ist aber kein externer verknüpfter Worktree.
• Ein Branch, der unter einem anderen Pfad ausgecheckt ist, ist ein externer verknüpfter Worktree.
• Ein abgetrennter Worktree hat einen ausgecheckten Commit, aber keinen Branch. Behandle schmutzige abgetrennte Worktrees als wiederherstellbare Arbeit, nicht als Müll. Immer prüfen, ob sein HEAD ein Vorfahre der Basis (lokal und remote) ist: wenn ja und der Worktree sauber ist, ist er bereits gemergt und benötigt keine Reintegration; wenn nicht, können seine Commits nach dem Entfernen unerreichbar werden und benötigen zuerst einen Recovery-Branch.
• Ein Branch-Ref und ein Worktree sind unterschiedliche Objekte. Das Entfernen eines sauberen verknüpften Worktrees löscht nicht dessen Branch; das Löschen eines Branches behandelt einen schmutzigen Worktree nicht sicher.
• Remote-HEAD ist ein symbolischer Standard-Branch-Zeiger, kein weiterer Remote-Branch.
• Ein Remote-Tracking-Ref ist eine lokale Beobachtung des Remote-Zustands. Das Abrufen ist weder Pull noch Merge.
• Keinen lokalen Branch für jeden Remote-Branch erstellen, es sei denn, der Benutzer fordert lokale Tracking-Branches an.

Beim Erklären des Zustands an den Benutzer diese Fakten klar halten:

• Ein Branch-Ref kann von maximal einem Worktree gleichzeitig ausgecheckt sein (0 oder 1); Git verweigert ein zweites Checkout desselben Branches.
• Das Entfernen eines Worktrees löscht nur sein Verzeichnis und die Registrierung. Branch-Refs und Commits bleiben im gemeinsamen Repository; der Branch wird einfach nicht mehr ausgecheckt und kann später wieder ausgecheckt werden.
• Das Entfernen eines Worktrees verliert nur uncommittete Arbeit (gestaged, ungestaged, nicht versioniert oder Konflikte). „Sauber“ bedeutet, dass das Verlustrisiko null ist, nicht dass der Branch gemergt ist.
• Ein abgetrennter Worktree belegt keinen Branch. Sein HEAD zeigt direkt auf einen Commit, daher führt er nie dazu, dass ein anderer Worktree einen Branch gewinnt oder verliert.
• Branches sind nicht „innerhalb“ des primären Worktrees; nicht ausgecheckte Branches existieren als Referenzen und können jederzeit gewechselt werden.

Eindeutig löschbare Branches definieren

Ein Branch ist eindeutig löschbar (明确删除) nur, wenn sein Inhalt vollständig in den vorgesehenen Basis-Branch (normalerweise main) gemergt ist:

• Durch Abstammung: Die Branch-Spitze ist ein Vorfahre der Basis (git merge-base --is-ancestor BRANCH BASE), also hat sie null Branch-eigene Commits.
• Durch Patch-Äquivalenz: Jeder Branch-eigene Commit hat eine Patch-ID, die bereits in der Basis vorhanden ist (git cherry BASE BRANCH zeigt keine +-Einträge), verifiziert mit git patch-id, niemals aus Commit-Betreffs.

Ein Branch mit einem eindeutigen Commit oder eindeutigem Patch ist nicht eindeutig löschbar, selbst wenn seine Arbeit redundant aussieht, sein Name einem gemergten Branch ähnelt oder seine Spitze durch einen Tag erhalten bleibt. Von Tags archivierte Branches sind möglicherweise nur mit expliziter Bestätigung löschbar, nicht durch diese Regel.

Ein Branch kann stattdessen ersetzt (被取代) sein: Er implementiert eine Funktion, die bereits durch eine weiterentwickelte oder alternative Implementierung in der Basis geliefert wurde. Überprüfe Commit für Commit und Datei für Datei, dass die Basis dieselbe Absicht und dieselben Dateien abdeckt, und dass die verbleibenden Branch-eigenen Zeilen veraltete Überreste und keine fehlende Funktionalität sind. Ersetzte Branches sind durch diese Regel nicht eindeutig löschbar; archiviere die exakte Spitze mit einem Tag, präsentiere die Vergleichsbeweise und lösche nur nach expliziter Benutzerbestätigung.

Bei Remote-Branches müssen die Merge-Inhaltsbeweise gegen die Remote-Basis gelten; Inhalte, die nur in eine nicht gepushte lokale Basis gemergt wurden, qualifizieren nicht. Vor dem Löschen immer die Löschbedingungen in references/decision-matrix.md anwenden.

Mit einer festen Branch-Matrix berichten

Für jeden kanonischen Branch-Namen berichten:

Feld	Erforderliche Bedeutung
Lokal	Ob refs/heads den Branch enthält
Remote	Jede gleichnamige Remote-Ref, nicht nur den Upstream
Sync	Voraus/zurück oder abgewichen gegenüber seinem konfigurierten Upstream
Basis-Beziehung	Basis-eigene und Branch-eigene Commits, Abstammung und Patch-Äquivalenzbeweise
Checkout	Nicht ausgecheckt, primärer Worktree, externer verknüpfter Worktree oder abgetrennt
Worktree-Zustand	Gestaged, ungestaged, nicht versioniert und Konflikte
Funktion	Durch Commits und Diffs nachgewiesene Funktionen oder Fehlerbehebungen
Empfehlung	Behalten, committen, integrieren, archivieren, löschen oder untersuchen; „löschen“ nur für eindeutig löschbare Branches, deren Inhalt vollständig in die Basis gemergt ist

Abgetrennte und entfernbare Worktrees separat auflisten, jeweils mit ihrem HEAD-Hash, ob dieser HEAD ein Vorfahre der lokalen und Remote-Basis ist, sauber/schmutzig Zustand, nicht versionierte Artefakte und einer Empfehlung (sicher zu entfernen / zuerst Recovery-Branch / behalten). Enden mit geordneten Aktionen, unterteilt in sicher jetzt, erfordert Bestätigung und blockiert durch uncommittete oder eindeutige Arbeit. Wenn der Benutzer eine nur-lokale Ansicht möchte oder wenn die Anfrage Bereinigungs-/Löschungsentscheidungen betrifft (整理、删除候选、哪些可以删), immer das farbige lokale Repository-Diagramm unten als Teil des Berichts aufnehmen; nicht auf eine explizite „画图“-Anfrage warten.

Das lokale Repository-Diagramm zeichnen (画出本地的代码库图)

Auf explizite Anfragen wie „画出本地的代码库图“, „本地 Git 状态的图“, „只展示本地分支“ oder „本地优先视图“ auslösen und es automatisch in jeden bereinigungsorientierten Bericht (整理、删除候选、哪些可以删) aufnehmen. Ein lokal-zuerst Branch-Diagramm erstellen:

• Das Audit unmittelbar vor dem Zeichnen erneut ausführen; das Diagramm mit dem Snapshot-Zeitpunkt und den Tip-Hashes beschriften.
• Auf nur lokale Branches beschränken (refs/heads/*). Remote-nur Branches nicht darstellen.
• Jeden Branch markieren, der auch einen gleichnamigen Remote-Branch hat, als 也有远程分支; andernfalls 无远程分支, wobei unterschieden wird zwischen nie gepusht und gepusht dann gelöscht (upstream gone).
• Branches nach Natur gruppieren: langlebig/primär (behalten), temporär (archivieren/löschen nach Bestätigung) und echte Arbeit (behalten und Integration entscheiden).
• Worktree-Zustand an jeden Branch anhängen: nicht ausgecheckt, primärer Worktree oder verknüpfter Worktree (mit Pfad) und sauber/schmutzig Status.
• Bereinigungsbeweise anhängen: eindeutige Commits/Patches, Upstream-Status (inkl. voraus/zurück), schmutzige Dateien und Stashes.
• Wenn ein anderer Prozess während der Sitzung einen Merge-Kandidaten oder Verifizierungs-Ref erstellt hat, diese Branches in eine eigene ausstehende Gruppe setzen; sie melden, aber nicht ändern, bis der externe Prozess abgeschlossen ist.
• Jeden abgetrennten Worktree im Worktree-Subgraphen zeichnen, auch wenn er keinen Branch hat: ihn detached <Pfad> → HEAD <Hash> beschriften, mit sauber/schmutzig Status und dem Vorfahren-Urteil (✔ HEAD 已在 base 中，已合入 oder ✘ 未合入，需恢复分支). Er hat keine Branch-Kante.
• Ein mermaid-Flussdiagramm mit einem Subgraphen pro Gruppe plus einem separaten Worktree-Subgraphen rendern; jeden ausgecheckten Branch mit seinem Worktree verbinden.

Vorlage:

flowchart TB
    subgraph LOCAL["Lokale Branches refs/heads/*"]
        subgraph KEEP["Langlebig/Primär — Behalten"]
            A["main (ahead 25 / behind 4)<br/>✔ 也有远程分支<br/>primary worktree · sauber"]
            B["dev<br/>✔ 也有远程分支 · nicht ausgecheckt<br/>Vorfahre, bereits in main gemergt"]
        end
        subgraph TEMP["Temporär — Archivieren/Löschen nach Bestätigung"]
            C["branch-c (N eindeutige Commits)<br/>✘ 无远程分支 (upstream gone)<br/>linked worktree · schmutzig"]
        end
        subgraph WORK["Echte Arbeit — Behalten und über Integration entscheiden"]
            D["branch-d (N eindeutige Commits)<br/>✘ 无远程分支 (nie gepusht)<br/>linked worktree · sauber"]
        end
        subgraph PENDING["Unterwegs/Externe Verifikation — Nicht anfassen"]
            E["merge-candidate-x (extern erstellt)<br/>✔ 也有远程分支 · linked worktree · sauber"]
        end
    end

    subgraph WT["Worktrees"]
        W1["primary /path/to/repo → main · sauber"]
        W2["linked /path/to/wt1 → branch-d · sauber"]
        W3["linked /path/to/wt2 → branch-c · schmutzig"]
        W4["linked /path/to/wt3 → merge-candidate-x · sauber"]
        W5["detached /path/to/wt4 → HEAD abc1234 · sauber<br/>✔ HEAD 已在 base 中 (bereits gemergt)"]
        W6["detached /path/to/wt5 → HEAD def5678 · schmutzig<br/>✘ 未合入 (Branch für Wiederherstellung benötigt)"]
    end

    A --> W1
    B -- "Vorfahre" --> A
    D --> W2
    C --> W3
    E --> W4

    style LOCAL fill:#e3f2fd,stroke:#1e88e5
    style KEEP fill:#e8f5e9,stroke:#4c8c4c
    style TEMP fill:#fff8e1,stroke:#f9a825
    style WORK fill:#e8eaf6,stroke:#3949ab
    style PENDING fill:#fff3e0,stroke:#fb8c00
    style WT fill:#f3e5f5,stroke:#8e24aa
    style A fill:#fce4ec,stroke:#d81b60

Lokale Commits organisieren

Nur innerhalb des Worktrees arbeiten, der die Änderungen besitzt.

1. Gestagede, ungestagede, nicht versionierte, ignorierte, generierte, große und geheimnisähnliche Dateien prüfen.
2. Generierte Ausgaben, Caches, Screenshots, lokale Logs und Anmeldeinformationen von Produktänderungen trennen. Bei Lockfiles Formatierungsänderungen (z.B. eine pnpm-Versions-Zitierstil-Änderung) von echten Abhängigkeitsänderungen trennen; mit einem Abhängigkeits-Diff verifizieren, bevor wiederhergestellt oder committet wird.
3. Commits nach Verhalten gruppieren, nicht nur nach Verzeichnis. Patch-Staging verwenden, wenn eine Datei mehrere Belange enthält:

git add -p
git diff --cached --check
git diff --cached --stat
git diff --cached

4. Fokussierte Validierung vor jedem logischen Commit und breitere Validierung vor der Integration durchführen.
5. Konventionelle Commit-Nachrichten verwenden. Niemals git add -A blind auf einem gemischten oder unbekannten Worktree anwenden.
6. Status nach jedem Commit erneut prüfen und genau angeben, was uncommittet bleibt.

Branches sicher integrieren

Vor Merge, Rebase, Cherry-Pick, Löschung, Worktree-Entfernung oder Force-ähnlichen Operationen references/decision-matrix.md lesen.

Bevor...

...[für Übersetzung gekürzt]