Git Worktree: trabalhando com várias branches ao mesmo tempo

No artigo anterior, vimos os principais conceitos do Git: repositórios, commits, branches, merge, push, pull e o fluxo básico de desenvolvimento.

Se você já começou a utilizar branches no dia a dia, provavelmente encontrou uma situação parecida com esta:

Você está trabalhando em uma funcionalidade, possui vários arquivos modificados e, de repente, precisa parar tudo para corrigir um bug urgente em outra branch.

Uma opção seria salvar temporariamente suas alterações com git stash, trocar de branch, fazer a correção e depois retornar ao trabalho anterior.

Mas existe outra possibilidade:

manter as duas branches abertas ao mesmo tempo, cada uma em seu próprio diretório.

É exatamente isso que o git worktree permite fazer.

O problema que o Git Worktree resolve

Normalmente, quando clonamos um repositório, temos algo parecido com:

meu-projeto/
├── .git/
├── src/
├── README.md
└── ...

Esse diretório é a nossa working tree, ou árvore de trabalho.

Quando executamos:

git switch feature/login

os arquivos desse diretório são atualizados para representar a branch feature/login.

Se depois executarmos:

git switch main

o mesmo diretório passa a representar a main.

Ou seja, normalmente temos:

um repositório
      ↓
um diretório de trabalho
      ↓
uma branch por vez

Isso funciona muito bem na maioria das situações.

O problema aparece quando queremos trabalhar em duas branches simultaneamente.

Imagine que estamos desenvolvendo:

feature/login

e temos alterações ainda não concluídas.

Nesse momento surge um bug crítico que precisa ser corrigido na:

main

Poderíamos interromper nosso trabalho, salvar tudo com stash ou criar um commit temporário, trocar de branch, corrigir o problema e depois voltar.

Com git worktree, podemos simplesmente criar outro diretório para trabalhar na outra branch.

O que é Git Worktree?

O Git permite que um mesmo repositório possua várias árvores de trabalho.

Por exemplo:

meu-projeto/
    → feature/login

meu-projeto-hotfix/
    → hotfix/login

Os dois diretórios pertencem ao mesmo repositório Git, mas cada um possui seus próprios arquivos de trabalho e pode estar em uma branch diferente.

Conceitualmente:

                Repositório Git
                     │
             ┌───────┴───────┐
             │               │
             ↓               ↓
      meu-projeto/     meu-projeto-hotfix/
             │               │
             ↓               ↓
      feature/login       hotfix/login

Assim podemos manter diferentes partes do projeto abertas ao mesmo tempo sem precisar ficar constantemente alternando branches.

Worktree não é outro clone

Uma primeira ideia poderia ser simplesmente clonar o projeto novamente:

git clone URL meu-projeto-2

Isso também criaria outro diretório onde poderíamos trabalhar.

Mas existe uma diferença importante.

Um novo clone cria outro repositório Git independente.

Já um worktree continua vinculado ao mesmo repositório.

Podemos pensar assim:

git clone

repositório A
    ↓
diretório A

repositório B
    ↓
diretório B

Enquanto com worktrees temos:

             mesmo repositório
              /            \
             /              \
      worktree A          worktree B

Os worktrees compartilham grande parte das informações do repositório, enquanto cada árvore mantém o estado necessário para trabalhar de forma independente.

Por isso, para trabalhar temporariamente com várias branches do mesmo projeto, um worktree costuma ser mais apropriado do que criar vários clones.

Verificando os worktrees existentes

Dentro de um repositório Git, execute:

git worktree list

Em um projeto comum, que ainda não possui worktrees adicionais, o resultado será parecido com:

C:/projetos/meu-projeto  91fa57d [main]

Esse diretório é chamado de main worktree, ou árvore de trabalho principal.

Ela foi criada quando executamos originalmente:

git clone

ou:

git init

A partir dela podemos adicionar outras árvores de trabalho vinculadas ao mesmo repositório.

Criando nosso primeiro worktree

Imagine que nosso projeto esteja neste diretório:

projetos/
└── meu-projeto/

E estamos trabalhando normalmente na main.

Agora queremos iniciar uma nova funcionalidade chamada:

feature/login

Podemos criar uma nova branch e um novo worktree ao mesmo tempo:

git worktree add -b feature/login ../meu-projeto-login main

Vamos separar esse comando:

git worktree add

cria uma nova árvore de trabalho.

A opção:

-b feature/login

cria uma nova branch chamada feature/login.

O argumento:

../meu-projeto-login

define onde ficará o novo diretório.

E:

main

indica que a nova branch será criada a partir da main.

Depois do comando, teremos:

projetos/
├── meu-projeto/
│   └── main
│
└── meu-projeto-login/
    └── feature/login

Agora podemos acessar o novo diretório:

cd ../meu-projeto-login

E verificar:

git status

O Git mostrará que estamos na branch:

feature/login

Enquanto isso, o diretório original continua normalmente na main.

Trabalhando nos dois diretórios

