using-git-worktrees

Visão geral

O que é using-git-worktrees?

using-git-worktrees é uma skill de fluxo de trabalho do repositório obra/superpowers que orienta você na criação de worktrees Git isoladas para desenvolvimento de features. Ela padroniza como e onde as worktrees são criadas, para que você possa trabalhar com segurança em vários branches ao mesmo tempo sem ficar alternando o tempo todo em um único diretório de trabalho.

Em vez de ter que adivinhar manualmente onde colocar as worktrees ou correr o risco de criar diretórios não rastreados e não ignorados, essa skill codifica um processo claro de seleção e verificação de diretórios. O objetivo é garantir isolamento confiável para o trabalho de implementação, mantendo a árvore principal do projeto limpa.

Para quem é esta skill?

Esta skill foi criada para desenvolvedores que:

• Trabalham em várias features ou correções em paralelo
• Querem uma convenção repetível de Git worktree entre projetos
• Precisam ter confiança de que os diretórios das worktrees estão no lugar certo e não vão poluir commits
• Usam Git pela linha de comando e se sentem à vontade rodando comandos simples de shell

Ela se encaixa especialmente bem em equipes que querem um fluxo de trabalho Git documentado, consistente e uma forma mais segura de criar ambientes temporários ou de longa duração para features.

Quais problemas a using-git-worktrees resolve?

using-git-worktrees ajuda você a evitar problemas comuns ao trabalhar com múltiplos branches:

• Sobrecarga para alternar branches: Trabalhe em vários branches ao mesmo tempo sem precisar ficar fazendo stash e checkout o tempo todo.
• Raiz do projeto bagunçada: Evite espalhar diretórios improvisados e pastas de worktree em lugares aleatórios.
• Commits acidentais de pastas de worktree: O fluxo enfatiza verificar se os diretórios locais de worktree são ignorados antes de criá-los.
• Convenções inconsistentes entre máquinas: Ao verificar diretórios existentes e preferências opcionais em CLAUDE.md, a skill empurra você para um layout padrão por projeto.

Se você já usa Git worktrees com frequência ou quer começar a usá-las com segurança, essa skill oferece um procedimento leve e opinativo.

Quando a using-git-worktrees é uma boa escolha?

Você deve usar using-git-worktrees quando:

• Estiver prestes a começar uma feature que precisa ficar isolada do seu workspace atual.
• Estiver planejando uma implementação com base em um design ou plano existente e quiser uma worktree limpa para executar esse plano.
• Seu repositório já usar diretórios .worktrees ou worktrees e você quiser continuar seguindo essa convenção.

Ela pode ser menos útil se:

• Você sempre trabalha em apenas um branch por vez e não precisa de múltiplas cópias de trabalho.
• Você já tem uma ferramenta interna rígida e automatizada que gerencia worktrees de outra forma.

Nos demais casos, adotar o fluxo de using-git-worktrees tende a deixar seu workflow Git mais previsível e seguro.

Como usar

Instalação e configuração

Para adicionar a skill using-git-worktrees ao seu ambiente, instale a partir do repositório obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Depois da instalação:

1. Abra o arquivo skills/using-git-worktrees/SKILL.md no checkout do repositório.
2. Leia tudo de ponta a ponta uma vez para entender os passos de seleção de diretório e verificação de segurança.
3. Garanta que você está trabalhando dentro de um repositório Git onde se sente confortável em criar diretórios adicionais de worktree.

Você não precisa de dependências extras além do Git e de um shell capaz de rodar os comandos mostrados na descrição da skill.

Fluxo principal: iniciando trabalho de feature isolado

Quando você for começar o trabalho em uma nova feature e quiser um workspace isolado, siga o fluxo de alto nível definido por using-git-worktrees:

1. Anuncie o fluxo de trabalho (para você e para quaisquer assistentes ou ferramentas):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. Defina o diretório da worktree usando o processo de seleção de diretório (veja a próxima seção). Isso evita espalhar worktrees em caminhos arbitrários.

