Git Worktree

O Git Worktree permite trabalhar com múltiplas branches do mesmo repositório simultaneamente, cada uma em um diretório diferente.

Isso é útil, por exemplo, para manter uma branch de desenvolvimento aberta enquanto trabalha em outra branch sem precisar ficar fazendo git checkout/git switch constantemente.

Comandos

git worktree add        # adiciona um novo worktree ao repositório
git worktree remove     # remove um worktree
git worktree prune      # remove informações de worktrees que não existem mais no sistema de arquivos
git worktree lock       # bloqueia um worktree para impedir que ele seja removido ou podado automaticamente
git worktree unlock     # remove o bloqueio de um worktree
git worktree list       # lista todos os worktrees associados ao repositório.
git worktree move       # move um worktree para outro diretório.
git worktree repair     # corrige referências de worktrees quando os caminhos registrados pelo Git ficaram inconsistentes.

Add uso:

git worktree add <path> <branch>

Parâmetros do add

<path> - diretório onde o novo worktree será criado.

git worktree add ../feature-login feature/login

<branch> - branch que será utilizada no novo worktree.

git worktree add ../feature-login feature/login

-b <new-branch> - cria uma nova branch e já adiciona o worktree utilizando essa branch.

git worktree add -b feature/login ../feature-login

-B <new-branch> - cria ou redefine a branch informada e adiciona o worktree.

git worktree add -B feature/login ../feature-login

--detach - cria o worktree sem associá-lo a uma branch.

git worktree add --detach ../teste

--force - permite criar um worktree mesmo quando o Git normalmente impediria a operação, como em algumas situações em que a branch já está associada a outro worktree.

git worktree add --force ../feature-login feature/login

Remove uso:

git worktree remove <worktree>

Exemplo:

git worktree remove ../feature-login

Parâmetros do remove

--force - força a remoção do worktree, inclusive quando existem alterações não commitadas.

git worktree remove --force ../feature-login

A remoção do worktree não remove a branch associada a ele.

Prune uso:

git worktree prune

Por exemplo, se um diretório de worktree foi apagado manualmente:

rm -rf ../feature-login

O Git ainda pode manter informações sobre esse worktree. O prune limpa essas referências.

Parâmetros do prune

-n / --dry-run - mostra o que seria removido sem executar a remoção.

git worktree prune --dry-run

-v / --verbose - exibe informações adicionais durante a limpeza.

git worktree prune --verbose

Lock uso:

git worktree lock <worktree>

Parâmetros do lock

--reason <string> - adiciona uma justificativa para o bloqueio.

git worktree lock --reason "Worktree utilizado para desenvolvimento" ../feature-login

O motivo pode ser visualizado posteriormente com:

git worktree list

Unlock uso:

git worktree unlock <worktree>

Exemplo:

git worktree unlock ../feature-login

List uso:

git worktree list

Exemplo de saída:

/home/dev/projeto       abc1234 [main]
/home/dev/projeto-dev   def5678 [dev]
/home/dev/projeto-fix   987abcd [feature/fix]

Parâmetros do list

--porcelain - exibe as informações em um formato mais detalhado e estruturado.

git worktree list --porcelain

-v / --verbose - exibe informações adicionais.

git worktree list --verbose

Move uso:

git worktree move <worktree> <new-path>

Exemplo:

git worktree move ../feature-login ../login

Isso altera o caminho registrado pelo Git sem precisar remover e recriar o worktree.

Repair uso:

git worktree repair

Também pode ser utilizado informando caminhos específicos:

git worktree repair <path>

É especialmente útil depois de mover manualmente um diretório ou alterar a localização do repositório principal.

Exemplo de uso completo

existe um projeto:

projeto/

E você esteja trabalhando na branch main.

Para criar um worktree para a branch dev:

git worktree add ../projeto-dev dev

A estrutura ficará:

projeto/
└── ...

projeto-dev/
└── ...

Agora é possível trabalhar simultaneamente:

projeto/       → main
projeto-dev/   → dev

Cada diretório possui seu próprio estado de trabalho, mas ambos utilizam o mesmo repositório Git.

Para visualizar:

git worktree list

Para remover quando terminar:

git worktree remove ../projeto-dev

Fluxo básico

# Criar worktree
git worktree add ../projeto-dev dev

# Listar worktrees
git worktree list

# Trabalhar normalmente
cd ../projeto-dev

# Voltar ao projeto principal
cd ../projeto

# Remover o worktree
git worktree remove ../projeto-dev

# Limpar referências antigas, se necessário
git worktree prune

Explicação Teórica

Uma explicação dos conceitos e dos principais comandos do Git Worktree: Ver explicação teórica

Explicação Prática

Exemplo prático utilizando um pequeno projeto em Python para demonstrar o uso do Worktree em uma situação real de desenvolvimento: Ver explicação prática

Projeto

Pequeno sistema desenvolvido em Python utilizado nos exemplos práticos: Ver projeto