git-worktree-manager

Visão geral da skill git-worktree-manager

O que git-worktree-manager faz

git-worktree-manager é uma skill de engenharia para operar vários Git worktrees locais sem conflitos de branch, porta, ambiente ou limpeza. Ela combina orientações operacionais com scripts auxiliares em Python que criam worktrees preparados, atribuem portas determinísticas, copiam arquivos de ambiente locais, podem instalar dependências opcionalmente e revisam worktrees antigos antes da remoção.

Use esta skill quando comandos comuns de git worktree não forem suficientes porque cada branch precisa se comportar como uma aplicação executável separada.

Melhor uso em fluxos Git paralelos

O perfil ideal é uma pessoa desenvolvedora, tech lead ou operadora de agentes de código que mantém duas ou mais branches abertas ao mesmo tempo: desenvolvimento de features, hotfixes, revisão de PRs, testes de migração ou implementação com múltiplos agentes. git-worktree-manager for Git Workflows é especialmente útil quando cada agente ou sessão de terminal deve ficar responsável por uma branch e um runtime isolado, em vez de compartilhar um único checkout.

Ela é menos útil se você só troca de branch ocasionalmente, não executa serviços locais ou já tem um wrapper interno maduro para worktrees.

Diferenciais principais antes de instalar

O valor prático não é apenas “criar um worktree”. A skill acrescenta convenções repetíveis para:

• nomenclatura determinística de worktrees e criação de branches
• alocação sem sobreposição de portas de app, banco de dados e Redis
• sincronização de .env, .env.local, .env.development e .envrc
• detecção de instalação de dependências a partir de lockfiles comuns
• verificações de limpeza para worktrees antigos, sujos e branches já mescladas
• padrões de Docker Compose para isolamento de serviços por worktree

Isso torna a git-worktree-manager skill mais operacional do que um prompt genérico sobre Git worktrees.

Como usar a skill git-worktree-manager

Opções de instalação do git-worktree-manager

Para uma configuração de skills no estilo Claude, instale a partir do repositório usando seu gerenciador de skills, se disponível:

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

Se for instalar manualmente, copie o diretório da skill em:

engineering/skills/git-worktree-manager

para sua pasta local de skills, como ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager ou outro diretório compatível de skills para agentes. Depois da instalação, confirme que estes arquivos estão presentes: SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py e os dois arquivos em references/.

Leia estes arquivos primeiro

Para adotar rapidamente, leia nesta ordem:

1. README.md para entender o formato dos comandos e a lista de ferramentas.
2. SKILL.md para o fluxo de trabalho previsto e as orientações de quando usar.
3. references/port-allocation-strategy.md antes de alterar portas de serviços.
4. references/docker-compose-patterns.md se sua aplicação usa Compose.
5. scripts/worktree_manager.py e scripts/worktree_cleanup.py antes de confiar na automação em um repositório de produção.

Isso é importante porque os scripts alteram checkouts reais, copiam arquivos de ambiente e podem instalar dependências. Revise os padrões antes de executá-los em um monorepo grande ou em um repositório com configuração local sensível.

Uso prático do git-worktree-manager

Um fluxo típico de criação e preparação é:

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

Um fluxo de revisão para limpeza é:

python scripts/worktree_cleanup.py \
  --repo . \
  --stale-days 14 \
  --format text

As duas ferramentas aceitam entrada JSON via --input <json-file> ou stdin, o que é útil para automação. Peça ao agente para produzir primeiro um plano de comandos e só execute o script depois de confirmar o caminho do repositório, o nome da branch, a branch base, o comportamento de instalação de dependências e a política de limpeza.

Padrão de prompt para melhores resultados

Prompt fraco:

Set up a worktree for my feature.

Prompt mais forte:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

Isso dá à skill informações suficientes para escolher a estratégia de branch, evitar colisões de portas, preservar a segurança em torno de arquivos .env* e separar planejamento de execução.

FAQ da skill git-worktree-manager

git-worktree-manager é só para agentes de IA?

Não. A skill é otimizada para trabalho com múltiplos agentes, mas os scripts e convenções também são úteis para pessoas desenvolvedoras. O principal benefício é a repetibilidade: cada worktree recebe uma branch previsível, um diretório, portas, arquivos de ambiente copiados e uma revisão de limpeza, em vez de depender de um histórico de shell improvisado.

Qual é a diferença em relação ao git worktree puro?

O git worktree add puro cria outro checkout. Ele não resolve conflitos locais de aplicação. git-worktree-manager adiciona o fluxo de trabalho ao redor: blocos de portas, .worktree-ports.json, cópia de arquivos de ambiente, instalação opcional de dependências, orientação de isolamento com Docker Compose e verificações de limpeza para branches antigas ou já mescladas.

Iniciantes conseguem usar com segurança?

Sim, desde que tratem a skill como um fluxo guiado, não como um executor cego de comandos. Iniciantes devem começar com operações de listagem/revisão, usar --format text, evitar remoção automática e inspecionar os comandos gerados antes da execução. O script de limpeza verifica worktrees sujos, mas você ainda deve entender quais branches podem ser excluídas com segurança.

Quando não devo usar esta skill?

Não use como está se seu repositório tiver tratamento incomum de ambiente, secrets que nunca devem ser copiados, instalação de dependências fora do padrão ou portas de serviço gerenciadas por uma plataforma interna. Nesses casos, use o git-worktree-manager guide como padrão inicial e personalize os scripts ou prompts antes da adoção.

Como melhorar a skill git-worktree-manager

Dê mais contexto de repositório ao git-worktree-manager

Entradas melhores geram planos de worktree mais seguros. Inclua:

• caminho absoluto do repositório
• branch de destino e branch base
• nome desejado para o diretório do worktree
• gerenciador de pacotes ou expectativas sobre lockfiles
• serviços que precisam de portas
• se arquivos .env* podem ser copiados
• se a instalação de dependências é permitida
• limite de idade para limpeza e branch base para verificações de merge

Isso reduz suposições e impede que o agente assuma padrões que não correspondem à sua aplicação.

Ajuste convenções de portas e Docker Compose

A estratégia de referência usa bases padrão como app 3000, Postgres 5432, Redis 6379, com um incremento de 10 por worktree. Se sua stack tiver mais serviços, reserve um bloco contíguo maior. Se você executa infraestrutura local fora dos worktrees, desloque as portas base para evitar colisões globais.

Para Docker Compose, prefira overrides por worktree, portas controladas por .env e nomes de projeto únicos, como:

docker compose -p myapp_wt_auth up -d

Isso evita colisões de containers, redes, volumes e bancos de dados entre branches.

Fique atento aos modos de falha comuns

Os problemas mais comuns são secrets copiados, reutilização de portas padrão de banco de dados, volumes Docker compartilhados entre migrações incompatíveis, instalação de dependências no runtime errado e exclusão de um worktree que ainda contém trabalho não commitado. Peça ao agente para informar o status sujo, os arquivos de ambiente copiados, as portas selecionadas e as ações de instalação depois de cada execução.

Para limpeza, comece com saída apenas de revisão. Habilite a remoção somente depois de confirmar que um worktree está antigo, limpo e mesclado na branch base esperada.

Faça iterações depois da primeira saída

Depois do primeiro plano ou comando, peça uma revisão focada em vez de recomeçar:

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

Isso mantém a skill ancorada nas restrições reais do repositório, ao mesmo tempo em que melhora a segurança e a reprodutibilidade.