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

# Git Worktrees

> Gerencie git worktrees para trabalho isolado em branches paralelas sem trocar de diretório

O comando `/worktree` do ChatCLI integra com o sistema de **git worktrees** para permitir trabalho isolado em múltiplas branches simultaneamente. Em vez de fazer `git stash` e `git checkout`, você cria worktrees separados e alterna entre eles com um único comando.

<Info>
  Git worktrees permitem ter múltiplas cópias de trabalho do mesmo repositório, cada uma em uma branch diferente, compartilhando o mesmo `.git`. O ChatCLI automatiza a criação, listagem e remoção dessas worktrees.
</Info>

***

## Conceito

Um **worktree** é um diretório separado vinculado ao mesmo repositório Git, mas em uma branch diferente. Isso permite:

```text theme={"system"}
meu-projeto/                 (main)
meu-projeto-feature-auth/    (feature/auth)  <- worktree
meu-projeto-fix-bug-123/     (fix/bug-123)   <- worktree
```

Todos compartilham o mesmo `.git`, commits e histórico. Você pode trabalhar em cada branch sem interferir nas outras.

***

## Comandos

| Comando                     | Descrição                                                  |
| :-------------------------- | :--------------------------------------------------------- |
| `/worktree create <branch>` | Cria uma nova worktree para a branch especificada          |
| `/worktree list`            | Lista todas as worktrees ativas do repositório             |
| `/worktree remove <branch>` | Remove uma worktree existente                              |
| `/worktree status`          | Mostra o status da worktree atual (branch, modified files) |

***

## Criando uma Worktree

```bash theme={"system"}
/worktree create feature/auth
```

```text theme={"system"}
Worktree created:
  Branch: feature/auth
  Path:   /Users/dev/meu-projeto-feature-auth/
  CWD changed to: /Users/dev/meu-projeto-feature-auth/

Tip: Use /worktree list to see all active worktrees.
```

<Steps>
  <Step title="Detecção automática de branch">
    Se a branch já existe no repositório (local ou remoto), o ChatCLI a usa diretamente. Se não existe, cria uma nova branch a partir do HEAD atual.
  </Step>

  <Step title="Criacao do diretório">
    O diretório da worktree e criado ao lado da raiz do repositório, com o nome baseado na branch (barras substituidas por hífens).
  </Step>

  <Step title="Mudanca de CWD">
    O ChatCLI muda automaticamente o diretório de trabalho para a nova worktree, permitindo que comandos subsequentes operem no contexto correto.
  </Step>
</Steps>

<Tip>
  A branch pode ser uma branch existente (local ou remota) ou uma nova branch. O ChatCLI detecta automaticamente e age de acordo.
</Tip>

***

## Listando Worktrees

```bash theme={"system"}
/worktree list
```

```text theme={"system"}
Active worktrees:
  * /Users/dev/meu-projeto/                  main          (current)
    /Users/dev/meu-projeto-feature-auth/     feature/auth  3 modified files
    /Users/dev/meu-projeto-fix-bug-123/      fix/bug-123   clean
```

***

## Removendo uma Worktree

```bash theme={"system"}
/worktree remove feature/auth
```

```text theme={"system"}
Worktree removed:
  Branch: feature/auth
  Path:   /Users/dev/meu-projeto-feature-auth/ (deleted)

Note: The branch 'feature/auth' was NOT deleted. Use git branch -d to remove it.
```

<Warning>
  Remover uma worktree **deleta o diretório** mas  **não deleta a branch**. Alterações não commitadas serão perdidas. Sempre faca commit ou stash antes de remover.
</Warning>

***

## Status da Worktree

```bash theme={"system"}
/worktree status
```

```text theme={"system"}
Current worktree:
  Path:   /Users/dev/meu-projeto-feature-auth/
  Branch: feature/auth
  Ahead:  2 commits (vs origin/feature/auth)
  Files:  3 modified, 1 untracked

  Modified:
    M  auth/handler.go
    M  auth/middleware.go
    M  auth/jwt.go
    ?  auth/refresh_token.go
```

***

## Workflow Tipico

<Tabs>
  <Tab title="Feature paralela">
    Trabalhe em uma feature sem afetar a branch principal:

    ```bash theme={"system"}
    # Crie worktree para a feature
    /worktree create feature/auth

    # Trabalhe normalmente (CWD já mudou)
    /coder Implemente o modulo de autenticação JWT

    # Volte para a worktree principal
    /worktree create main
    # (detecta que main já existe e apenas muda o CWD)
    ```
  </Tab>

  <Tab title="Hotfix urgente">
    Corrija um bug sem perder o trabalho em progresso:

    ```bash theme={"system"}
    # Você está trabalhando em feature/auth...
    # Bug urgente em produção!

    /worktree create hotfix/fix-login

    # Corrija o bug
    /coder Corrija o bug de login que causa redirect infinito

    # Volte para a feature
    /worktree create feature/auth
    ```
  </Tab>

  <Tab title="Review de PR">
    Revise um PR sem sair da sua branch:

    ```bash theme={"system"}
    # Crie worktree para a branch do PR
    /worktree create feature/new-api

    # Análise o código
    /plan
    /agent Análise as alterações nesta branch e identifique possiveis problemas
    # ou, numa linha só:
    # /plan Análise as alterações nesta branch e identifique possiveis problemas

    # Remova quando terminar
    /worktree remove feature/new-api
    ```
  </Tab>
</Tabs>

***

## Detalhes Tecnicos

### Localizacao dos Diretorios

Worktrees são criados **ao lado** da raiz do repositório:

```text theme={"system"}
/Users/dev/
  meu-projeto/                     <- repositório original
  meu-projeto-feature-auth/        <- worktree (branch: feature/auth)
  meu-projeto-fix-bug-123/         <- worktree (branch: fix/bug-123)
```

O nome do diretório e composto por `<nome-do-repo>-<branch>`, onde barras (`/`) na branch são substituidas por hífens (`-`).

### Mudanca Automática de CWD

Ao criar ou selecionar uma worktree, o ChatCLI muda automaticamente o CWD. Isso garante que:

* Comandos do agent/coder operam nos arquivos corretos
* Busca de arquivos (`search`, `tree`) refletem a branch correta
* Bootstrap files (SOUL.md, RULES.md) são detectados corretamente

### Compatibilidade

| Requisito   | Detalhes                                |
| :---------- | :-------------------------------------- |
| Git         | >= 2.15.0 (suporte a worktrees)         |
| Repositório | Deve ser um repositório Git (não bare)  |
| Permissoes  | Escrita no diretório pai do repositório |

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Sessões" icon="clock-rotate-left" href="/pt/features/session-management">
    Combine worktrees com sessões para contexto persistente por branch.
  </Card>

  <Card title="Modo Coder" icon="code" href="/pt/core-concepts/coder-mode">
    Use o modo coder com worktrees para engenharia isolada por branch.
  </Card>
</CardGroup>