Chega de git stash: como trabalhar em múltiplas features em paralelo com git worktree

brduarte — Tue, 25 Aug 2026 12:08:39 +0000

Se você já perdeu tempo com essa sequência:

git stash
git checkout outra-branch
# resolve o problema urgente
git checkout branch-original
git stash pop

...só pra descobrir depois que esqueceu o que tinha no stash, ou que o venv/node_modules da outra branch estava desatualizado — este artigo é pra você.

O problema

Um repositório Git tradicional tem uma única pasta de trabalho ligada a uma branch por vez. Trocar de branch significa trocar todo o conteúdo dessa pasta. Isso funciona bem quando você faz uma coisa de cada vez, mas quebra assim que você precisa:

Revisar um PR urgente enquanto está no meio de uma feature grande
Rodar testes de uma branch enquanto edita outra
Manter ambientes de dependências diferentes (versões de libs, .env) para features distintas sem reinstalar tudo a cada troca

A saída mais comum é o stash, mas ele é frágil: some da vista, acumula, e é fácil esquecer o que tinha ali dentro.

A solução: `git worktree`

O git worktree permite ter várias pastas de trabalho simultâneas, cada uma vinculada a uma branch diferente, todas compartilhando o mesmo histórico de commits (o .git).

Pense em uma biblioteca central (o histórico do repositório) com várias mesas de leitura (as worktrees), cada uma com um livro diferente aberto. Você não precisa fechar um livro pra abrir outro.

O que é compartilhado, o que é separado

Compartilhado entre worktrees	Separado por worktree
Histórico de commits	Arquivos da working directory
Objetos do Git (blobs, trees)	Arquivos não versionados (`.env`, `venv`, `node_modules`)
Configuração do repositório	Saída do `git status`

Um commit feito em uma worktree aparece imediatamente no git log das outras — mas os arquivos físicos de cada pasta continuam independentes.

Colocando em prática

Criando uma worktree com branch nova

git worktree add ../meu-projeto-feature-x -b feature/nome-da-feature

Isso cria a pasta ../meu-projeto-feature-x, já com uma branch nova feature/nome-da-feature criada a partir do commit atual.

Criando uma worktree para uma branch que já existe

git worktree add ../meu-projeto-hotfix feature/hotfix-urgente

Útil quando a branch já veio de um colega ou de um PR aberto.

Listando as worktrees ativas

git worktree list

Saída parecida com:

/home/user/meu-projeto           abc1234 [main]
/home/user/meu-projeto-feature-x def5678 [feature/nome-da-feature]
/home/user/meu-projeto-hotfix    ghi9012 [feature/hotfix-urgente]

Removendo uma worktree depois do merge

git worktree remove ../meu-projeto-feature-x

Se a pasta tiver mudanças não commitadas, o Git avisa e pede --force.

Estrutura de pastas sugerida

~/projetos/meu-projeto/            # repo principal (main/develop)
~/projetos/meu-projeto-feature-x/  # worktree da feature X
~/projetos/meu-projeto-hotfix/     # worktree do hotfix urgente

Cada pasta pode ter seu próprio ambiente virtual, seu próprio servidor rodando em uma porta diferente, sua própria instância do editor aberta — sem um interferir no outro.

Convenção de nomes ligada ao board

Se seu time usa um board tipo Jira/Linear, vale manter o ID do card no nome da branch (e da worktree):

git worktree add ../meu-projeto-proj-123 -b feature/PROJ-123-descricao-curta

Isso facilita rastrear no PR, no CI e em qualquer extração de métricas de fluxo (lead time, deployment frequency) que você faça a partir do histórico de branches.

Dicas práticas

1. Evite worktrees de vida muito longa. O worktree resolve o problema de contexto simultâneo, não o de branches gigantes. Combine com features pequenas e merges frequentes — se uma feature for demorar semanas, considere feature flags em vez de manter a branch (e a worktree) viva por muito tempo.

2. Cuidado com portas e serviços locais. Se cada worktree sobe um servidor de desenvolvimento, defina portas diferentes por ambiente (.env.local com PORT=8001, por exemplo) pra evitar conflito.

3. .gitignore continua valendo por pasta. Arquivos como .env, venv/, node_modules/ não são compartilhados automaticamente — cada worktree precisa da própria cópia (ou de um pip install / npm install local).

4. Worktrees podem viver fora do diretório do repo. Não precisam ficar como subpastas; o exemplo usa ../ só por convenção de organização.

Por que isso importa

A alternativa mais comum ao worktree — múltiplos clones separados do mesmo repositório — resolve o problema de paralelismo, mas duplica o histórico completo em disco e obriga a sincronizar remotes manualmente entre os clones. O worktree resolve o mesmo problema mantendo um único .git como fonte de verdade, com o custo de espaço em disco apenas dos arquivos de trabalho, não do histórico inteiro.

Se seu fluxo de trabalho envolve alternar entre features, revisar PRs no meio de outra tarefa, ou manter hotfixes prontos pra aplicar sem abandonar o que está em andamento, o git worktree provavelmente vai economizar mais tempo do que qualquer alias de stash que você já criou.

Já usa git worktree no seu fluxo? Como você organiza as pastas e os ambientes de cada worktree? Comenta aí.

Por que evitar incluir o arquivo .env no processo de build do projeto

brduarte — Mon, 27 Mar 2023 03:00:13 +0000

O arquivo .env é um componente importante de muitos projetos, especialmente aqueles que dependem de variáveis de ambiente para funcionar corretamente. No entanto, em alguns casos, pode ser uma má prática incluir o arquivo .env no processo de build do projeto.

A principal razão para não incluir o arquivo .env no processo de build é a segurança. O arquivo .env geralmente contém informações sensíveis, como senhas, chaves de API e outras credenciais. Se essas informações forem incluídas no processo de build, elas podem ser acessadas por qualquer pessoa com acesso ao código fonte ou ao pacote compilado. Isso pode levar a graves problemas de segurança, como invasões de sistemas, roubo de dados e comprometimento de credenciais.

Além disso, incluir o arquivo .env no processo de build pode tornar o processo mais complexo e demorado. Se o arquivo .env contiver muitas variáveis de ambiente ou informações sensíveis, ele pode aumentar significativamente o tamanho do pacote final e, consequentemente, o tempo de compilação e implantação. Isso pode afetar negativamente o desempenho e a eficiência do projeto.

Uma solução para evitar incluir o arquivo .env no processo de build é separá-lo do restante do código fonte e manter as informações sensíveis em um local seguro, como um servidor seguro ou um cofre de segredos. Em vez de incluir as informações diretamente no arquivo .env, é possível fazer referência a elas por meio de variáveis de ambiente definidas no sistema operacional ou em outro lugar seguro. Isso permite que o projeto seja compilado e implantado sem expor informações sensíveis a usuários não autorizados.

Em resumo, incluir o arquivo .env no processo de build pode ser uma má prática de segurança e pode tornar o processo mais complexo e demorado. É importante considerar cuidadosamente a melhor maneira de gerenciar informações sensíveis em projetos que dependem de variáveis de ambiente e tomar medidas para garantir a segurança e eficiência do processo de build.

DEV Community: brduarte