OpenCode Worktree: isole tarefas de programação com Git

Um Git worktree é outro diretório de trabalho conectado ao mesmo repositório. O checkout principal pode ficar em main, enquanto uma pasta ao lado usa work/auth. Os arquivos e a branch atual são separados, mas o Git compartilha objetos e histórico; por isso, normalmente não é preciso clonar todo o repositório para cada tarefa.

Esse fluxo não exige um modo especial de worktree no OpenCode. Inicie a CLI dentro do novo diretório e ele será o contexto do projeto. Configurações globais ainda podem valer, mas arquivos locais não rastreados e dados do ambiente não são copiados automaticamente.

Primeiro confira a branch e as alterações do checkout atual. Um começo limpo facilita identificar o que pertence à tarefa nova. Na raiz do repositório, crie uma branch e seu worktree em uma pasta irmã, fora do diretório original.

O exemplo cria work/auth no commit atual e o coloca em ../app-auth. Se a branch já existir, confirme que outro worktree não a está usando antes de reutilizá-la. O Git normalmente impede que a mesma branch fique ativa em vários worktrees vinculados.

Execute estes comandos na raiz do repositório principal. A nova branch começa no commit atual.

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

Depois de cd ../app-auth, execute opencode nesse terminal. O diretório atual é a fronteira importante: use um terminal ou sessão por worktree e confirme a raiz do projeto antes de permitir edições. Uma primeira solicitação somente de leitura pode resumir a branch e listar os arquivos a verificar.

Dê a cada sessão uma tarefa específica e registre a branch. Uma pasta pode cuidar dos testes de autenticação e outra da documentação. Evite que duas sessões alterem o mesmo arquivo ou a mesma saída gerada. Pastas separadas reduzem conflitos, mas não coordenam agentes automaticamente.

O worktree separa arquivos controlados pelo Git e o índice, mas não é um contêiner nem uma fronteira de segurança. Um banco local, servidor de teste, cache, projeto Docker ou conta externa ainda pode ser compartilhado. Se necessário, separe schema, porta, nome do projeto ou use um ambiente descartável.

O Git faz checkout dos arquivos rastreados no commit escolhido. .env, certificados, caches e saídas ignoradas podem não aparecer no novo worktree. Recrie apenas o ambiente necessário, carregue segredos pelo método aprovado e verifique git status --short --branch antes e depois do trabalho.

Revise a branch do worktree como uma mudança independente. Inspecione git diff, execute as verificações do projeto nessa pasta e confirme que só há arquivos previstos. Depois dos testes, faça merge ou rebase pelo processo da equipe. Alterações não aparecem em outro checkout até que os commits sejam compartilhados.

Antes de remover, verifique mudanças sem commit e decida se deve confirmá-las, guardá-las ou mantê-las. git worktree remove ../app-auth remove um checkout limpo; se houver alterações, o Git bloqueia a operação sem uma opção forçada. Não use força como limpeza normal. git worktree prune remove registros antigos, não diretórios ativos.

Use um worktree quando tarefas precisarem de branches, cópias dos arquivos ou limites de revisão diferentes por horas ou dias. Para investigação somente de leitura ou que precisa ver arquivos ainda não commitados, outra sessão no mesmo checkout é mais simples. Se as tarefas forem sequenciais, basta trocar de branch.

O worktree acrescenta etapas de nomear branches, instalar dependências, separar serviços, testar, integrar e limpar. Se dois agentes precisarem editar os mesmos arquivos, a integração pode ficar mais difícil. Divida primeiro as mudanças para que não se sobreponham ou execute as edições em sequência.

Se git worktree add informar que a branch já está em uso, consulte git worktree list e escolha outra branch ou volte ao worktree existente. Se o OpenCode mostrar arquivos inesperados, confira o caminho do terminal e a raiz do projeto antes de mudar configurações. Arquivos ignorados não fazem parte do checkout.

Se testes de sessões diferentes interferirem, procure fora do Git: bancos, portas, pastas temporárias, geradores e caches compartilhados. Se a remoção falhar, rode git status dentro do worktree e preserve as alterações úteis. Mantenha o checkout principal disponível para integrar o trabalho.