# Git worktrees para agentes de IA: comandos, armadilhas e automação

> Um git worktree é um diretório de trabalho extra ligado ao mesmo repositório, com branch e arquivos próprios, mas histórico compartilhado. Para agentes de IA, um worktree por agente garante que sessões paralelas nunca editem os mesmos arquivos. Você cria com `git worktree add`, lista com `git worktree list` e remove com `git worktree remove`. O Tallos cria e limpa um worktree para cada workspace automaticamente.

- Canonical: https://runtallos.com/pt/aprenda/git-worktrees-para-agentes-de-ia
- English: https://runtallos.com/learn/git-worktrees-for-ai-agents.md
- Atualizado em: 2026-09-29
- Section: Aprenda

## Em resumo

- Um repositório, várias branches em checkout ao mesmo tempo
- Comandos principais: add, list, remove, prune
- Uma branch só pode estar em um worktree
- Todo workspace do Tallos é um git worktree de verdade

## O que é um git worktree?

Um **git worktree** é um diretório de trabalho ligado a um repositório existente, com a sua própria branch em checkout. O clone normal é o **worktree principal**; cada `git worktree add` cria um **worktree vinculado** em outra pasta. Todos compartilham o mesmo armazenamento de objetos do `.git`, então commits, branches e remotes são os mesmos em todo lugar, mas cada pasta tem seus arquivos, seu index e seu `HEAD`.

Comparado a um segundo `git clone`, o worktree é mais rápido de criar, ocupa menos disco porque o histórico é compartilhado, e um commit feito num worktree aparece na hora nos outros. Comparado a trocar de branch, nada vai para o stash e nada é interrompido.

## Por que agentes de IA precisam de git worktrees?