3. Rode a verificação de segurança adequada ao tipo de diretório escolhido (local ao projeto vs. global). Este passo é essencial para evitar commits acidentais de pastas de worktree.

4. Crie a Git worktree para o branch que você precisa. Por exemplo:

   git worktree add <path-to-worktree> <branch-name>
   

5. Entre na nova worktree e faça seu trabalho de implementação ali, mantendo sua cópia de trabalho original limpa e disponível para code review, correções rápidas ou outras tarefas.

Repita esse fluxo sempre que começar uma feature, spike ou experimento que não deve interferir com o diretório de trabalho atual.

Processo de seleção de diretório

using-git-worktrees define uma ordem estruturada de seleção de diretório para que você sempre saiba onde as worktrees devem ficar e não precise rediscutir isso a cada vez.

1. Dar preferência a diretórios de worktree existentes

A partir da raiz do repositório, procure diretórios preferenciais de worktree nesta ordem de prioridade:

ls -d .worktrees 2>/dev/null     # Preferido (oculto)
ls -d worktrees 2>/dev/null      # Alternativo

• Se .worktrees existir, use-o.
• Se .worktrees não existir, mas worktrees existir, use worktrees.
• Se nenhum existir, siga para o próximo passo.

Essa regra mantém seu fluxo de trabalho consistente com escolhas anteriores no mesmo projeto.

2. Verificar preferências de projeto em CLAUDE.md

Se nenhum diretório padrão de worktree estiver presente, procure uma preferência documentada em CLAUDE.md na raiz do projeto:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

Se CLAUDE.md especificar uma convenção de diretório de worktree, use essa convenção sem fazer mais perguntas. Isso permite que o projeto documente centralmente o layout de worktree preferido.

3. Perguntar e escolher um novo local quando não houver preferência

Se não houver diretório existente nem preferência documentada em CLAUDE.md, escolha explicitamente onde as novas worktrees devem ficar. A skill sugere oferecer para você (ou para a equipe) uma escolha clara:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• Opção 1: .worktrees/ mantém as worktrees junto ao projeto, ocultas por padrão e fáceis de descobrir no repo.
• Opção 2: ~/.config/superpowers/worktrees/<project-name>/ centraliza as worktrees por projeto fora da raiz do repo, o que pode ser útil se você quiser que o diretório de trabalho Git se mantenha visualmente enxuto.

Depois de escolher uma opção, continue usando esse mesmo local para o mesmo projeto para evitar fragmentação.

Verificação de segurança antes de criar uma worktree

A skill using-git-worktrees enfatiza checagens de segurança, principalmente ao usar diretórios locais ao projeto que ficam dentro do repositório Git.

Verificando se diretórios locais ao projeto são ignorados

Para diretórios locais como .worktrees ou worktrees, verifique se eles são ignorados pelo Git antes de criar worktrees dentro deles. A skill trata isso como uma condição MUST.

No mínimo, você deve:

• Confirmar que .worktrees ou worktrees aparece em algum arquivo de ignore relevante (.gitignore, .git/info/exclude ou arquivos globais de ignore), e
• Usar git check-ignore para garantir que o Git realmente ignora o diretório na configuração atual.

Um padrão típico é rodar git check-ignore apontando para o caminho do diretório e confirmar que o Git o trata como ignorado, respeitando configurações de ignore locais, globais e de sistema.

Se o diretório não estiver ignorado:

• Adicione-o a um arquivo de ignore apropriado, faça commit da regra se ela fizer sentido no repositório, e
• Rode a checagem novamente antes de criar qualquer worktree naquele local.

Isso reduz o risco de a infraestrutura das suas worktrees acabar staged ou commitada por engano.

Usando locais globais com segurança

Se você escolher a opção de diretório global (por exemplo, em ~/.config/superpowers/worktrees/), os diretórios ficam fora do repositório e não são rastreados pelo Git. Nesse caso, o requisito de ignore é bem menos crítico, mas ainda assim vale garantir que:

