zhifengjiang/git-repo-organizer

Organisateur de dépôt Git

Fondez chaque conclusion sur un instantané Git frais. Traitez les refs, les répertoires extraits, les fichiers non commités et les dépôts distants hébergés comme des couches d'état distinctes.

Sélectionnez le mode de fonctionnement

Déduisez le mode le plus restreint autorisé par la demande :

• Analyser : inspecter et rapporter sans modifier les refs, l'index ou le contenu du worktree. Utilisez git ls-remote lorsque la vérité distante actuelle est importante ; ne fetchez pas, ne mergez pas, ne pushez pas, ne commitez pas, ne rebasez pas, ne supprimez pas, ne créez pas de branches de suivi ou ne changez pas de worktree simplement pour analyser.
• Rafraîchir : fetcher les refs de suivi distant, puis rapporter. N'intégrez pas une branche simplement parce que les refs ont été fetchées.
• Commiter : organiser et commiter les modifications uniquement dans le worktree nommé.
• Intégrer : merger, rebaser ou cherry-picker uniquement les branches nommées via un worktree d'intégration propre.
• Nettoyer : supprimer uniquement les branches ou worktrees jugés sûrs selon la matrice de décision.
• Synchroniser : pusher ou fast-forward uniquement les refs nommées après les avoir rafraîchies et revérifiées.

Si "整理" ou "同步" n'autorise pas clairement les mutations, dressez d'abord un inventaire et présentez les opérations exactes proposées. Exigez une confirmation explicite avant de supprimer des refs distantes, de forcer un push, de réécrire l'historique partagé, de jeter des modifications ou de forcer la suppression d'un worktree.

Construire un instantané actuel

1. Localisez le vrai dépôt et le répertoire Git commun. Ne supposez jamais que le répertoire de travail de l'invite est la racine du dépôt.
2. Lisez les instructions du projet comme AGENTS.md avant d'agir.
3. En mode Analyser, vérifiez les tips distants en direct sans mettre à jour les refs de suivi distant :

git ls-remote --symref --heads REMOTE

Indiquez clairement que les refs de suivi distant locales restent en cache et inchangées. En mode Rafraîchir, ou immédiatement avant une mutation distante explicitement demandée, exécutez :

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

Utilisez no-tags par défaut. Fetch des branches et fetch des tags sont des opérations séparées ; ne remplacez jamais un tag local conflictuel automatiquement.

Le fetch met à jour uniquement les refs de suivi distant. En mode Rafraîchir, arrêtez-vous là et comparez chaque branche locale avec sa contrepartie distante sans intégrer aucun côté :

• Ne mergez ou ne pullez jamais simplement pour rendre un audit actuel. Une branche locale peut légitimement être en avance, en retard ou avoir divergé ; rapportez cet état.
• Ne commitez, stashez, instantanément, ne basculez, ne réinitialisez ou ne touchez en aucune façon un worktree sale simplement pour l'analyser. Enregistrez l'état sale et traitez-le comme un bloqueur de mutation.
• Les branches locales dont le remote a été supprimé (upstream gone) ou qui n'ont jamais été poussées restent locales uniquement ; notez-le explicitement dans le rapport.
• N'entrez en mode Synchroniser ou Intégrer que lorsque l'utilisateur demande explicitement cette mutation. Réexécutez l'audit immédiatement avant, opérez dans le worktree qui possède la branche et appliquez la matrice de décision.

4. Exécutez l'audit en lecture seule fourni :

python3 scripts/audit_git_state.py --repo /chemin/absolu --format markdown
python3 scripts/audit_git_state.py --repo /chemin/absolu --base main --format json

Résolvez les scripts par rapport à ce répertoire de compétence, pas au dépôt cible.

5. Inspectez les commits uniques et les fichiers modifiés pour chaque branche qui pourrait être conservée, intégrée ou supprimée :

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

Lisez les diffs représentatifs avant de décrire la fonctionnalité de la branche. N'inférez pas la fonction à partir d'un nom de branche.

