O que é git worktree?

Em resumo

Uma git worktree é uma pasta de trabalho extra ligada ao mesmo repositório git. Cada pasta tem uma branch diferente em checkout, então você trabalha em duas coisas ao mesmo tempo sem clonar o repositório de novo e mantém agentes de código em paralelo fora do caminho um do outro.

Como funciona

Normalmente, a pasta de um repositório tem uma branch em checkout, e trocar exige fazer commit ou stash antes. Com uma worktree, sua pasta principal fica como está e uma nova pasta com outra branch é adicionada ao lado. As pastas compartilham o histórico de commits e o banco de objetos, mas cada uma tem seu próprio HEAD, index e arquivos de trabalho.

Os comandos básicos

Um punhado de comandos cobre o uso do dia a dia.

git worktree add ../feature-a -b feature-a: cria uma nova branch e uma pasta.
git worktree list: mostra as worktrees abertas.
git worktree remove ../feature-a: remove a pasta.
git worktree prune: limpa os registros de pastas apagadas à mão.

Por que importa para agentes de código

Dois agentes na mesma pasta podem sobrescrever os arquivos um do outro, e a execução de testes de um agente pode tropeçar na mudança pela metade do outro. Dar a cada agente sua própria worktree evita isso: cada um trabalha na própria branch e você junta os resultados com um pull request ou merge. Branches que mexem no mesmo arquivo ainda podem gerar conflito na hora do merge.

Pontos de atenção

Worktrees são leves, mas alguns detalhes pegam as pessoas de surpresa.

A mesma branch não pode estar em checkout em duas worktrees ao mesmo tempo.
Arquivos não rastreados, como node_modules, .env e saída de build, não são copiados; talvez você precise instalar as dependências de novo.
Se cada worktree roda seu próprio servidor de desenvolvimento, fique de olho em conflitos de porta.
Remova as worktrees que você não usa mais, senão pastas esquecidas se acumulam no disco.

Worktrees no AgentVera

O AgentVera usa worktrees como base para rodar agentes em paralelo.

No painel de worktrees do Git, abra uma branch e uma pasta por funcionalidade e inicie um agente direto nessa pasta.
No turno da noite, cada tarefa roda na sua própria worktree em uma branch night/<date>-<slug>; o agente faz commit, mas nunca faz push (Pro e Team).
Os ambientes de preview rodam o servidor de desenvolvimento do projeto e de cada worktree em seu próprio endereço, com o nome da branch.
A coordenação de agentes avisa quando agentes em worktrees diferentes alteram o mesmo arquivo, já que o merge pode dar conflito.

Perguntas frequentes

Qual a diferença entre uma worktree e uma branch?

Uma branch é uma linha de commits com nome; uma worktree é uma pasta onde uma branch está em checkout. Só com branches você alterna dentro de uma pasta; com worktrees você mantém várias branches abertas em pastas separadas ao mesmo tempo.

Qual a diferença entre uma worktree e clonar o repositório duas vezes?

Worktrees compartilham um único repositório: commits, branches e configuração são comuns, e elas ocupam menos disco. Um commit feito em uma worktree aparece nas outras na hora, enquanto clones separados precisam de push e fetch.

Como apago uma worktree?

Rode git worktree remove <pasta>. Se você apagou a pasta à mão, git worktree prune limpa o registro. A branch continua; apague-a separadamente com git branch -d se precisar.

As worktrees compartilham o node_modules?

Não. Arquivos não rastreados são separados em cada pasta, então você instala as dependências em cada worktree.