| name | git-worktree-manager |
| description | Gerenciador de Git Worktree — executa trabalho paralelo em funcionalidades com segurança usando worktrees Git, com isolamento de branch, alocação de porta, sincronização de ambiente e limpeza padronizados. |
| agents | ["claude-code"] |
Git Worktree Manager
Nível: PODEROSO
Categoria: Engenharia
Domínio: Desenvolvimento Paralelo e Isolamento de Branch
Visão Geral
Use esta skill para executar trabalho paralelo em funcionalidades com segurança usando Git worktrees. Ela padroniza isolamento de branch, alocação de porta, sincronização de ambiente e limpeza para que cada worktree se comporte como um app local independente sem interferir em outro branch.
Esta skill é otimizada para workflows multi-agente onde cada agente ou sessão de terminal possui um worktree.
Capacidades Principais
- Criar worktrees a partir de branches novos ou existentes com nomenclatura determinística
- Alocar automaticamente portas não conflitantes por worktree e persistir atribuições
- Copiar arquivos de ambiente locais (
.env*) do repo principal para o novo worktree
- Opcionalmente instalar dependências com base na detecção de lockfile
- Detectar worktrees obsoletos e mudanças não commitadas antes da limpeza
- Identificar branches mergeados e remover worktrees desatualizados com segurança
Quando Usar
- Você precisa de 2+ branches concorrentes abertos localmente
- Você quer servidores de dev isolados para funcionalidade, hotfix e validação de PR
- Você está trabalhando com múltiplos agentes que não devem compartilhar um branch
- Seu branch atual está bloqueado mas você precisa enviar uma correção rápida agora
- Você quer limpeza repetível em vez de operações
rm -rf ad-hoc
Workflows Principais
1. Criar um Worktree Totalmente Preparado
- Escolha um nome de branch e nome de worktree.
- Execute o script do gerenciador (cria o branch se estiver ausente).
- Revise o mapa de porta gerado.
- Inicie o app usando as portas alocadas.
python scripts/worktree_manager.py \
--repo . \
--branch feature/new-auth \
--name wt-auth \
--base-branch main \
--install-deps \
--format text
Se você usar entrada de automação JSON:
cat config.json | python scripts/worktree_manager.py --format json
python scripts/worktree_manager.py --input config.json --format json
2. Executar Sessões Paralelas
Convenção recomendada:
- Repo principal: branch de integração (
main/develop) na porta padrão
- Worktree A: branch de funcionalidade + portas com offset
- Worktree B: branch de hotfix + próximo offset
Cada worktree contém .worktree-ports.json com as portas atribuídas.
3. Limpeza com Verificações de Segurança
- Escaneie todos os worktrees e idade obsoleta.
- Inspecione árvores sujas e status de merge do branch.
- Remova apenas worktrees mergeados + limpos, ou force explicitamente.
python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text
4. Padrão Docker Compose
Use arquivos de override por worktree mapeados das portas alocadas. O script produz um mapa de porta determinístico; aplique-o ao docker-compose.worktree.yml.
Veja docker-compose-patterns.md para templates concretos.
5. Estratégia de Alocação de Porta
A estratégia padrão é base + (índice * stride) com verificações de colisão:
- App:
3000
- Postgres:
5432
- Redis:
6379
- Stride:
10
Veja port-allocation-strategy.md para a estratégia completa e casos extremos.
Interfaces dos Scripts
python scripts/worktree_manager.py --help
- Criar/listar worktrees
- Alocar/persistir portas
- Copiar arquivos
.env*
- Instalação opcional de dependências
python scripts/worktree_cleanup.py --help
- Detecção de obsoleto por idade
- Detecção de estado sujo
- Detecção de branch mergeado
- Remoção segura opcional
Ambas as ferramentas suportam stdin JSON e modo de arquivo --input para pipelines de automação.
Armadilhas Comuns
- Criar worktrees dentro do diretório do repo principal
- Reutilizar
localhost:3000 em todos os branches
- Compartilhar uma URL de banco de dados entre branches de funcionalidade isolados
- Remover um worktree com mudanças não commitadas
- Esquecer de podar metadados antigos após exclusão de branch
- Assumir status de merge sem verificar contra o branch alvo
Melhores Práticas
- Um branch por worktree, um agente por worktree.
- Mantenha os worktrees de curta duração; remova após o merge.
- Use um padrão de nomenclatura determinístico (
wt-<tópico>).
- Persista mapeamentos de porta em arquivo, não em memória ou notas de terminal.
- Execute varredura de limpeza semanalmente em repos ativos.
- Use
--format json para fluxos de máquina e --format text para revisão humana.
- Nunca force-remova worktrees sujos a menos que as mudanças sejam intencionalmente descartadas.
Lista de Verificação de Validação
Antes de declarar a configuração completa:
git worktree list mostra caminho + branch esperado..worktree-ports.json existe e contém portas únicas.- Arquivos
.env copiados com sucesso (se presentes no repo de origem).
- O comando de instalação de dependências sai com código
0 (se habilitado).
- A varredura de limpeza não reporta árvores sujas obsoletas não intencionais.
Referências
Matriz de Decisão
Use este seletor rápido antes de criar um novo worktree:
- Precisa de dependências isoladas e portas de servidor -> crie um novo worktree
- Precisa apenas de uma revisão de diff local rápida -> fique na árvore atual
- Precisa de hotfix enquanto o branch de funcionalidade está sujo -> crie worktree de hotfix dedicado
- Precisa de branch de reprodução efêmero para triagem de bug -> crie worktree temporário e faça limpeza no mesmo dia
Lista de Verificação Operacional
Antes da Criação
- Confirme que o repo principal tem baseline limpo ou commits WIP intencionais.
- Confirme a convenção de nomenclatura do branch alvo.
- Confirme que o branch base necessário existe (
main/develop).
- Confirme que nenhuma porta local reservada já está ocupada por serviços fora do repo.
Após a Criação
- Verifique se o branch
git status corresponde ao branch esperado.
- Verifique se
.worktree-ports.json existe.
- Verifique se o app inicializa na porta de app alocada.
- Verifique se os endpoints de BD e cache apontam para portas isoladas.
Antes da Remoção
- Verifique se o branch tem upstream e está mergeado quando pretendido.
- Verifique se nenhum arquivo não commitado permanece.
- Verifique se nenhum container/processo em execução depende deste caminho de worktree.
Integração com CI e Equipe
- Use nomenclatura de caminho de worktree que mapeie para o ID da tarefa (
wt-1234-auth).
- Inclua o caminho do worktree no título do terminal para evitar commits na janela errada.
- Em configurações automatizadas, persista metadados de criação em artefatos/logs de CI.
- Acione relatório de limpeza em jobs agendados e poste resumo no canal da equipe.
Recuperação de Falha
- Se
git worktree add falhar devido ao caminho existente: inspecione o caminho, não sobrescreva.
- Se a instalação de dependências falhar: mantenha o worktree criado, marque o status e continue a recuperação manual.
- Se a cópia de env falhar: continue com aviso e lista explícita de arquivos ausentes.
- Se a alocação de porta colidir com serviço externo: reexecute com portas base ajustadas.