6. Classez chaque worktree détaché avant le nettoyage :

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

Vérifiez à la fois la base locale et la base distante (par exemple main et github/main). Un HEAD détaché et propre qui est un ancêtre de la base distante est déjà mergé — il n'a pas besoin de réintégration et ne nécessite pas de branche de récupération ; il s'agit probablement d'un vestige d'un script de vérification et peut être supprimé en toute sécurité après confirmation. Un HEAD détaché qui n'est pas un ancêtre peut contenir des commits uniques ; créez une branche de récupération sur HEAD avant toute suppression, même si le worktree semble propre. Inspectez les fichiers non suivis et séparez les artefacts générés (sorties de test, répertoires de build) du travail manuscrit avant la suppression forcée.

7. Gardez la sortie proportionnée à la décision. Écrivez l'audit JSON et les listings en masse des refs/worktrees/diffs dans un fichier temporaire et ne lisez que les résumés. Plongez dans les diffs uniquement pour les branches qui sont candidates à l'intégration ou à la suppression ; ne déversez pas dans le contexte les journaux par branche et les diffs complets dans les grands dépôts.

8. Réexécutez l'audit immédiatement avant le rapport final et avant chaque mutation. Les dépôts peuvent changer pendant l'analyse ; incluez l'heure de l'instantané et les hachages de tip dans le résultat. Surveillez également l'activité concurrente : une ref, un worktree ou une branche distante créée ou supprimée par un autre processus depuis le dernier instantané (par exemple une branche candidate à la fusion) modifie le plan ; représentez le plan au lieu d'agir sur des cibles obsolètes.

Gardez le modèle d'état précis

• Le checkout normal du dépôt est le worktree principal. Il apparaît dans git worktree list mais n'est pas un worktree lié externe.
• Une branche extraite sous un autre chemin est un worktree lié externe.
• Un worktree détaché a un commit extrait mais pas de branche. Traitez les worktrees détachés sales comme du travail récupérable, pas comme des déchets. Vérifiez toujours si son HEAD est un ancêtre de la base (locale et distante) : si oui et le worktree est propre, il est déjà mergé et n'a pas besoin de réintégration ; si non, ses commits pourraient devenir inaccessibles après suppression et nécessitent d'abord une branche de récupération.
• Une ref de branche et un worktree sont des objets différents. La suppression d'un worktree lié propre ne supprime pas sa branche ; la suppression d'une branche ne gère pas en toute sécurité un worktree sale.
• Le HEAD distant est un pointeur symbolique de branche par défaut, pas une autre branche distante.
• Une ref de suivi distant est une observation locale de l'état distant. La fetcher n'est pas la puller ou la merger.
• Ne créez pas une branche locale pour chaque branche distante sauf si l'utilisateur demande des branches de suivi locales.

Lorsque vous expliquez l'état à l'utilisateur, gardez ces faits clairs :

• Une ref de branche peut être extraite par au plus un worktree à la fois (0 ou 1) ; Git refuse un deuxième checkout de la même branche.
• La suppression d'un worktree ne supprime que son répertoire et son enregistrement. Les refs de branche et les commits restent dans le dépôt partagé ; la branche devient simplement non extraite et peut être extraite à nouveau plus tard.
• La suppression d'un worktree ne perd que le travail non commité (fichiers staged, unstaged, non suivis ou en conflit). "Propre" signifie que ce risque de perte est nul, pas que la branche est mergée.
• Un worktree détaché n'occupe aucune branche. Son HEAD pointe directement sur un commit, donc il ne fait jamais gagner ou perdre une branche à un autre worktree.
• Les branches ne sont pas "à l'intérieur" du worktree principal ; les branches non extraites existent en tant que refs et peuvent être basculées à tout moment.

Définir les branches clairement supprimables

Une branche est clairement supprimable (明确删除) uniquement lorsque son contenu est entièrement mergé dans la branche de base prévue (généralement main) :

