Pular para o conteúdo
Setup do Dev
Desenvolvimento

Como usar o git worktree para corrigir um bug sem largar o branch em que você estava

Um worktree abre outro branch numa pasta ao lado, sem stash e sem clonar de novo. No nosso teste, ele ocupou 1,4 MB onde um clone completo ocupou 41 MB.

Por Setup do Dev
4 min de leitura
Compartilhar
Capa com o título Dois branches abertos, sem stash, o número 1,4 MB e a saída do git worktree list com duas pastas

Você está no meio de uma feature, com arquivos alterados que ainda não dá para commitar, e chega o pedido: corrigir o cálculo do frete em produção, agora. O caminho de sempre é o git stash, trocar de branch, corrigir, voltar e torcer para o stash aplicar sem conflito.

O git worktree resolve de outro jeito: abre o branch do hotfix numa segunda pasta, ligada ao mesmo repositório, e deixa a feature exatamente como estava. Testamos no Git 2.56, num repositório de teste, com a saída real de cada comando.

Criar a segunda pasta

No repositório da loja, com a feature pela metade:

$ git status --short
 M app.txt

$ git worktree add -b hotfix/frete ../loja-hotfix main
Preparing worktree (new branch 'hotfix/frete')
HEAD is now at a2138f6 versao 1

O comando cria a pasta ../loja-hotfix, cria nela o branch hotfix/frete a partir do main e faz o checkout. A pasta original não muda: o app.txt continua alterado, no branch da feature.

$ git worktree list
.../loja         a2138f6 [feature/checkout]
.../loja-hotfix  a2138f6 [hotfix/frete]

Trabalhar no hotfix

A pasta nova é uma cópia de trabalho comum. Abra no editor, corrija, rode os testes e faça o commit:

$ cd ../loja-hotfix
$ git commit -am "corrige frete"
$ git log --oneline -2
0f2a264 corrige frete
a2138f6 versao 1

O commit vai para o mesmo repositório. De volta à pasta da loja, o branch hotfix/frete já está lá, com o commit, pronto para o push ou o merge. E a feature continuava intacta: o git status na pasta original mostrou o mesmo M app.txt de antes.

Diagrama de um repositório com duas pastas de trabalho, uma no branch da feature e outra no branch do hotfix, as duas usando a mesma pasta .git, e a comparação de espaço com um clone
Duas pastas, um repositório só: o worktree no nosso teste, com o espaço de cada um

Por que não clonar de novo

Dava para resolver com um segundo clone, e é o que muita gente faz. A diferença está no histórico. O worktree não copia a pasta .git: no lugar dela, ele cria um arquivo .git de uma linha, que aponta para o repositório principal.

$ cat ../loja-hotfix/.git
gitdir: .../loja/.git/worktrees/loja-hotfix

Num repositório de teste com 40 commits e 39 MB de histórico, o worktree ocupou 1,4 MB, só os arquivos de trabalho. Um clone completo (git clone --no-local) ocupou 41 MB, porque leva o histórico inteiro de novo. Num repositório de anos, a diferença é de gigabytes. E o worktree enxerga na hora os branches e commits da outra pasta, sem fetch.

O que ele não compartilha são as dependências: a pasta nova não tem node_modules nem vendor, e precisa do npm install ou do composer install dela.

As duas travas que o Git põe

A primeira: o mesmo branch não pode estar aberto em duas pastas. Tentamos abrir o hotfix/frete numa terceira:

$ git worktree add ../outra hotfix/frete
fatal: 'hotfix/frete' is already used by worktree at '.../loja-hotfix'

A documentação do git-worktree explica o motivo: duas pastas no mesmo branch ficariam disputando o mesmo ponteiro. A segunda trava protege o trabalho não salvo. Com uma alteração pendente no hotfix, o Git recusou remover a pasta:

$ git worktree remove ../loja-hotfix
fatal: '../loja-hotfix' contains modified or untracked files, use --force to delete it

Revisar um pull request sem criar branch

O worktree também serve para olhar o código de outra pessoa sem mexer no seu. Com --detach, ele abre um commit específico, sem criar branch nenhum:

$ git worktree add --detach ../revisao hotfix/frete
Preparing worktree (detached HEAD 0f2a264)
HEAD is now at 0f2a264 corrige frete

Na pasta ../revisao, dá para rodar o projeto, os testes e o linter do jeito que o colega mandou, enquanto a sua feature continua aberta na outra pasta. Terminada a revisão, a pasta sai sem deixar branch para trás.

Para uma pasta que fica num pendrive ou num disco de rede, que às vezes some, existe o lock. Com ele, o Git recusa remover a pasta e o prune não a limpa, mesmo quando ela não está à vista:

$ git worktree lock --reason "pendrive" ../revisao
$ git worktree remove ../revisao
fatal: cannot remove a locked working tree, lock reason: pendrive

O git worktree unlock devolve a pasta ao normal.

Remover direito, e o que fazer se apagou a pasta na mão

O jeito certo de terminar é git worktree remove ../loja-hotfix, depois de commitar ou descartar o que estiver lá. O branch continua no repositório; só a pasta sai.

Se a pasta foi apagada pelo explorador de arquivos, o Git continua achando que ela existe. No nosso teste, o git worktree list passou a marcá-la como prunable, e o prune limpou o registro:

$ git worktree prune -v
Removing worktrees/loja-hotfix: gitdir file points to non-existent location

Mesmo depois disso, o branch hotfix/frete e o commit “corrige frete” continuavam no repositório. Apagar a pasta não apaga o trabalho commitado.

Para quem troca de contexto várias vezes por dia, a rotina fica assim: uma pasta por tarefa em andamento, um worktree remove quando ela termina, e o stash de volta ao lugar dele, que é guardar mudança pequena por pouco tempo.

Fonte: Documentação do Git: git-worktree

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. Criar a segunda pasta
  2. Trabalhar no hotfix
  3. Por que não clonar de novo
  4. As duas travas que o Git põe
  5. Revisar um pull request sem criar branch
  6. Remover direito, e o que fazer se apagou a pasta na mão

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.