Usando Git Worktrees

Visão Geral

Git worktrees criam espaços de trabalho isolados que compartilham o mesmo repositório, permitindo trabalhar em vários branches simultaneamente sem alternar.

Princípio central: Seleção sistemática de diretório + verificação de segurança = isolamento confiável.

Anúncio no início: "Estou usando a habilidade using-git-worktrees para configurar um espaço de trabalho isolado."

Processo de Seleção de Diretório

Siga esta ordem de prioridade:

1. Verificar Diretórios Existentes

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

Se encontrado: Use esse diretório. Se ambos existirem, .worktrees vence.

2. Verificar CLAUDE.md

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

Se a preferência estiver especificada: Use-a sem perguntar.

3. Perguntar ao Usuário

Se nenhum diretório existir e nenhuma preferência em CLAUDE.md:

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?

Verificação de Segurança

Para Diretórios Locais do Projeto (.worktrees ou worktrees)

DEVE verificar se o diretório está ignorado antes de criar o worktree:

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

Se NÃO estiver ignorado:

De acordo com a regra de Jesse "Corrija coisas quebradas imediatamente":

1. Adicione a linha apropriada a .gitignore
2. Commite a alteração
3. Prossiga com a criação do worktree

Por que é crítico: Evita commitar acidentalmente o conteúdo do worktree no repositório.

Para Diretório Global (~/.config/superpowers/worktrees)

Nenhuma verificação de .gitignore é necessária - está completamente fora do projeto.

Passos de Criação

1. Detectar Nome do Projeto

project=$(basename "$(git rev-parse --show-toplevel)")

2. Criar Worktree

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Executar Configuração do Projeto

Detecta e executa automaticamente a configuração apropriada:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. Verificar Linha de Base Limpa

Execute testes para garantir que o worktree comece limpo:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

Se os testes falharem: Relate as falhas, pergunte se deve prosseguir ou investigar.

Se os testes passarem: Relate que está pronto.

5. Relatar Localização

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Referência Rápida

Erros Comuns

Pular a verificação de ignorar

• Problema: O conteúdo do worktree é rastreado, polui o status do git
• Correção: Sempre use git check-ignore antes de criar um worktree local do projeto

Assumir a localização do diretório

• Problema: Cria inconsistência, viola convenções do projeto
• Correção: Siga a prioridade: existente > CLAUDE.md > perguntar

Prosseguir com testes falhando

• Problema: Não é possível distinguir novos bugs de problemas pré-existentes
• Correção: Relate falhas, obtenha permissão explícita para prosseguir

Comandos de configuração fixos (hardcoded)

• Problema: Quebra em projetos que usam ferramentas diferentes
• Correção: Detecte automaticamente a partir de arquivos do projeto (package.json, etc.)

Exemplo de Fluxo de Trabalho

Você: Estou usando a habilidade using-git-worktrees para configurar um espaço de trabalho isolado.

[Verifica .worktrees/ - existe]
[Verifica se está ignorado - git check-ignore confirma que .worktrees/ está ignorado]
[Cria worktree: git worktree add .worktrees/auth -b feature/auth]
[Executa npm install]
[Executa npm test - 47 passando]

Worktree pronto em /Users/jesse/myproject/.worktrees/auth

…