o que é um git worktree?

o problema que worktrees resolvem

Uma pasta só pode ter uma branch ativa. Uma worktree acrescenta outra pasta com outra branch.

Normalmente, um repositório é uma pasta com uma branch ativa. Para trabalhar em duas coisas ao mesmo tempo, você guarda as mudanças com stash, troca de branch, faz o outro trabalho, volta e restaura o stash. Funciona, mas é lento e fácil de errar.

Uma worktree te dá uma segunda pasta que já está em outra branch. A funcionalidade A fica numa pasta e a funcionalidade B em outra, as duas abertas ao mesmo tempo, sem stash nem troca de branch.

por que isso importa para agentes de ia

Worktrees são o que torna seguro rodar vários agentes num repositório.

Dois agentes de IA na mesma pasta sobrescrevem um ao outro. O agente A edita auth.ts, o agente B edita auth.ts um minuto depois, e quem salvar por último vence. O trabalho do outro agente some, e nenhum dos dois percebe.

Com uma worktree para cada um, todo agente tem sua própria pasta, branch e arquivos. Os dois podem editar auth.ts ao mesmo tempo sem mexer na cópia do outro. Quando terminarem, você revisa e faz merge de cada branch separadamente.

como isso fica no disco

Mesmo histórico, arquivos separados. Onde as pastas ficam é decisão sua ou da sua ferramenta.

my-project/                 ← your main checkout (main)
my-project/worktrees/
  ├─ add-auth/              ← worktree, branch add-auth
  └─ fix-nav/               ← worktree, branch fix-nav

Toda worktree compartilha o mesmo histórico do git, então um commit feito em uma aparece nas outras. Edições sem commit ficam na própria pasta. O git não se importa com onde as worktrees ficam: ao lado do repositório, numa pasta separada ou dentro dele, como o Pane faz.

como o pane automatiza isso

O Pane cria, preenche e limpa uma worktree para cada pane, então você nunca digita os comandos.

Você não precisa rodar nenhum comando do git. Quando você cria um pane, o Pane:

1. Pega uma worktree que ele preparou com antecedência para aquele projeto e branch, para que o pane abra quase na hora, e dá a ele uma branch nova.
2. Copia seus arquivos .env, configurações de agentes como .claude e .codex, e o node_modules para dentro dele, para que o agente possa começar na hora. Você pode mudar a lista nas configurações.
3. Quando você arquiva o pane, verifica se há trabalho sem commit, não rastreado ou sem push, e então remove a worktree. Você pode restaurar um pane arquivado depois.

o jeito manual

Três comandos para criar e começar, e dois para limpar.

Sem uma ferramenta, a mesma coisa leva alguns comandos do git:

echo "worktrees/" >> .git/info/exclude   # once: keep them out of git status
git worktree add worktrees/add-auth -b add-auth
cd worktrees/add-auth
claude                      # start your agent here

# once the branch is merged:
git worktree remove worktrees/add-auth
git branch -d add-auth

Lembre de remover a worktree e apagar a branch depois do merge. A maioria das pessoas esquece, e é por isso que as ferramentas automatizam isso.

documentação relacionada

• → Panes e worktrees: como o Pane gerencia worktrees
• → Como rodar agentes em paralelo: o fluxo paralelo completo
• → Monorepos: worktrees em projetos monorepo
• → Git worktrees para agentes de IA: uma visão geral

Fontes

Correções

Se algo aqui estiver errado ou desatualizado, nos avise e vamos corrigir e atualizar a data no topo. Abra uma issue no GitHub

Fontes

• → git-worktree documentation
• → Panes & Worktrees (Pane docs)
• → Git worktree tools for AI agents