Por que fazer git stash a cada troca de branch? O que é Git Worktree? Diferenças entre Git Worktree e Git Branch? Como usar o Git Worktree para criar um fluxo de desenvolvimento multi-thread de alta eficiência

Sat, 08 Aug 2026 08:29:00 +0800

Você já passou por esta situação? Está no meio do desenvolvimento de uma funcionalidade complexa quando, de repente, surge um Bug urgente que precisa ser corrigido imediatamente.

Para alternar de branch, você é forçado a executar relutantemente git stash para esconder o seu código inacabado. Após corrigir o Bug e voltar, precisa fazer git stash pop com todo o cuidado, enfrentando às vezes o pesadelo dos conflitos de código (conflict).

Na verdade, o Git há muito tempo possui uma ferramenta extremamente poderosa para resolver este problema: o Git Worktree.

Diga adeus à troca caótica de branches e ao Stash, e abrace o desenvolvimento multi-thread com Worktree

Este artigo vai te guiar pelo funcionamento essencial e pelo uso prático no mundo real.

Qual é a diferença entre Git Worktree e Git Branch?

Para entender o Git Worktree, primeiro vamos esclarecer como ele se diferencia do Git Branch.

Podemos comparar o controle de versão com a leitura de um livro físico:

Commit é a edição / versão do livro
Branch é um marcador de página posicionado em uma página específica
Worktree é a mesa de trabalho onde você abre o livro

No método tradicional, temos apenas uma mesa de trabalho. Sempre que queremos mudar de marcador de página, precisamos recolher todos os papéis em alteração sobre a mesa ou guardá-los na gaveta (ou seja, git stash).

Já o Git Worktree permite que você tenha várias mesas de trabalho independentes ao mesmo tempo.

Item de comparação	Git Branch	Git Worktree
Conceito de Workspace	Compartilha um único diretório físico de trabalho	Possui múltiplos diretórios físicos de trabalho independentes
Custo de troca de branch	Exige commit, stash ou salvar alterações	Sem stash; basta alternar de diretório
Isolamento e segurança	Arquivos não commitados podem gerar conflitos ou resíduos	Diretórios totalmente isolados; alterações não se interferem
Histórico de alterações	Compartilha histórico de Commit e branches do Git	Compartilha histórico de Commit e branches do Git

A branch ativa, o Staging Area e as alterações não commitadas de cada Worktree são totalmente independentes, mas elas compartilham todo o histórico de Commit e registros de branch.

Branch é o marcador de versão, enquanto Worktree é a mesa de trabalho física

Dessa forma, quando você precisar alternar de tarefa, basta abrir outra pasta de diretório sem alterar em nada o seu estado de desenvolvimento atual.

Como começar a usar o Git Worktree?

Ao adotar o Git Worktree em projetos reais, um bom planejamento de diretórios torna o desenvolvimento muito mais fluido.

Recomenda-se manter o diretório do projeto original clonado com git clone como a sede limpa main, e colocar os novos diretórios Worktree fora do projeto principal (por exemplo, ../my-app-worktrees), evitando erros de escaneamento recursivo pelas ferramentas de desenvolvimento.

O fluxo de comandos mais comum é o seguinte:

Fluxo	Comando
1. Criar um novo Worktree e simultaneamente uma nova branch	`git worktree add ../my-app-worktrees/feature-login -b feature-login`
2. Visualizar a lista de todos os Worktrees ativos	`git worktree list`

O Git Worktree é especialmente adequado para gerenciar tarefas de desenvolvimento de um AI Agent.

Você pode atribuir um diretório Worktree independente ao AI Agent para que ele faça alterações e testes à vontade, enquanto os desenvolvedores humanos realizam a revisão de código (Review) e testes em outro Worktree.

Dê ao AI Agent um Worktree isolado para processar em paralelo o desenvolvimento por IA e a revisão humana

Ambos operam em seus respectivos diretórios físicos, de forma segura e clara.

Como fazer o merge e a limpeza segura após concluir o desenvolvimento?

Após concluir o desenvolvimento em um Worktree independente, como integrar os resultados e fazer a limpeza?

Lembre-se de um conceito importante: O diretório Worktree em si não precisa de merge, o que realmente precisa ser mesclado é a Branch.

Você só precisa retornar ao diretório da mesa de trabalho main e executar o comando git merge na branch da funcionalidade correspondente para concluir a integração.

Para a limpeza, siga o procedimento padrão de dois passos:

Passo	Comando
1. Remover o diretório físico do Worktree	`git worktree remove ../my-app-worktrees/feature-login`
2. Excluir a branch de funcionalidade concluída	`git branch -d feature-login`

Remova primeiro o diretório Worktree e depois exclua a Branch

Certifique-se de usar sempre o comando git worktree remove para realizar a limpeza, em vez de apagar a pasta manualmente no gerenciador de arquivos.

Quais são as armadilhas comuns ao usar o Git Worktree?

Embora o Git Worktree seja extremamente conveniente, existem algumas armadilhas que exigem atenção especial.

Armadilha 1: Alterações não commitadas serão perdidas

Embora a remoção do Worktree não exclua a Branch em si, se você ainda tiver alterações sem commit nesse diretório, a remoção forçada do diretório Worktree fará com que essas modificações sejam perdidas para sempre.

Armadilha 2: Conflito de ocupação de branch

O mecanismo de proteção do Git não permite fazer Checkout da mesma Branch em dois Worktrees diferentes simultaneamente. Se você tentar alternar para uma branch já em uso em um segundo Worktree, o Git bloqueará a ação e exibirá uma mensagem de erro.

Forçar a exclusão de um Worktree causará a perda de alterações sem Commit

Ao dominar essas características e princípios, você evitará esses problemas.

Conclusão

Com o Git Worktree, podemos dizer adeus à troca caótica de branches e ao processo git stash, alcançando um verdadeiro desenvolvimento multi-thread.

Na próxima vez que precisar corrigir um Bug urgente, desenvolver várias funcionalidades simultaneamente ou atribuir tarefas de programação a um AI Agent, experimente abrir uma nova mesa de trabalho!

Reference

Git - git-worktree Documentation

Git Worktree on Dev TLDRLSS