Worktrees

Para que serve

Um worktree é outra pasta de trabalho do mesmo repositório Git, ligada a um branch diferente. Os arquivos são separados, o histórico é o mesmo. Quando dois agentes precisam editar o mesmo projeto ao mesmo tempo, cada um fica com a sua pasta, e as mudanças de um não aparecem por acidente no git status do outro. O PrumoGrid cria o worktree pela Nova etapa, mostra cada um no cartão do projeto e oferece Remover quando você terminar.

Quando usar e quando não usar

Use um worktree quando houver dois trabalhos simultâneos no mesmo repositório. Por exemplo: na loja-api, um agente corrige o cupom PRIMEIRA enquanto outro atualiza a documentação. Também serve para um experimento que você talvez descarte inteiro.

Não use quando as etapas acontecem uma depois da outra no mesmo terminal; aí a pasta do projeto resolve. Também não se aplica a projetos sem Git: num projeto SVN, a opção aparece desabilitada com o motivo, e a etapa roda na pasta do projeto. E lembre que o worktree nasce sem dependências instaladas. Se o projeto precisa de npm install e de um .env para rodar os testes, conte com esse preparo.

Passo a passo

Criar um worktree pela Nova etapa

O exemplo cria o worktree cupom-fix na loja-api para uma etapa do Codex.

1. Selecione a loja-api e clique em Nova etapa.
2. Em O que precisa ser feito?, escreva a tarefa, por exemplo Corrija o cupom PRIMEIRA, que dá desconto em dobro com dois itens no carrinho, e acrescente um teste.
3. Em Executa, escolha o agente.
4. Abra Mais opções e depois Opções de etapa. Em Pasta, escolha Em um worktree novo.
5. No campo nome do worktree (vira a branch), digite cupom-fix. A nota abaixo lembra que o worktree isola a tarefa numa branch própria e nasce sem dependências instaladas.
6. Confira o plano: ele mostra o nome, o branch e o caminho, como Worktree novo "cupom-fix" (branch cupom-fix) em: C:\demo\.tg-worktrees\loja-api-cupom-fix.
7. Clique em Criar etapa. Uma confirmação do Windows, Criar worktree, mostra o repositório, a nova pasta e o branch novo a partir do branch atual. Confirme em Criar.
8. O aviso diz que a etapa foi criada no worktree novo e qual painel foi aberto. O terminal já nasce dentro da pasta do worktree.

A pasta .tg-worktrees fica ao lado do repositório, fora dele. No exemplo, C:\demo\.tg-worktrees, ao lado de C:\demo\loja-api. Assim o worktree não aparece no git status da pasta principal.

O nome aceita letras, números, ponto, hífen e sublinhado, começando por letra ou número, com até 64 caracteres. Não pode ter .., terminar em . ou .lock, nem ser um nome reservado do Windows, como con ou nul.

Conferir pelo terminal

Num PowerShell da pasta principal, estes comandos só leem:

git worktree list
git -C ..\.tg-worktrees\loja-api-cupom-fix status --short

O primeiro lista a pasta principal e o worktree com o branch cupom-fix. O segundo mostra só o que mudou dentro do worktree.

O que aparece na tela

Ampliar captura ↗

O cartão do projeto mostra no máximo quatro linhas de árvores de trabalho, nesta ordem: a do branch principal, depois os worktrees com sessão aberta e, em seguida, os criados pelo PrumoGrid em .tg-worktrees. Os que passam de quatro, e os criados por outras ferramentas, ficam recolhidos numa linha.

Recolher a linha outras N árvores de trabalho não apaga pastas nem registros do Git; só esconde as linhas.

Remover um worktree

1. No cartão do projeto, passe o mouse na linha do worktree. A dica do × diz qual pasta será removida e lembra que o branch continua no repositório.
2. Clique no ×. A confirmação Remover worktree mostra a pasta, o branch e se há alterações não commitadas.
3. Sem alterações, ele diz Não há alterações não commitadas. Confirme em Remover.
4. Com alterações, ele avisa que remover agora descarta esse trabalho e mostra uma caixa como Sim, descartar as 2 alterações não commitadas. Sem marcar a caixa, a remoção é recusada e nada é descartado.
5. Se o PrumoGrid não conseguir verificar as alterações, a caixa diz Sim, remover mesmo sem conseguir verificar as alterações. Prefira conferir com git status --short na pasta antes de marcar.

A confirmação é uma caixa do próprio Windows, com os botões Remover e Cancelar. Num worktree sem alterações, ela fica assim:

Remover worktree
Remover o worktree "C:/demo/.tg-worktrees/loja-api-cupom-fix"?
Branch: cupom-fix
Não há alterações não commitadas.
O branch continua no repositório; some apenas a pasta do worktree.

Depois de remover, o aviso diz que a árvore de trabalho foi removida e que o branch continua no repositório. A pasta sai do disco. O branch cupom-fix fica, com os commits que ele tiver. Se não precisar mais dele depois do merge, apague com git branch -d cupom-fix.

Numa linha ausente, Remover apaga só o registro no Git, porque a pasta já não existia.

Limpeza

Worktrees se acumulam. Cada etapa com Em um worktree novo cria uma pasta, e fechar o projeto não remove nenhuma delas. De tempos em tempos:

• Olhe as linhas do cartão e a linha outras N árvores de trabalho.
• Commite ou descarte o que ficou em cada worktree e remova pelo ×.
• Rode git worktree list para conferir o que sobrou. Para registros de pastas que já foram apagadas à mão, git worktree prune limpa o Git.

Dicas

• Clicar na linha de um worktree no cartão leva ao terminal dele. Se não houver terminal aberto ali, abre um novo nessa pasta.
• Use nomes curtos e neutros, que digam a tarefa: cupom-fix, docs-readme. O nome vira o branch e aparece no cartão.
• Se uma etapa no worktree vai rodar uma verificação como npm test, prepare as dependências nesse worktree antes. A verificação roda na pasta da etapa.
• Arquivos de ponte entre agentes, como ANALISE.md, ficam na pasta de quem os gravou. Se o próximo agente trabalha em outra pasta, indique o caminho completo na instrução.
• A revisão de alterações mostra o estado da pasta que ela indica. Confirme que é o worktree certo antes de commitar.

Limites conhecidos

• Worktrees dependem do Git. Em SVN, a cópia isolada não é oferecida.
• O PrumoGrid não copia node_modules, .env nem executa nada ao criar: só a pasta do worktree é criada.
• Remover não apaga o branch.
• Fechar um projeto no catálogo não remove os worktrees dele do disco.
• O cartão mostra até quatro linhas; o resto fica em outras N árvores de trabalho.