Pular para o conteúdo principal
O comando /worktree do ChatCLI integra com o sistema de git worktrees para permitir trabalho isolado em multiplas branches simultaneamente. Em vez de fazer git stash e git checkout, você cria worktrees separados e alterna entre eles com um único comando.
Git worktrees permitem ter multiplas copias de trabalho do mesmo repositorio, cada uma em uma branch diferente, compartilhando o mesmo .git. O ChatCLI automatiza a criacao, listagem e remocao dessas worktrees.

Conceito

Um worktree e um diretorio separado vinculado ao mesmo repositorio Git, mas em uma branch diferente. Isso permite:
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 historico. Você pode trabalhar em cada branch sem interferir nas outras.

Comandos

ComandoDescrição
/worktree create <branch>Cria uma nova worktree para a branch especificada
/worktree listLista todas as worktrees ativas do repositorio
/worktree remove <branch>Remove uma worktree existente
/worktree statusMostra o status da worktree atual (branch, modified files)

Criando uma Worktree

/worktree create feature/auth
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.
1

Deteccao automática de branch

Se a branch já existe no repositorio (local ou remoto), o ChatCLI a usa diretamente. Se não existe, cria uma nova branch a partir do HEAD atual.
2

Criacao do diretorio

O diretorio da worktree e criado ao lado da raiz do repositorio, com o nome baseado na branch (barras substituidas por hifens).
3

Mudanca de CWD

O ChatCLI muda automaticamente o diretorio de trabalho para a nova worktree, permitindo que comandos subsequentes operem no contexto correto.
A branch pode ser uma branch existente (local ou remota) ou uma nova branch. O ChatCLI detecta automaticamente e age de acordo.

Listando Worktrees

/worktree list
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

/worktree remove feature/auth
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.
Remover uma worktree deleta o diretorio mas não deleta a branch. Alterações não commitadas serão perdidas. Sempre faca commit ou stash antes de remover.

Status da Worktree

/worktree status
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

Trabalhe em uma feature sem afetar a branch principal:
# 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)

Detalhes Tecnicos

Localizacao dos Diretorios

Worktrees são criados ao lado da raiz do repositorio:
/Users/dev/
  meu-projeto/                     <- repositorio original
  meu-projeto-feature-auth/        <- worktree (branch: feature/auth)
  meu-projeto-fix-bug-123/         <- worktree (branch: fix/bug-123)
O nome do diretorio e composto por <nome-do-repo>-<branch>, onde barras (/) na branch são substituidas por hifens (-).

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

RequisitoDetalhes
Git>= 2.15.0 (suporte a worktrees)
RepositorioDeve ser um repositorio Git (não bare)
PermissoesEscrita no diretorio pai do repositorio

Próximos Passos

Sessoes

Combine worktrees com sessoes para contexto persistente por branch.

Modo Coder

Use o modo coder com worktrees para engenharia isolada por branch.