Worktrees e hooks Git

Preparar um worktree para um agente de IA consiste em instalar as dependências no seu checkout, fornecer a sua configuração ignorada e reservar portas e uma base de dados de testes próprias do ticket. Uma pasta Git separada não separa os serviços da máquina.

1. Ativa os worktrees e lança dois tickets independentes, A e B. Usa o caminho devolvido pelo Singularity para cada ticket; deixa a aplicação gerir os ramos e as pastas.
2. A partir da raiz de cada checkout, executa o comando do repositório, por exemplo pnpm install --frozen-lockfile num projeto pnpm. Não partilhes node_modules, as saídas de build nem as caches modificáveis entre checkouts.
3. Recria os ficheiros ignorados a partir de um modelo sem segredos. Verifica git check-ignore .env.local e git status --short. Fornece os segredos através do teu gestor habitual, sem os copiar para um ticket, um log ou um commit; não uses a base de dados de produção para os testes.
4. Atribui uma porta e uma base de dados distintas: A usa 43101 e .local/ticket-a.sqlite, B usa 43102 e .local/ticket-b.sqlite. Para um serviço externo, usa duas bases de dados ou esquemas de teste e adapta as variáveis à tua aplicação.
5. Lança os testes nos dois terminais ao mesmo tempo. Uma porta ocupada deve fazer falhar o teste; nesse caso, escolhe outra porta livre e regista-a no ticket. Não termines um processo desconhecido.

Um exemplo reproduzível para dois tickets

As instruções descarregáveis instalam um pequeno projeto Node 24+ com npm ci, sem dependências de terceiros. Descarrega os seus três ficheiros para cada checkout: package.json, package-lock.json e isolation.test.mjs. Cria apenas a configuração A em A, e a B em B.

# Checkout A: examples/worktree-setup/.env.local
TICKET_ID=ticket-a
PORT=43101
TEST_DB_PATH=.local/ticket-a.sqlite
# Checkout B: examples/worktree-setup/.env.local
TICKET_ID=ticket-b
PORT=43102
TEST_DB_PATH=.local/ticket-b.sqlite

npm test verifica a resposta HTTP do ticket e o proprietário da sua base de dados SQLite, com 1,5 segundos de sobreposição. O teste fecha o servidor e a base de dados mesmo em caso de falha. Esta receita verifica o isolamento dos recursos deste exemplo, não todos os ambientes aplicacionais.

Parar, limpar ou sequenciar

Para os teus servidores de desenvolvimento antes de eliminar o worktree e apaga apenas as bases de dados de teste desse ticket. Guarda as alterações úteis antes da limpeza Git. Se dois tickets tiverem de usar o mesmo emulador, a mesma base de dados ou uma porta fixa, sequencia-os com uma dependência: A para e liberta o recurso antes de B. A fila de integração serializa os commits, não os servidores.

Estes comandos pertencem ao repositório de exemplo; não constituem uma API de preparação do Singularity. O worktrees.json do Cursor e os scripts do Superset ou do Conductor não são apresentados aqui como configurações suportadas. Consulta os primeiros passos, a orquestração e o protocolo comparativo comum.

Um worktree Git é uma segunda pasta de trabalho associada ao mesmo repositório. Tem o seu próprio ramo e os seus próprios ficheiros extraídos, partilhando o histórico Git com a pasta principal. Assim, podes manter aberta uma alteração inacabada na tua árvore habitual enquanto outro trabalho avança noutro sítio.

Não é uma cópia completa do repositório nem um ramo abstrato sem ficheiros: as ferramentas, os testes e os editores podem abri-lo normalmente.

Com a definição ativa, cada execução de agente recebe o seu próprio worktree em .singularity-worktrees/<uuid>/ e um ramo dedicado. O fluxo pede ao agente que leia, modifique, teste e faça commit nessa pasta, para separar as suas alterações dos teus ficheiros sem commit.

Esta separação reduz a sobreposição de ficheiros entre agentes. Não constitui uma restrição do acesso do processo ao resto do sistema.

Não. Um worktree Git é uma pasta de trabalho separada, não uma sandbox do sistema. Por si só, não bloqueia nem a leitura nem a escrita na pasta principal e não limita as ligações de rede. Um agente, um comando, um teste ou um hook pode aceder a outros caminhos e serviços se as permissões do processo o autorizarem.

