Git Repository Organizer

O que Git Repository Organizer faz?

Baseie toda conclusão em um snapshot Git atualizado. Trate refs, diretórios com checkout, arquivos não commitados e remotos hospedados como camadas de estado separadas.

Selecione o modo de operação

Inferir o modo mais restrito autorizado pela solicitação:

• Analisar: inspecione e relate sem alterar refs, o índice ou o conteúdo da worktree. Use git ls-remote quando a verdade remota atual for relevante; não faça fetch, merge, pull, commit, rebase, delete, push, crie branches de rastreamento ou troque worktrees apenas para analisar.
• Atualizar: faça fetch de refs de rastreamento remoto, depois relate. Não integre um branch apenas porque refs foram buscadas.
• Commit: organize e faça commit das alterações apenas na worktree nomeada.
• Integrar: faça merge, rebase ou cherry-pick apenas dos branches nomeados através de uma worktree de integração limpa.
• Limpar: remova apenas branches ou worktrees comprovadamente seguras pela matriz de decisão.
• Sincronizar: faça push ou fast-forward apenas dos refs nomeados após atualizar e re-verificar.

Se "整理" ou "同步" não autoriza claramente mutações, faça primeiro um inventário e apresente as operações exatas propostas. Exija confirmação explícita antes de deletar refs remotos, fazer push forçado, reescrever histórico compartilhado, descartar alterações ou remover uma worktree à força.

Construa um snapshot atualizado

1. Localize o repositório real e o diretório Git comum. Nunca presuma que o diretório de trabalho atual é a raiz do repositório.
2. Leia as instruções do projeto, como AGENTS.md, antes de agir.
3. No modo Analisar, verifique as pontas remotas ao vivo sem atualizar as refs de rastreamento remoto:

git ls-remote --symref --heads REMOTE

Declare claramente que as refs de rastreamento remoto locais permanecem em cache e inalteradas. No modo Atualizar, ou imediatamente antes de uma mutação remota explicitamente solicitada, execute:

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

Use no-tags por padrão. Buscar branches e buscar tags são operações separadas; nunca sobrescreva uma tag local conflitante automaticamente.

Fetch atualiza apenas refs de rastreamento remoto. No modo Atualizar, pare aí e compare cada branch local com sua contraparte remota sem integrar nenhum dos lados:

• Nunca faça merge ou pull apenas para fazer uma auditoria parecer atualizada. Um branch local pode legitimamente estar à frente, atrás ou divergente; relate esse estado.
• Nunca faça commit, stash, snapshot, switch, reset, ou toque em uma worktree suja apenas para analisá-la. Registre o estado sujo e trate-o como um bloqueador de mutação.
• Branches locais cujo remoto foi deletado (upstream gone) ou que nunca foram enviados permanecem apenas locais; anote isso explicitamente no relatório.
• Só entre no modo Sincronizar ou Integrar quando o usuário pedir explicitamente essa mutação. Reexecute a auditoria imediatamente antes, opere na worktree que possui o branch e aplique a matriz de decisão.

4. Execute a auditoria read-only fornecida:

python3 scripts/audit_git_state.py --repo /caminho/absoluto --format markdown
python3 scripts/audit_git_state.py --repo /caminho/absoluto --base main --format json

Resolva scripts relativos ao diretório deste skill, não ao repositório alvo.

5. Inspecione commits únicos e arquivos alterados para cada branch que possa ser mantido, integrado ou deletado:

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

Leia diffs representativos antes de descrever a funcionalidade do branch. Não infira função a partir de um nome de branch.

6. Classifique toda worktree destacada antes da limpeza:

git merge-base --is-ancestor HEAD BASE && echo "HEAD já está em BASE"

Verifique tanto contra a base local quanto contra a base remota (por exemplo main e github/main). Um HEAD destacado limpo que é ancestral da base remota está já mesclado — não precisa de reintegração e não precisa de branch de recuperação; é provavelmente um resquício de um script de verificação e pode ser removido com segurança após confirmação. Um HEAD destacado que não é ancestral pode conter commits únicos; crie um branch de recuperação em HEAD antes de qualquer remoção, mesmo que a worktree pareça limpa. Inspecione arquivos não rastreados e separe artefatos gerados (saída de teste, diretórios de build) de trabalho manual antes da remoção forçada.

7. Mantenha a saída proporcional à decisão. Escreva a auditoria JSON e as listas de refs/worktrees/diffs em massa para um arquivo temporário e leia apenas os resumos. Aprofunde-se apenas em branches que são candidatos a integração ou exclusão; não despeje logs por branch e diffs completos no contexto em repositórios grandes.