Agora podemos abrir os dois diretórios no editor:

meu-projeto/

e:

meu-projeto-login/

Cada um possui seus próprios arquivos.

Podemos modificar arquivos no worktree da feature:

cd meu-projeto-login

Depois:

git add .
git commit -m "Adiciona formulário de login"

Enquanto isso, podemos continuar utilizando o outro diretório normalmente:

cd ../meu-projeto

E ele continuará na branch:

main

Não precisamos executar git switch constantemente.

Criando um worktree para uma branch existente

Também podemos utilizar uma branch que já existe.

Imagine que temos:

feature/dashboard

Para criar um worktree associado a ela:

git worktree add ../meu-projeto-dashboard feature/dashboard

Agora teremos:

meu-projeto/
    → main

meu-projeto-dashboard/
    → feature/dashboard

As duas branches podem ser utilizadas simultaneamente.

Uma branch normalmente só pode estar em um worktree

Existe uma regra importante ao trabalhar com worktrees.

Se a branch:

feature/login

já estiver aberta em:

meu-projeto-login/

e tentarmos utilizá-la também em outro worktree, o Git normalmente impedirá a operação.

Isso acontece para evitar que duas árvores de trabalho diferentes modifiquem simultaneamente o estado da mesma branch.

Ao executar:

git worktree list

podemos verificar facilmente qual branch está associada a cada diretório.

Por exemplo:

C:/projetos/meu-projeto        91fa57d [main]
C:/projetos/meu-projeto-login  42ab831 [feature/login]

Essa listagem é muito útil quando começamos a utilizar vários worktrees.

Um caso muito útil: corrigindo um bug urgente

Imagine a seguinte situação.

Estamos trabalhando em:

feature/nova-tela

O projeto possui vários arquivos modificados:

git status

Resultado:

modified: src/page.ts
modified: src/api.ts
modified: src/styles.css

O trabalho ainda está pela metade.

Nesse momento descobrimos um bug crítico em produção.

Sem worktree, poderíamos precisar:

salvar alterações
      ↓
trocar para main
      ↓
criar branch de hotfix
      ↓
corrigir
      ↓
voltar para feature
      ↓
restaurar alterações

Com worktree, podemos manter nosso trabalho completamente intacto e executar:

git worktree add -b hotfix/erro-login ../meu-projeto-hotfix main

Agora temos:

meu-projeto/
    → feature/nova-tela
    → alterações continuam exatamente onde estavam

meu-projeto-hotfix/
    → hotfix/erro-login
    → criado a partir da main

Entramos no novo diretório:

cd ../meu-projeto-hotfix

Fazemos a correção:

git add .
git commit -m "Corrige erro no login"

E enviamos a branch:

git push -u origin hotfix/erro-login

Enquanto isso, o desenvolvimento da feature/nova-tela nunca precisou ser interrompido ou guardado em um stash.

Esse é um dos cenários onde git worktree se torna especialmente útil.

Worktree ou stash?

Os dois recursos resolvem problemas diferentes.

git stash é útil quando queremos guardar alterações temporariamente:

Working Directory
      ↓
git stash
      ↓
alterações guardadas
      ↓
troca de branch

Já git worktree permite manter os dois ambientes ativos:

feature/
    → arquivos da feature

hotfix/
    → arquivos do hotfix

Uma comparação simplificada:

| Situação | Ferramenta | |---|---| | Preciso esconder algumas alterações rapidamente | git stash | | Quero alternar temporariamente de branch | git stash pode ser suficiente | | Quero manter duas branches abertas | git worktree | | Quero executar dois ambientes do projeto simultaneamente | git worktree | | Preciso corrigir algo sem mexer no trabalho atual | git worktree | | Quero comparar ou testar branches lado a lado | git worktree |

Nenhuma das duas ferramentas substitui a outra.

Elas resolvem situações diferentes.

Dependências e arquivos gerados

É importante perceber que cada worktree possui seu próprio diretório físico.

Em um projeto Node.js, por exemplo, podemos ter:

meu-projeto/
├── node_modules/
└── src/

meu-projeto-feature/
├── node_modules/
└── src/

Arquivos versionados pelo Git estarão presentes em cada árvore de trabalho.

Mas diretórios ignorados pelo Git, como:

node_modules/
dist/
build/

não são automaticamente compartilhados entre os worktrees.

Isso significa que, dependendo do projeto, pode ser necessário executar novamente:

npm install

ou:

npm ci

dentro do novo worktree.

O mesmo vale para builds, caches e outros arquivos gerados localmente.

Portanto, worktrees evitam duplicar o repositório Git completo, mas não significam necessariamente que todo o ambiente de desenvolvimento ocupará pouco espaço.

Removendo um worktree

Depois que terminarmos o trabalho, podemos remover a árvore adicional.

Primeiro podemos verificar os worktrees:

git worktree list

Depois removemos aquele que não precisamos mais:

git worktree remove ../meu-projeto-login