• Par ascendance : le tip de la branche est un ancêtre de la base (git merge-base --is-ancestor BRANCHE BASE), elle n'a donc aucun commit unique.
• Par équivalence de patch : chaque commit unique de la branche a un équivalent de patch-id déjà présent dans la base (git cherry BASE BRANCHE ne montre aucune entrée +), vérifié avec git patch-id, jamais à partir sujets de commit.

Une branche avec un commit unique ou un patch unique n'est pas clairement supprimable, même si son travail semble redondant, son nom ressemble à une branche mergée ou son tip est préservé par un tag. Les branches archivées par tag peuvent être supprimables uniquement avec confirmation explicite, pas par cette règle.

Une branche peut plutôt être remplacée (被取代) : elle implémente une fonctionnalité déjà livrée par une implémentation évoluée ou alternative dans la base. Vérifiez commit par commit et fichier par fichier que la base couvre la même intention et les mêmes fichiers, et que les lignes restantes uniques à la branche sont des vestiges obsolètes plutôt que des fonctionnalités manquantes. Les branches remplacées ne sont pas clairement supprimables par cette règle ; archivez le tip exact avec un tag, présentez les preuves de comparaison et supprimez uniquement après confirmation explicite de l'utilisateur.

Pour les branches distantes, les preuves de contenu mergé doivent tenir contre la base distante ; le contenu mergé uniquement dans une base locale non poussée ne se qualifie pas. Appliquez toujours les portes de suppression dans references/decision-matrix.md avant de supprimer.

Rapporter avec une matrice de branche fixe

Pour chaque nom de branche canonique, rapportez :

Champ	Signification requise
Local	Si refs/heads contient la branche
Distant	Chaque ref distante du même nom, pas seulement l'upstream
Sync	En avance/en retard ou divergé par rapport à son upstream configuré
Relation de base	Commits uniquement dans la base et uniquement dans la branche, ascendance et preuves d'équivalence de patch
Checkout	Non extraite, worktree principal, worktree lié externe, ou détaché
État du worktree	Staged, unstaged, non suivis et conflits
Fonction	Fonctionnalités ou correctifs prouvés par les commits et les diffs
Recommandation	Garder, commiter, intégrer, archiver, supprimer ou enquêter ; utiliser "supprimer" uniquement pour les branches clairement supprimables dont le contenu est entièrement mergé dans la base

Listez les worktrees détachés et élagables séparément, chacun avec son hachage HEAD, si ce HEAD est un ancêtre de la base locale et distante, l'état propre/sale, les artefacts non suivis et une recommandation (sûr à supprimer / branche de récupération d'abord / garder). Terminez par des actions ordonnées divisées en sûr maintenant, nécessite confirmation, et bloqué par du travail non commité ou unique. Lorsque l'utilisateur veut une vue locale uniquement, ou lorsque la demande implique des décisions de nettoyage/suppression (整理、删除候选、哪些可以删), incluez toujours le diagramme de dépôt local en couleur ci-dessous dans le rapport ; n'attendez pas une demande explicite de "画图".

Dessiner le diagramme du dépôt local (画出本地的代码库图)

Déclenchez sur des demandes explicites comme "画出本地的代码库图", "本地 Git 状态的图", "只展示本地分支", ou "本地优先视图", et incluez-le automatiquement dans chaque rapport orienté nettoyage (整理、删除候选、哪些可以删). Produisez un diagramme de branche local d'abord :