Agentes de IA precisam de worktrees porque editam arquivos direto e rodam por minutos seguidos. Dois agentes na mesma pasta sobrescrevem as edições um do outro, dividem a mesma staging area e brigam pelo build. Um worktree por agente dá a cada um uma cópia isolada numa branch própria, e é isso que torna seguro [rodar agentes em paralelo](https://runtallos.com/pt/rodar-agentes-de-ia-em-paralelo) e revisar cada resultado como um diff limpo na [revisão de diff](https://runtallos.com/pt/recursos/revisao-de-diff).

**Vários agentes, uma pasta**
- As edições colidem nos mesmos arquivos
- Uma branch mistura as mudanças de todos
- Não dá para descartar o trabalho de um agente só

**Um worktree por agente**
- Cada agente edita sua cópia
- Cada resultado é uma branch com seu diff
- Descarte um removendo o worktree dele

## Como configurar git worktrees para agentes de IA, passo a passo?

1. **Confira a versão do git** — Rode `git --version`. O `git worktree` faz parte do git desde a versão 2.5, então qualquer instalação atual serve.
2. **Atualize a branch base** — No checkout principal, rode `git fetch origin` para os worktrees novos partirem do `origin/main` mais recente.
3. **Crie um worktree por agente** — Rode `git worktree add ../myapp-auth -b feat/auth origin/main`. Isso cria a pasta `../myapp-auth` com uma branch nova `feat/auth` a partir do `origin/main`. Repita com pasta e branch novas para cada agente.
4. **Traga os arquivos ignorados pelo git** — Um worktree novo é um checkout limpo: `node_modules`, `.env` e caches de build não vêm junto. Instale as dependências e copie os arquivos locais que cada agente precisa.
5. **Inicie o agente dentro do worktree** — `cd ../myapp-auth` e inicie o agente ali, por exemplo `claude` ou `codex`. O diretório de trabalho do agente é o worktree, então as edições ficam nele.
6. **Revise e faça o merge da branch** — Revise com `git diff origin/main...feat/auth`, rode os testes e depois faça push da branch e abra um pull request, ou faça o merge local.
7. **Remova o worktree no fim** — Rode `git worktree remove ../myapp-auth` e depois `git branch -d feat/auth` se a branch já entrou. Rode `git worktree prune` se algum dia você apagou a pasta de um worktree na mão.

## Quais comandos de git worktree eu realmente preciso?

Quatro comandos resolvem quase tudo: `add`, `list`, `remove` e `prune`. O resto é para casos específicos.

| Comando | O que faz |
| --- | --- |
| `git worktree add <path> -b <branch> [<start>]` | Cria uma pasta com uma branch nova a partir de `<start>` (padrão: o `HEAD` atual) |
| `git worktree add <path> <branch-existente>` | Faz checkout de uma branch que já existe, se nenhum outro worktree estiver com ela |
| `git worktree add --detach <path> <commit>` | Faz checkout de um commit sem branch, para testes rápidos |
| `git worktree list` | Mostra todos os worktrees com caminho, commit e branch |
| `git worktree remove <path>` | Apaga a pasta de um worktree limpo e seus metadados; `--force` descarta mudanças não commitadas |
| `git worktree prune` | Limpa metadados de worktrees cuja pasta foi apagada na mão |
| `git worktree move <path> <novo-path>` | Move um worktree vinculado para outra pasta |
| `git worktree lock <path>` | Protege um worktree em disco removível ou de rede contra o prune |

_Cola de comandos do git worktree_

```bash
git fetch origin
git worktree add ../myapp-auth -b feat/auth origin/main
git worktree add ../myapp-tests -b test/checkout origin/main
git worktree list
# ...os agentes trabalham, você revisa e faz o merge...
git worktree remove ../myapp-auth
git branch -d feat/auth
```

## Quais são as armadilhas mais comuns com git worktree?

- **Uma branch só vive em um worktree.** `fatal: 'main' is already checked out` significa que outro worktree está com ela. Crie uma branch nova por worktree.
- **Faltam os arquivos ignorados pelo git.** `.env`, `node_modules` e caches não vêm junto. Reserve tempo para configurar ou automatize a cópia.
- **Portas e serviços compartilhados colidem.** Dois servidores de desenvolvimento na porta 3000 falham. Dê a cada worktree sua porta e, se precisar, seu banco de testes.
- **Worktrees dentro do repositório confundem as ferramentas.** Um worktree aninhado na pasta principal aparece em buscas e watchers. Mantenha os worktrees numa pasta irmã ou num diretório ignorado pelo git.
- **Apagar a pasta na mão deixa metadados.** O git ainda acha que a branch está em checkout. Rode `git worktree prune`.
- **`--force` perde trabalho.** `git worktree remove --force` descarta mudanças não commitadas. Faça commit ou confira o diff antes.
- **O disco enche.** O histórico é compartilhado, mas cada worktree tem seus arquivos e dependências.

> Deixe os worktrees com o Tallos. Cada workspace é um, criado e limpo para você. → https://runtallos.com/signup

## Como o Tallos automatiza os git worktrees?

O Tallos é nativo em worktrees: toda tarefa que você começa vira um **workspace**, e todo workspace é um git worktree de verdade, com branch, arquivos e sessões de agente próprios. Você nunca digita `git worktree add`, mas sempre pode abrir um terminal e usar git puro dentro de qualquer workspace.

- **Criação em segundo plano.** O Tallos roda `git fetch` e `git worktree add` em segundo plano e mostra o progresso na aba nova; você segue trabalhando.
- **Escolha do ponto de partida.** Parta da branch base, de outra branch local (para empilhar sobre um PR em revisão), de um commit específico ou de uma branch remota que o Tallos busca para você.
- **Nome da branch.** Vem do nome do workspace ou do item vinculado do GitHub, Linear, Jira ou GitLab. Defina o seu em **Avançado → Nome da branch**.
- **Arquivos ignorados pelo git.** Liste os arquivos a copiar no `.worktreeinclude` na raiz do repositório e configure caminhos compartilhados por repositório em Configurações → Repositório.
- **Limpeza.** Excluir um workspace remove a pasta e a branch depois da confirmação. Se o git mantiver uma branch por ela ter commits sem merge, o Tallos deixa você revisar.
- **Seus próprios worktrees.** Worktrees criados com `git worktree add` fora do Tallos podem aparecer na barra lateral, e um worktree removido pela CLI some do Tallos na próxima atualização.

| Etapa | Git puro | Tallos |
| --- | --- | --- |
| Criar | `git worktree add ../dir -b branch origin/main` | Novo workspace |
| Escolher o ponto de partida | Passar `<start>` | Seletor de ponto de partida |
| Copiar o `.env` | Na mão | `.worktreeinclude` |
| Iniciar o agente | `cd` + comando do agente | Agente escolhido no mesmo diálogo |
| Revisar | `git diff` | Diff com notas por linha |
| Remover | `git worktree remove` + `git branch -d` | Excluir workspace |

_O mesmo ciclo de vida do worktree, na mão e no Tallos_

Veja na prática em [como rodar várias sessões do Claude Code](https://runtallos.com/pt/aprenda/rodar-varias-sessoes-do-claude-code) ou leia a página de [workspaces paralelos](https://runtallos.com/pt/recursos/workspaces-paralelos). Termos novos? O [glossário](https://runtallos.com/pt/glossario) define worktree, workspace e base ref.

## Perguntas frequentes

### Qual a diferença entre git worktree e git clone?

O clone copia o repositório inteiro, com histórico. O worktree é uma pasta de trabalho extra que compartilha o histórico do repositório original, então é mais rápido de criar e ocupa menos disco.

### Dois worktrees podem usar a mesma branch?

Não. O git só permite uma branch em checkout em um worktree por vez. Crie uma branch nova para cada worktree.

### Como apago um git worktree?

Rode `git worktree remove <path>`. Se você já apagou a pasta na mão, rode `git worktree prune` para limpar os metadados que sobraram.

### Por que o .env some num worktree novo?

Worktrees só trazem arquivos versionados. Arquivos ignorados pelo git, como `.env` e `node_modules`, precisam ser copiados ou reinstalados; o Tallos copia automaticamente com um arquivo `.worktreeinclude`.

### Onde devo colocar os git worktrees?

Fora da pasta principal, por exemplo num diretório irmão, para editores, watchers e buscas não enxergarem os arquivos duas vezes.

### O Tallos usa git worktrees de verdade?

Sim. Todo workspace do Tallos é um git worktree padrão, então `git status`, `git rebase` e qualquer outro comando do git funcionam dentro dele.

---

**Rode seus agentes em paralelo com o Tallos** — Claude Code, Codex, Gemini e mais de 30 agentes — cada um no seu workspace, com squads, chat, terminais e revisão num só app. Usa as assinaturas que você já tem.

https://runtallos.com/signup (macOS 13+ · Windows 10+)