Isso remove o diretório da árvore de trabalho e seu vínculo com o repositório.

A branch, entretanto, continua existindo.

Se ela também não for mais necessária, podemos removê-la separadamente:

git branch -d feature/login

Assim:

git worktree remove

remove a árvore de trabalho.

Enquanto:

git branch -d

remove a branch.

São operações diferentes.

Evite apagar o diretório manualmente

Como um worktree possui informações administrativas registradas pelo Git, o ideal é removê-lo utilizando:

git worktree remove caminho

em vez de simplesmente apagar a pasta pelo explorador de arquivos.

Caso um diretório de worktree seja removido manualmente, podem permanecer informações antigas registradas pelo Git.

Para limpar essas referências podemos utilizar:

git worktree prune

Esse comando remove metadados de worktrees que não existem mais.

Movendo um worktree

Também é possível mover uma árvore de trabalho utilizando:

git worktree move caminho-atual novo-caminho

Por exemplo:

git worktree move ../meu-projeto-login ../features/login

O Git atualiza as informações necessárias para continuar reconhecendo aquela árvore de trabalho.

É preferível utilizar esse comando em vez de simplesmente mover a pasta manualmente.

Principais comandos

Os comandos mais importantes para começar são:

# Listar worktrees
git worktree list

# Criar worktree e uma nova branch
git worktree add -b feature/login ../meu-projeto-login main

# Criar worktree usando uma branch existente
git worktree add ../meu-projeto-dashboard feature/dashboard

# Remover um worktree
git worktree remove ../meu-projeto-login

# Mover um worktree
git worktree move caminho-atual novo-caminho

# Limpar referências de worktrees que não existem mais
git worktree prune

Na maior parte do tempo, add, list e remove já são suficientes para utilizar worktrees no dia a dia.

Um fluxo completo

Vamos imaginar que estamos desenvolvendo uma funcionalidade e precisamos corrigir um bug sem interromper nosso ambiente atual.

No diretório principal temos:

meu-projeto/
    → feature/relatorios

Criamos um worktree para o hotfix:

git worktree add -b hotfix/login ../meu-projeto-hotfix main

Entramos nele:

cd ../meu-projeto-hotfix

Instalamos as dependências, se necessário:

npm ci

Corrigimos o problema.

Depois:

git status
git add .
git commit -m "Corrige falha no login"
git push -u origin hotfix/login

Quando o trabalho estiver concluído, retornamos ao diretório principal:

cd ../meu-projeto

E removemos o worktree:

git worktree remove ../meu-projeto-hotfix

Se a branch também já puder ser removida:

git branch -d hotfix/login

Nosso trabalho original em feature/relatorios continua exatamente onde estava.

O modelo mental mais importante

No uso tradicional, podemos imaginar:

Repositório
    ↓
Working Tree
    ↓
uma branch por vez

Com worktrees:

                  Repositório
                 /     |      \
                /      |       \
               ↓       ↓        ↓
          Worktree A Worktree B Worktree C
               │       │        │
               ↓       ↓        ↓
             main   feature   hotfix

Cada worktree possui seus próprios arquivos de trabalho, mas todos continuam relacionados ao mesmo repositório.

Esse é o conceito principal.

git worktree não cria uma nova cópia independente do projeto.

Ele cria outra árvore de trabalho vinculada ao mesmo repositório.

Quando vale a pena usar Git Worktree?

Worktrees são especialmente úteis quando precisamos:

• trabalhar em duas ou mais branches ao mesmo tempo;
• corrigir um hotfix sem interromper uma feature em andamento;
• comparar duas versões do projeto lado a lado;
• executar testes em outra branch sem modificar o diretório atual;
• manter dois ambientes do projeto abertos simultaneamente;
• trabalhar em tarefas paralelas sem ficar alternando constantemente de branch.

Para um fluxo simples, continuar utilizando git switch é perfeitamente suficiente.

Mas quando começam a aparecer tarefas paralelas, interrupções frequentes ou vários contextos de desenvolvimento, git worktree pode simplificar bastante o trabalho.

Conclusão

Branches permitem criar diferentes linhas de desenvolvimento dentro de um repositório.

Porém, em um fluxo tradicional, o diretório de trabalho normalmente representa apenas uma dessas branches por vez.

git worktree remove essa limitação prática ao permitir criar várias árvores de trabalho vinculadas ao mesmo repositório.

Assim podemos ter algo como:

main
feature/login
hotfix/producao

abertos simultaneamente em diretórios diferentes.

Os comandos essenciais são poucos:

git worktree add
git worktree list
git worktree remove

E o modelo mental também é simples:

um repositório
      ↓
vários diretórios de trabalho
      ↓
várias branches simultaneamente

Depois que você começa a trabalhar com tarefas paralelas, hotfixes ou múltiplos ambientes de desenvolvimento, git worktree deixa de parecer apenas mais um comando do Git e passa a ser uma ferramenta bastante útil para organizar o fluxo de trabalho.