• Réexécutez l'audit immédiatement avant de dessiner ; étiquetez le diagramme avec l'heure de l'instantané et les hachages de tip.
• Limitez la portée aux branches locales uniquement (refs/heads/*). Ne rendez pas les branches distantes uniquement.
• Marquez chaque branche qui a également une branche distante du même nom comme 也有远程分支 ; sinon marquez 无远程分支, en distinguant jamais poussé de poussé puis supprimé (upstream gone).
• Groupez les branches par nature : longue durée/principales (garder), temporaires (archiver/supprimer après confirmation), et travail réel (garder et décider l'intégration).
• Attachez l'état du worktree à chaque branche : non extrait, worktree principal, ou worktree lié (avec son chemin), et état propre/sale.
• Attachez les preuves de nettoyage : commits/patches uniques, statut upstream (y compris en avance/en retard), fichiers sales et stashes.
• Si un autre processus a créé un candidat à la fusion ou une ref de vérification pendant la session, mettez ces branches dans leur propre groupe en attente ; rapportez-les mais ne les modifiez pas jusqu'à ce que le processus externe se résolve.
• Dessinez chaque worktree détaché dans le sous-graphe Worktree même s'il n'a pas de branche : étiquetez-le detached <chemin> → HEAD <hachage>, avec l'état propre/sale et le verdict d'ascendance (✔ HEAD 已在 base 中，已合入 ou ✘ 未合入，需恢复分支). Il n'a pas d'arête de branche.
• Rendez un seul organigramme mermaid avec un sous-graphe par groupe plus un sous-graphe worktree séparé ; connectez chaque branche extraite à son worktree.

Modèle :

flowchart TB
    subgraph LOCAL["本地分支 refs/heads/*"]
        subgraph KEEP["长期/主要 —— 保留"]
            A["main（ahead 25 · behind 4）<br/>✔ 也有远程分支<br/>primary worktree · 干净"]
            B["dev<br/>✔ 也有远程分支 · 未检出<br/>祖先，已完全合入 main"]
        end
        subgraph TEMP["临时性 —— 确认后归档/删除"]
            C["branch-c（N 个独有提交）<br/>✘ 无远程分支（upstream gone）<br/>linked worktree · 脏"]
        end
        subgraph WORK["有实际工作 —— 保留并决定是否合入"]
            D["branch-d（N 个独有提交）<br/>✘ 无远程分支（从未推送）<br/>linked worktree · 干净"]
        end
        subgraph PENDING["在途/外部验证 —— 不动"]
            E["merge-candidate-x（外部创建）<br/>✔ 也有远程分支 · linked worktree · 干净"]
        end
    end

    subgraph WT["Worktree"]
        W1["primary /chemin/vers/depot → main · 干净"]
        W2["linked /chemin/vers/wt1 → branch-d · 干净"]
        W3["linked /chemin/vers/wt2 → branch-c · 脏"]
        W4["linked /chemin/vers/wt3 → merge-candidate-x · 干净"]
        W5["detached /chemin/vers/wt4 → HEAD abc1234 · 干净<br/>✔ HEAD 已在 base 中（已合入）"]
        W6["detached /chemin/vers/wt5 → HEAD def5678 · 脏<br/>✘ 未合入（需恢复分支）"]
    end

    A --> W1
    B -- "祖先" --> 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

Organiser les commits locaux

Travaillez uniquement à l'intérieur du worktree qui possède les modifications.

1. Inspectez les fichiers staged, unstaged, non suivis, ignorés, générés, volumineux et semblables à des secrets.
2. Séparez les sorties générées, les caches, les captures d'écran, les journaux locaux et les identifiants des modifications du produit. Pour les fichiers de verrouillage, séparez la re-sérialisation de format uniquement (par exemple un changement de style de guillemet de version pnpm) des modifications réelles des dépendances ; vérifiez avec un diff de dépendances avant de restaurer ou de commiter.
3. Groupez les commits par comportement, pas seulement par répertoire. Utilisez le staging par patch lorsqu'un fichier contient plusieurs préoccupations :

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

4. Exécutez une validation ciblée avant chaque commit logique et une validation plus large avant l'intégration.
5. Utilisez des messages de commit conventionnels. N'utilisez jamais git add -A aveuglément sur un worktree mixte ou non familier.
6. Revérifiez le statut après chaque commit et indiquez exactement ce qui reste non commité.

Intégrer les branches en toute sécurité

Lisez references/decision-matrix.md avant merge, rebase, cherry-pick, suppression, suppression de worktree ou opérations de force-like.

Bef

…

[truncated for translation]