• O caminho seja estável entre máquinas (ou documentado para o time).
• Você tenha espaço em disco suficiente para múltiplas worktrees completas.

Aplicar essas verificações de forma consistente mantém o histórico Git focado em mudanças de código-fonte, e não em artefatos de tooling.

Adaptando a skill ao seu fluxo de trabalho

A skill using-git-worktrees é deliberadamente leve e focada no repositório. Para integrá-la ao seu fluxo mais amplo:

• Documente sua escolha final de diretório de worktree na documentação de contribuição ou onboarding do projeto.
• Considere adicionar uma seção curta em CLAUDE.md descrevendo como sua equipe usa Git worktrees.
• Empacote os passos de seleção de diretório e verificação em seus próprios scripts de shell, se quiser um setup de um comando só, mantendo as regras originais como fonte de verdade.

A skill foi pensada como uma implementação de referência clara, que você pode seguir como está ou adaptar com cuidado ao seu ambiente.

FAQ

Qual é o principal benefício de using-git-worktrees em relação a checkouts Git normais?

using-git-worktrees facilita trabalhar em vários branches em paralelo criando diretórios de trabalho adicionais (worktrees) que compartilham o mesmo histórico Git. Em vez de ficar repetindo checkout e stash em um único diretório, você mantém cada feature ou correção em seu próprio workspace isolado, guiado por um processo consistente de seleção de diretório e segurança.

Como instalar a skill using-git-worktrees?

Instale a skill a partir do repositório obra/superpowers usando:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Depois da instalação, abra skills/using-git-worktrees/SKILL.md no seu checkout local para seguir o fluxo detalhado.

Preciso mudar todo o meu fluxo Git para usar esta skill?

Você não precisa reformular todo o seu fluxo. using-git-worktrees se concentra em como você inicia e gerencia workspaces isolados. Você pode continuar fazendo commit, rebase e push como sempre; a skill basicamente padroniza onde e como você cria worktrees e garante que elas sejam posicionadas com segurança.

Posso usar using-git-worktrees em qualquer repositório Git?

Sim, desde que o repositório seja compatível com Git worktrees em geral. A skill se baseia em comandos Git padrão e utilitários de shell. Para melhores resultados, rode as verificações de diretório a partir da raiz do repositório e siga as recomendações de ignore para qualquer diretório de worktree local ao projeto.

E se meu projeto já tiver outra convenção de worktree?

Se seu projeto já usa .worktrees, worktrees ou uma convenção documentada em CLAUDE.md, using-git-worktrees vai naturalmente respeitar essa preferência por meio das regras de seleção de diretório. Se a convenção for totalmente diferente, você ainda pode aproveitar os princípios (escolha clara de diretório e checagens de segurança), apontando-os para o layout de diretórios que você já utiliza.

using-git-worktrees é adequada para projetos grandes ou de longa duração?

Sim. A skill é particularmente útil em projetos grandes, onde vários branches de longa duração são comuns. Sua seleção estruturada de diretórios e o foco em regras de ignore ajudam a manter o repositório organizado ao longo do tempo, mesmo quando você acumula muitas worktrees para trabalhos em andamento.

Quando eu deveria evitar usar using-git-worktrees?

Talvez você não precise dessa skill se raramente trabalha em mais de um branch por vez ou se sua equipe já utiliza outra ferramenta dedicada que gerencia worktrees e impõe suas próprias convenções de diretório. Nesses casos, a estrutura adicional de using-git-worktrees pode não trazer benefício suficiente para justificar uma mudança de hábito.

Onde posso ver a definição original dessa skill?

A definição autoritativa de using-git-worktrees está no arquivo SKILL.md dentro do diretório skills/using-git-worktrees no repositório obra/superpowers no GitHub. Consulte esse arquivo para a descrição mais precisa e atualizada do comportamento.