As restrições efetivas dependem do CLI do fornecedor, do seu modo sandbox, da sua política de aprovação e das permissões do sistema. Verifica os caminhos autorizados em leitura e escrita, o acesso à rede e os pedidos de aprovação antes de lançar o agente. Em Settings → AI Providers, consulta as opções do fornecedor escolhido: vê as definições dos fornecedores de IA, nomeadamente o modo sandbox e as aprovações do Codex e as opções do Gemini. As suas capacidades diferem; ativar os worktrees não acrescenta uma proteção universal do sistema.

1. O Singularity cria o worktree a partir do ramo base do ticket.
2. O agente trabalha no ramo dedicado, verifica o seu trabalho e cria nele os seus commits.
3. No fim, o Singularity volta a aplicar esses commits sobre a versão mais recente do ramo base.
4. Consoante as definições do quadro, o resultado é integrado automaticamente ou apresentado no separador Review.

A integração usa um rebase, não um merge. Os commits são reaplicados no topo da base para manter um histórico linear, sem commit de fusão. Se a base tiver avançado e surgir um conflito, a execução continua disponível para o resolver.

Tickets paralelos e conflitos semânticos

A pré-qualificação pode identificar dependências entre tickets ativos: se B depender de A, B aguarda a integração de A. A fila de integração ordena os tickets de um mesmo projeto. Após um rebase sobre uma base que avançou, o agente tem de voltar a executar os testes afetados e as verificações do projeto, e analisar os testes adicionados ou modificados pelos outros tickets.

Testes a passar não garantem a ausência de conflitos semânticos. Dois pedidos podem impor regras incompatíveis sem qualquer conflito Git. Especifica a regra partilhada nos critérios de aceitação e testa as interações. Uma contradição de negócio exige uma decisão; desativa a fusão automática para manter uma revisão humana. Vê o artigo sobre os tickets paralelos.

Abre Settings → Git → Worktrees para controlar o isolamento. Mantém Use git worktrees ativado para separar as pastas e os ramos das execuções. A fusão automática é independente: desativa-a se as execuções concluídas tiverem de aguardar a tua aprovação no separador Review.

Quando o isolamento está desativado, o agente escreve diretamente na tua árvore de trabalho. Não existe pasta nem ramo separados, pelo que o Singularity não tem nada para apresentar como trabalho isolado em Review.

No navegador, abre a secção de worktrees do projeto e depois o menu correspondente. Remove worktree apaga a sua pasta, mas mantém o seu ramo e os seus commits: o seu histórico continua recuperável.

Clean up worktrees também elimina as suas referências de ramo. Esta operação é irreversível. Verifica se todo o trabalho útil foi integrado ou guardado noutro sítio antes de confirmar.

O detalhe de um ticket mostra, em Work, o projeto, o ramo do worktree e o seu ramo de base. Na vista Git do Navigator, a secção Worktrees do projeto separa os worktrees por integrar e os integrados, com os respetivos contadores. Expande um para ver o seu último commit e os ficheiros modificados e, depois, escolhe Merge into main…, Graph ou Explore.

Explore abre o worktree no explorador de ficheiros: percorres e abres os ficheiros escritos pelo agente enquanto ele trabalha, sem tocar na tua própria cópia. Fecha a exploração para voltares ao teu projeto. Se o merge entrar em conflito, consulta resolver um conflito Git.

A partir do cockpit Git de um projeto, abre o separador Hooks para consultar os hooks detetados no repositório. Executam as verificações definidas pelo projeto nos momentos previstos pelo Git.

Se um hook pre-commit falhar, o commit não foi feito. Corrige a causa indicada — formatação, lint ou um teste, por exemplo — e volta a fazer o commit. Os ficheiros podem continuar modificados ou no índice: verifica o seu estado no cockpit Git.

O painel Hooks lista todos os hooks Git possíveis; os que estão instalados aparecem assinalados, com o respetivo número de linhas. O Singularity deteta o Husky (core.hooksPath) e lê os hooks no local onde o Git realmente os executa. O menu de um hook propõe Edit manually, Create a change ticket — um agente adapta o hook no seu worktree —, chmod +x para um hook não executável e Delete. Um hook em falta pode ser criado a partir de um modelo.

No compositor de commit, o indicador ⚡ seguido de um número anuncia os hooks que serão executados. A sua saída aparece num terminal; se um hook falhar, o commit não é feito: corrige a causa e tenta novamente.