> ## Documentation Index > Fetch the complete documentation index at: https://cli.fuxicode.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Executar sessões paralelas com worktrees > Isole sessões paralelas do Fuxi Code em worktrees git separadas para que as alterações não colidam. Abrange o sinalizador `--worktree`, isolamento de subagentes, `.worktreeinclude`, limpeza e hooks de VCS não-git. Uma [git worktree](https://git-scm.com/docs/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 Fuxi Code em sua própria worktree significa que edições em uma sessão nunca tocam arquivos em outra, para que você possa ter Fuxi 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](#non-git-version-control). O [aplicativo desktop](/pt/desktop#work-in-parallel-with-sessions) cria uma worktree para cada nova sessão automaticamente. Worktrees são uma das várias maneiras de executar Fuxi em paralelo. Elas isolam edições de arquivo, enquanto [subagentes](/pt/sub-agents) e [equipes de agentes](/pt/agent-teams) coordenam o trabalho em si. Consulte [Executar agentes em paralelo](/pt/agents) para comparar as abordagens, ou pule para [Isolar subagentes com worktrees](#isolate-subagents-with-worktrees) para usar worktrees e subagentes juntos.

Inicie Fuxi em uma worktree

Passe `--worktree` ou `-w` para criar uma worktree isolada e iniciar Fuxi nela. Por padrão, a worktree é criada em `.fuxi/worktrees//` na raiz do seu repositório, em um novo branch nomeado `worktree-`: ```bash theme={null} fuxi --worktree feature-auth ``` Para colocar worktrees em outro lugar, configure um hook [`WorktreeCreate`](#non-git-version-control). Execute o comando novamente com um nome diferente em outro terminal para iniciar uma segunda sessão isolada: ```bash theme={null} fuxi --worktree bugfix-123 ``` Se você omitir o nome, Fuxi gera um como `bright-running-fox`: ```bash theme={null} fuxi --worktree ``` Você também pode pedir ao Fuxi para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta [`EnterWorktree`](/pt/tools-reference). Uma vez em uma worktree, Fuxi pode alternar diretamente para outra em `.fuxi/worktrees/` chamando `EnterWorktree` com o caminho de destino. A worktree anterior permanece no disco intacta. {/* min-version: 2.1.198 */}A partir da v2.1.198, entrar ou sair de uma worktree também realoca a transcrição da sessão para o armazenamento de projeto desse diretório, da mesma forma que [`/cd`](/pt/commands) faz, então `/desktop` e `--resume` encontram a sessão lá depois. Worktrees criadas por um hook [`WorktreeCreate`](#non-git-version-control) são excluídas e mantêm a transcrição no diretório de inicialização. Antes de usar `--worktree` interativamente em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando `fuxi` uma vez nesse diretório. Se a confiança ainda não foi aceita, `--worktree` sai com um erro e solicita que você execute `fuxi` no diretório primeiro. Execuções não interativas com `-p` pulam a [verificação de confiança](/pt/security), então `fuxi -p --worktree` prossegue sem ela. {/* min-version: 2.1.205 */}Se Fuxi Code não conseguir entrar no diretório da worktree na inicialização, por exemplo porque um hook [`WorktreeCreate`](/pt/hooks#worktreecreate) imprimiu algo diferente do diretório que criou, ou porque o diretório foi deletado após ser configurado, Fuxi Code imprime um erro nomeando o caminho e sai com código 1. Antes da v2.1.205, isso causava crash na sessão, e com `-p` travava por cerca de 30 segundos antes de sair com código 0. {/* min-version: 2.1.200 */}Plugins instalados no [escopo do projeto](/pt/plugins-reference#plugin-installation-scopes) do checkout principal também carregam em worktrees do mesmo repositório, então você não precisa reinstalá-los por worktree. Isso se aplica se você criar a worktree com `--worktree` ou com `git worktree add`. Requer Fuxi Code v2.1.200 ou posterior. Adicione `.fuxi/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](/pt/settings#worktree-settings). 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: ```json theme={null} { "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. Fuxi Code busca `pull//head` de `origin` e cria a worktree em `.fuxi/worktrees/pr-`: ```bash theme={null} fuxi --worktree "#1234" ``` Para controle total sobre como as worktrees são criadas, configure um hook [`WorktreeCreate`](/pt/hooks#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 Fuxi 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: ```text .worktreeinclude theme={null} .env .env.local config/secrets.json ``` Isso se aplica a worktrees criadas com `--worktree`, [worktrees de subagentes](#isolate-subagents-with-worktrees), e sessões paralelas no [aplicativo desktop](/pt/desktop#work-in-parallel-with-sessions).

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 Fuxi para "usar worktrees para seus agentes", ou defina permanentemente em um [subagente personalizado](/pt/sub-agents#supported-frontmatter-fields) adicionando `isolation: worktree` ao frontmatter. Cada subagente obtém uma worktree temporária que é removida automaticamente quando o subagente termina sem alterações. As worktrees de subagentes usam a mesma [branch base](#choose-the-base-branch) que `--worktree`, portanto elas fazem branch da branch padrão do seu repositório, a menos que `worktree.baseRef` seja definido como `"head"`.

Limpe worktrees

Quando você sai de uma sessão de worktree, a limpeza depende se você fez alterações: * **Sem alterações não confirmadas, sem arquivos não rastreados e sem novos commits**: a worktree e seu branch são removidos automaticamente. Se a sessão tiver um [nome](/pt/sessions#name-your-sessions), Fuxi solicita em vez disso para que você possa manter a worktree para depois * **Alterações não confirmadas, arquivos não rastreados ou novos commits existem**: Fuxi 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, arquivos não rastreados 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 que Fuxi criou para subagentes e [sessões em segundo plano](/pt/agent-view#how-file-edits-are-isolated) são removidas automaticamente uma vez que são mais antigas que sua configuração [`cleanupPeriodDays`](/pt/settings#available-settings), 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. Enquanto um agente está em execução, Fuxi executa `git worktree lock` em sua worktree para que a limpeza simultânea não possa removê-la. O bloqueio é liberado quando o agente termina. Para limpar uma worktree que a varredura mantém, execute `git worktree remove`, adicionando `--force` se a worktree tiver alterações não confirmadas ou arquivos não rastreados. No Windows, antes de remover uma worktree, Fuxi Code remove qualquer junção NTFS ou symlink de diretório em qualquer profundidade dentro dela como uma entrada de link, para que remover a worktree não exclua os arquivos para os quais um link aponta. Antes da v2.1.205, Fuxi Code removia apenas links de nível superior como entradas de link, e remover uma worktree com uma junção aninhada em um subdiretório poderia excluir o conteúdo do diretório para o qual o link apontava fora da worktree.

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: ```bash theme={null} git worktree add ../project-feature-a -b feature-a ``` Crie uma worktree a partir de um branch existente: ```bash theme={null} git worktree add ../project-bugfix bugfix-123 ``` Inicie Fuxi na worktree: ```bash theme={null} cd ../project-feature-a && fuxi ``` Liste suas worktrees: ```bash theme={null} git worktree list ``` Remova uma quando terminar com ela: ```bash theme={null} git worktree remove ../project-feature-a ``` Consulte a [documentação de git worktree](https://git-scm.com/docs/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 worktrees usa git por padrão. Para SVN, Perforce, Mercurial, ou outros sistemas, configure os hooks [`WorktreeCreate` e `WorktreeRemove`](/pt/hooks#worktreecreate) para fornecer lógica de criação e limpeza personalizada. Como o hook substitui o comportamento padrão do git, [`.worktreeinclude`](#copy-gitignored-files-into-worktrees) 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 Fuxi Code possa usá-lo como o diretório de trabalho da sessão: ```json theme={null} { "hooks": { "WorktreeCreate": [ { "hooks": [ { "type": "command", "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.fuxi/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](/pt/hooks#worktreecreate) 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: * [Subagentes](/pt/sub-agents): delegue trabalho para agentes isolados dentro de uma sessão * [Equipes de agentes](/pt/agent-teams): coordene múltiplas sessões do Fuxi automaticamente * [Gerencie sessões](/pt/sessions): nomeie, retome e alterne entre conversas * [Sessões paralelas do desktop](/pt/desktop#work-in-parallel-with-sessions): sessões apoiadas por worktree no aplicativo desktop