Git Worktrees

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.

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.

Conceito

Um worktree é um diretório separado vinculado ao mesmo repositório 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 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

/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.

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.

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).

Mudanca de CWD

O ChatCLI muda automaticamente o diretório 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 diretório 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

Feature paralela
Hotfix urgente
Review de PR

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)

Corrija um bug sem perder o trabalho em progresso:

# 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

Revise um PR sem sair da sua branch:

# 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

Detalhes Tecnicos

Localizacao dos Diretorios

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

/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

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Conceito

Comandos

Criando uma Worktree

Listando Worktrees

Removendo uma Worktree

Status da Worktree

Workflow Tipico

Detalhes Tecnicos

Localizacao dos Diretorios

Mudanca Automática de CWD

Compatibilidade

Próximos Passos

Sessões

Modo Coder

​Conceito

​Comandos

​Criando uma Worktree

​Listando Worktrees

​Removendo uma Worktree

​Status da Worktree

​Workflow Tipico

​Detalhes Tecnicos

​Localizacao dos Diretorios

​Mudanca Automática de CWD

​Compatibilidade

​Próximos Passos

Sessões

Modo Coder

Conceito

Comandos

Criando uma Worktree

Listando Worktrees

Removendo uma Worktree

Status da Worktree

Workflow Tipico

Detalhes Tecnicos

Localizacao dos Diretorios

Mudanca Automática de CWD

Compatibilidade

Próximos Passos