8. Reexecute a auditoria imediatamente antes do relatório final e antes de cada mutação. Repositórios podem mudar enquanto a análise está em execução; inclua o timestamp do snapshot e os hashes das pontas no resultado. Também fique atento a atividade concorrente: uma ref, worktree ou branch remoto criado ou deletado por outro processo desde o último snapshot (por exemplo um branch candidato a merge) altera o plano; reapresente o plano em vez de agir com alvos obsoletos.

Mantenha o modelo de estado preciso

• O checkout normal do repositório é a worktree primária. Ela aparece em git worktree list mas não é uma worktree linked externa.
• Um branch com checkout em outro caminho é uma worktree linked externa.
• Uma worktree destacada tem um commit com checkout mas nenhum branch. Trate worktrees destacadas sujas como trabalho recuperável, não lixo. Sempre verifique se seu HEAD é ancestral da base (local e remota): se sim e a worktree estiver limpa, está já mesclada e não precisa de reintegração; se não, seus commits podem se tornar inalcançáveis após a remoção e precisam de um branch de recuperação primeiro.
• Uma ref de branch e uma worktree são objetos diferentes. Remover uma worktree linked limpa não deleta seu branch; deletar um branch não trata com segurança uma worktree suja.
• HEAD remoto é um ponteiro simbólico de branch padrão, não outro branch remoto.
• Uma ref de rastreamento remoto é uma observação local do estado remoto. Fazer fetch dela não é puxá-la ou mesclá-la.
• Não crie um branch local para cada branch remoto a menos que o usuário peça branches de rastreamento locais.

Ao explicar o estado ao usuário, mantenha esses fatos claros:

• Uma ref de branch pode estar com checkout em no máximo uma worktree por vez (0 ou 1); Git recusa um segundo checkout do mesmo branch.
• Remover uma worktree deleta apenas seu diretório e registro. Refs de branch e commits permanecem no repositório compartilhado; o branch simplesmente fica sem checkout e pode ser verificado novamente.
• Remover uma worktree perde apenas trabalho não commitado (arquivos staged, unstaged, não rastreados ou em conflito). "Limpo" significa que o risco de perda é zero, não que o branch está mesclado.
• Uma worktree destacada não ocupa nenhum branch. Seu HEAD aponta diretamente para um commit, então nunca faz com que outra worktree ganhe ou perca um branch.
• Branches não estão "dentro" da worktree primária; branches sem checkout existem como refs e podem ser trocados a qualquer momento.

Defina branches claramente deletáveis

Um branch é claramente deletável (明确删除) apenas quando seu conteúdo está totalmente mesclado no branch base pretendido (geralmente main):

• Por ancestralidade: a ponta do branch é ancestral da base (git merge-base --is-ancestor BRANCH BASE), então tem zero commits exclusivos.
• Por equivalência de patch: todo commit exclusivo do branch tem um patch-id equivalente já presente na base (git cherry BASE BRANCH não mostra entradas +), verificado com git patch-id, nunca por assunto de commit.

Um branch com qualquer commit único ou patch único não é claramente deletável, mesmo que seu trabalho pareça redundante, seu nome se assemelhe a um branch mesclado ou sua ponta seja preservada por uma tag. Branches arquivados por tag podem ser deletáveis apenas com confirmação explícita, não por esta regra.

Um branch pode, em vez disso, estar substituído (被取代): implementa uma funcionalidade já entregue por uma implementação evoluída ou alternativa na base. Verifique commit a commit e arquivo a arquivo que a base cobre a mesma intenção e arquivos, e que as linhas restantes exclusivas do branch são remanescentes obsoletos em vez de funcionalidade faltante. Branches substituídos não são claramente deletáveis por esta regra; arquive a ponta exata com uma tag, apresente a evidência de comparação e delete apenas após confirmação explícita do usuário.

Para branches remotos, a evidência de conteúdo mesclado deve ser válida contra a base remota; conteúdo mesclado apenas em uma base local não enviada não se qualifica. Sempre aplique os portões de exclusão em references/decision-matrix.md antes de deletar.

Relato com uma matriz de branches fixa

Para cada nome de branch canônico, relate:

