Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Uma git worktree é um diretório de trabalho separado com seus próprios arquivos e branch, compartilhando o mesmo histórico de repositório e remoto que seu checkout principal. Executar cada sessão do Claude Code em sua própria worktree significa que edições em uma sessão nunca tocam arquivos em outra, para que você possa ter Claude construindo um recurso em um terminal enquanto corrige um bug em um segundo. Esta página aborda isolamento de worktree na CLI. Tudo abaixo assume um repositório git. Para outros sistemas de controle de versão, consulte Controle de versão não-git. O aplicativo desktop cria uma worktree para cada nova sessão automaticamente. Worktrees são uma das várias maneiras de executar Claude em paralelo. Elas isolam edições de arquivo, enquanto subagentes e equipes de agentes coordenam o trabalho em si. Consulte Executar agentes em paralelo para comparar as abordagens, ou pule para Isolar subagentes com worktrees para usar worktrees e subagentes juntos.

​
Inicie Claude em uma worktree

Passe --worktree ou -w para criar uma worktree isolada e iniciar Claude nela. Por padrão, a worktree é criada em .claude/worktrees/<value>/ na raiz do seu repositório, em um novo branch nomeado worktree-<value>: 
claude --worktree feature-auth
Para colocar worktrees em outro lugar, configure um hook WorktreeCreate. Execute o comando novamente com um nome diferente em outro terminal para iniciar uma segunda sessão isolada: 
claude --worktree bugfix-123
Se você omitir o nome, Claude gera um como bright-running-fox: 
claude --worktree
Você também pode pedir ao Claude para “trabalhar em uma worktree” durante uma sessão, e ele criará uma com a ferramenta EnterWorktree. Antes de usar --worktree em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando claude uma vez nesse diretório. Se a confiança ainda não foi aceita, --worktree sai com um erro e solicita que você execute claude no diretório primeiro, inclusive quando combinado com -p.
Adicione .claude/worktrees/ ao seu .gitignore para que o conteúdo da worktree não apareça como arquivos não rastreados no seu checkout principal.

​
Escolha o branch base

Worktrees fazem branch a partir do branch padrão do seu repositório, origin/HEAD, para que começem de uma árvore limpa correspondendo ao remoto. Se nenhum remoto estiver configurado ou a busca falhar, a worktree volta para seu HEAD local atual. Para sempre fazer branch a partir do HEAD local, defina worktree.baseRef como "head" em configurações. Definir baseRef como "head" faz com que novas worktrees carreguem seus commits não enviados e estado de branch de recurso, o que é útil ao isolar subagentes que precisam operar em trabalho em andamento. A configuração aceita apenas "fresh" ou "head", não refs git arbitrárias: 
{
  "worktree": {
    "baseRef": "head"
  }
}
Para fazer branch a partir de um pull request específico, passe o número do PR prefixado com #, ou uma URL completa de pull request do GitHub. Claude Code busca pull/<number>/head de origin e cria a worktree em .claude/worktrees/pr-<number>: 
claude --worktree "#1234"
Para controle total sobre como as worktrees são criadas, configure um hook WorktreeCreate, que substitui completamente a lógica padrão de git worktree.

​
Copie arquivos ignorados pelo git em worktrees

Uma worktree é um checkout fresco, então arquivos não rastreados como .env ou .env.local do seu repositório principal não estão presentes. Para copiá-los automaticamente quando Claude cria uma worktree, adicione um arquivo .worktreeinclude à raiz do seu projeto. O arquivo usa sintaxe .gitignore. Apenas arquivos que correspondem a um padrão e também são ignorados pelo git são copiados, então arquivos rastreados nunca são duplicados. Este .worktreeinclude copia dois arquivos env e uma configuração de segredos em cada nova worktree:
.worktreeinclude
.env
.env.local
config/secrets.json
Isso se aplica a worktrees criadas com --worktree, worktrees de subagentes, e sessões paralelas no aplicativo desktop.

​
Isole subagentes com worktrees

Subagentes podem executar em suas próprias worktrees para que edições paralelas não entrem em conflito. Peça ao Claude para “usar worktrees para seus agentes”, ou defina permanentemente em um subagente personalizado adicionando isolation: worktree ao frontmatter. Cada subagente obtém uma worktree temporária que é removida automaticamente quando o subagente termina sem alterações.

​
Limpe worktrees

Quando você sai de uma sessão de worktree, a limpeza depende se você fez alterações:
  • Sem alterações: a worktree e seu branch são removidos automaticamente
  • Alterações ou commits existem: Claude solicita que você mantenha ou remova a worktree. Manter preserva o diretório e branch para que você possa retornar mais tarde. Remover exclui o diretório da worktree e seu branch, descartando todas as alterações não confirmadas e commits
  • Execuções não interativas: worktrees criadas com --worktree junto com -p não são limpas automaticamente, pois não há prompt de saída. Remova-as com git worktree remove
Worktrees de subagentes órfãs por um crash ou execução interrompida são removidas na inicialização uma vez que são mais antigas que sua configuração cleanupPeriodDays, desde que não tenham alterações não confirmadas, nenhum arquivo não rastreado e nenhum commit não enviado. Worktrees que você cria com --worktree nunca são removidas por esta varredura.

​
Gerencie worktrees manualmente

Para controle total sobre localização de worktree e configuração de branch, crie worktrees com Git diretamente. Isso é útil quando você precisa fazer checkout de um branch existente específico ou colocar a worktree fora do repositório. Crie uma worktree em um novo branch: 
git worktree add ../project-feature-a -b feature-a
Crie uma worktree a partir de um branch existente: 
git worktree add ../project-bugfix bugfix-123
Inicie Claude na worktree: 
cd ../project-feature-a && claude
Liste suas worktrees: 
git worktree list
Remova uma quando terminar com ela: 
git worktree remove ../project-feature-a
Consulte a documentação de git worktree para a referência completa de comandos. Lembre-se de inicializar seu ambiente de desenvolvimento em cada nova worktree: instale dependências, configure ambientes virtuais, ou execute o que quer que a configuração do seu projeto exija.

​
Controle de versão não-git

Isolamento de worktree usa git por padrão. Para SVN, Perforce, Mercurial, ou outros sistemas, configure hooks WorktreeCreate e WorktreeRemove para fornecer lógica de criação e limpeza personalizada. Como o hook substitui o comportamento padrão do git, .worktreeinclude não é processado quando você usa --worktree. Copie quaisquer arquivos de configuração local dentro do seu script de hook. Este hook WorktreeCreate lê o nome da worktree de stdin, faz checkout de uma cópia de trabalho SVN fresca, e imprime o caminho do diretório para que Claude Code possa usá-lo como o diretório de trabalho da sessão: 
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}
Emparelhe-o com um hook WorktreeRemove para limpar quando a sessão terminar. Consulte a referência de hooks para o esquema de entrada e um exemplo de remoção.

​
Veja também

Worktrees lidam com isolamento de arquivo. As páginas relacionadas abaixo cobrem delegação de trabalho para esses checkouts isolados e alternância entre as sessões que você cria: