> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktrees

> Configurar automaticamente worktrees do Git para tarefas paralelas do Cascade

Windsurf oferece suporte ao uso de worktrees do Git para executar tarefas do Cascade em paralelo, sem interferir no workspace principal.

Ao usar worktrees, cada conversa no Cascade ganha sua própria sessão, permitindo que o Cascade edite, faça build e teste o código sem interferir no workspace principal.

<div id="basic-worktree-usage">
  ## Uso básico de worktree
</div>

A forma mais simples de começar a usar worktrees é alternar para o modo "Worktree" no canto inferior direito do campo de entrada do Cascade.

<Frame>
  <img style={{ maxHeight: "500px" }} src="https://mintcdn.com/codeium/U6QOrK-OfUtO4wfJ/assets/windsurf/worktree-toggle.png?fit=max&auto=format&n=U6QOrK-OfUtO4wfJ&q=85&s=8bb3e54349d5c84d4db81210a67ee931" width="873" height="224" data-path="assets/windsurf/worktree-toggle.png" />
</Frame>

<Note>
  Atualmente, você só pode mudar para uma worktree no início de uma sessão do Cascade. Conversas não podem ser movidas para uma worktree diferente depois de iniciadas.
</Note>

Depois que o Cascade faz alterações em arquivos na worktree, você tem a opção de clicar em "merge" para incorporar essas alterações de volta ao seu workspace principal.

<Frame>
  <img style={{ maxHeight: "500px" }} src="https://mintcdn.com/codeium/U6QOrK-OfUtO4wfJ/assets/windsurf/worktree-merge.png?fit=max&auto=format&n=U6QOrK-OfUtO4wfJ&q=85&s=bb47b232dd861f3e37255b9b82fb18bc" width="724" height="98" data-path="assets/windsurf/worktree-merge.png" />
</Frame>

<div id="location">
  ## Localização
</div>

Os worktrees são organizados pelo nome do repositório em `~/.windsurf/worktrees/<repo_name>`.

Cada worktree recebe um nome aleatório exclusivo.

Para ver a lista de worktrees ativos, você pode executar `git worktree list` no diretório do repositório.

<Warning>
  Como os worktrees ficam em um diretório diferente do seu projeto original, **sistemas de build ou ferramentas que dependem de caminhos relativos** (por exemplo, referências `../shared-lib`, dependências vinculadas por symlink ou dependências de código-fonte em monorepo resolvidas por caminho) podem não funcionar corretamente dentro de um worktree. Se o seu projeto usa caminhos relativos fora da raiz do repositório, configure um hook [`post_setup_worktree`](./worktrees#setup-hook) para criar os symlinks necessários ou copiar os arquivos necessários para os locais esperados.
</Warning>

<div id="setup-hook">
  ## Hook de configuração
</div>

Cada worktree contém uma cópia dos arquivos do seu repositório, mas não inclui arquivos `.env` ou outros pacotes que não estão sob controle de versão.

Se você quiser incluir arquivos ou pacotes adicionais em cada worktree, pode usar o `post_setup_worktree` [hook](./hooks#post_setup_worktree) para copiá-los para o diretório da worktree.

O hook `post_setup_worktree` é executado depois que cada worktree é criada e configurada. Ele é executado dentro do novo diretório da **worktree**.

A variável de ambiente `$ROOT_WORKSPACE_PATH` aponta para o caminho original do workspace e pode ser usada para acessar arquivos ou executar comandos relativos ao repositório original.

<div id="example">
  ### Exemplo
</div>

Copie arquivos de ambiente e instale dependências quando uma nova worktree for criada.

**Config** (em `.windsurf/hooks.json`):

```json theme={null}
{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
        "show_output": true
      }
    ]
  }
}
```

**Script** (`hooks/setup_worktree.sh`):

```bash theme={null}
#!/bin/bash

# Copiar arquivos de ambiente do workspace original
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "Arquivo .env copiado"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Arquivo .env.local copiado"
fi

# Instalar dependências
if [ -f "package.json" ]; then
    npm install
    echo "Dependências npm instaladas"
fi

exit 0
```

Este hook garante que cada worktree tenha a configuração de ambiente necessária e as dependências necessárias instaladas automaticamente.

<div id="cleanup">
  ## Limpeza
</div>

Windsurf limpa automaticamente os worktrees mais antigos ao criar um novo, para evitar uso excessivo do disco. Cada workspace pode ter até **20** worktrees.

Os worktrees são limpos com base em quando foram acessados pela última vez — os mais antigos são removidos primeiro. Essa limpeza acontece por workspace, garantindo que worktrees de diferentes repositórios permaneçam independentes uns dos outros.

Além disso, se você excluir manualmente uma conversa no Cascade, o Windsurf excluirá automaticamente o worktree associado.

<div id="source-control-panel">
  ## Painel de Controle de Código-Fonte
</div>

Por padrão, o Windsurf não mostra worktrees criadas pelo Cascade no Painel de SCM.
Você pode definir `git.showWindsurfWorktrees` como `true` nas suas configurações para alterar esse comportamento padrão e habilitar a visualização das worktrees no Painel de SCM.