Worktrees
Trabalhe em uma branch e uma pasta separadas sem alterar sua cópia principal do projeto.
Um worktree é uma segunda pasta de trabalho do mesmo repositório Git, normalmente em outra branch. Ele permite separar uma tarefa sem mexer nos arquivos da sua cópia principal.
Crie um worktree gerenciado
Execute o Clarvis a partir de qualquer checkout do repositório Git:
clarvis --worktree docs-guideO Clarvis cria a branch clarvis/docs-guide em um checkout gerenciado abaixo do checkout principal do repositório ou reabre o checkout já registrado pelo Git para essa branch. Informe somente o nome. O Clarvis controla o prefixo de branch clarvis/.
Omita o nome quando quiser que o Clarvis gere um:
clarvis --worktreeOs nomes devem ter de 1 a 80 caracteres ASCII, começar por letra ou dígito e usar apenas letras, dígitos, pontos, sublinhados ou hífens. Também precisam formar um segmento de branch Git válido; por isso, .., @{, ponto final e sufixo .lock são recusados. A seleção do worktree termina antes de a sessão, o kernel ou a TUI começar. Assim, toda operação de arquivo e toda execução usa esse mesmo checkout.
Continue o trabalho no mesmo checkout
Use o mesmo nome de worktree nas próximas inicializações:
clarvis --worktree docs-guide --continueO Clarvis usa a lista de worktrees registrada pelo Git como fonte da verdade. Ele não mantém um registro separado de worktrees. Se o checkout gerenciado pelo Clarvis tiver sido removido, mas sua branch ainda existir, o mesmo comando poderá recriá-lo a partir dessa branch. Se o Git já registrar a branch em um worktree externo, o Clarvis reabre esse caminho em vez de movê-lo.
Não é possível trocar de worktree dentro de uma sessão. Saia e inicie o Clarvis novamente com o nome desejado para que todos os serviços usem a mesma identidade de workspace.
Mantenha ou remova o checkout ao sair
Quando o worktree estiver limpo, o fluxo normal de saída com dois Ctrl+C pergunta se você deseja remover o checkout:
- N mantém o checkout e sai.
- Y remove o checkout limpo e sai.
- Escape cancela a saída.
Se o checkout tiver alterações pendentes, o Clarvis o mantém e não oferece a remoção. Esse caminho nunca usa uma operação Git forçada, e a branch clarvis/<name> é preservada nos dois casos.
Atenção
Um checkout limpo significa apenas que seus arquivos não têm alterações pendentes. Isso não significa que a branch foi integrada ou publicada, nem que é seguro excluí-la. Integre ou remova a branch com seu fluxo Git normal.
Onde ficam os checkouts gerenciados
O Clarvis armazena os checkouts gerenciados em:
<primary-checkout>/.clarvis/worktrees/<name>Antes de criar um checkout, ele garante que o .clarvis/.gitignore do checkout principal exclua worktrees/. Isso evita que os arquivos do checkout aninhado sejam adicionados por acidente a partir do workspace principal. Worktrees externos criados por você permanecem fora desse caminho de limpeza gerenciada.