Campo	Significado exigido
Local	Se refs/heads contém o branch
Remoto	Cada ref remoto de mesmo nome, não apenas o upstream
Sincronia	À frente/atrás ou divergente em relação ao seu upstream configurado
Relação com a base	Commits apenas na base e apenas no branch, ancestralidade e evidência de equivalência de patch
Checkout	Sem checkout, worktree primária, worktree linked externa ou destacada
Estado da worktree	Staged, unstaged, não rastreados e conflitos
Função	Funcionalidades ou correções comprovadas por commits e diffs
Recomendação	Manter, commit, integrar, arquivar, deletar ou investigar; use "deletar" apenas para branches claramente deletáveis cujo conteúdo está totalmente mesclado na base

Liste worktrees destacadas e removíveis separadamente, cada uma com seu hash HEAD, se esse HEAD é ancestral da base local e remota, estado limpo/sujo, artefatos não rastreados e uma recomendação (seguro remover / branch de recuperação primeiro / manter). Termine com ações ordenadas divididas em seguro agora, requer confirmação e bloqueado por trabalho não commitado ou único. Quando o usuário quiser uma visualização apenas local, ou quando a solicitação envolver decisões de limpeza/deleção (整理、删除候选、哪些可以删), inclua sempre o diagrama colorido do repositório local abaixo como parte do relatório; não espere por um pedido explícito de "画图".

Desenhe o diagrama do repositório local (画出本地的代码库图)

Dispare em solicitações explícitas como "画出本地的代码库图", "本地 Git 状态的图", "只展示本地分支" ou "本地优先视图", e inclua-o automaticamente em todo relatório orientado a limpeza (整理、删除候选、哪些可以删). Produza um diagrama de branches local-first:

• Reexecute a auditoria imediatamente antes de desenhar; rotule o diagrama com o timestamp do snapshot e hashes das pontas.
• Escopo apenas para branches locais (refs/heads/*). Não renderize branches apenas remotos.
• Marque cada branch que também tem um branch remoto de mesmo nome como 也有远程分支; caso contrário marque 无远程分支, distinguindo nunca enviado de enviado e depois deletado (upstream gone).
• Agrupe branches por natureza: longa duração/principal (manter), temporário (arquivar/deletar após confirmação) e trabalho real (manter e decidir integração).
• Anexe estado da worktree a cada branch: sem checkout, worktree primária ou worktree linked (com seu caminho) e status limpo/sujo.
• Anexe evidência de limpeza: commits/patches únicos, status upstream (incluindo à frente/atrás), arquivos sujos e stashes.
• Se outro processo criou um candidato a merge ou ref de verificação durante a sessão, coloque esses branches em seu próprio grupo pendente; relate-os mas não os modifique até que o processo externo seja resolvido.
• Desenhe toda worktree destacada no subgrafo Worktree mesmo que não tenha branch: rotule-a detached <caminho> → HEAD <hash>, com status limpo/sujo e o veredito de ancestralidade (✔ HEAD 已在 base 中，已合入 ou ✘ 未合入，需恢复分支). Ela não tem aresta de branch.
• Renderize um fluxograma Mermaid com um subgrafo por grupo mais um subgrafo de worktree separado; conecte cada branch com checkout à sua worktree.

Modelo:

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 /caminho/para/repo → main · 干净"]
        W2["linked /caminho/para/wt1 → branch-d · 干净"]
        W3["linked /caminho/para/wt2 → branch-c · 脏"]
        W4["linked /caminho/para/wt3 → merge-candidate-x · 干净"]
        W5["detached /caminho/para/wt4 → HEAD abc1234 · 干净<br/>✔ HEAD 已在 base 中（已合入）"]
        W6["detached /caminho/para/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

Organize commits locais

Trabalhe apenas dentro da worktree que possui as alterações.

1. Inspecione arquivos staged, unstaged, não rastreados, ignorados, gerados, grandes e semelhantes a segredos.
2. Separe saídas geradas, caches, screenshots, logs locais e credenciais de alterações de produto. Para lockfiles, separe re-serialização apenas de formato (por exemplo uma alteração de estilo de citação de versão do pnpm) de alterações reais de dependências; verifique com um diff de dependências antes de restaurar ou commitar.
3. Agrupe commits por comportamento, não apenas por diretório. Use staging de patch quando um arquivo contém múltiplas preocupações:

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

4. Execute validação focada antes de cada commit lógico e validação mais ampla antes da integração.
5. Use mensagens de commit convencionais. Nunca use git add -A cegamente em uma worktree mista ou desconhecida.
6. Re-verifique o status após cada commit e declare exatamente o que permanece não commitado.

Integre branches com segurança

Leia references/decision-matrix.md antes de merge, rebase, cherry-pick, deleção, remoção de worktree ou operações de força.

[continuação truncada para tradução]