Git Worktrees

Git worktrees permitem que você faça checkout de múltiplos branches em diretórios separados, compartilhando um único banco de dados .git. Desenvolvedores Rust os utilizam para revisões paralelas de PRs, branches de hotfix e execuções longas de cargo build sem a necessidade de stash.

Receita

# Do repositório principal
git worktree add ../billing-api-review origin/feat/billing-tax
cd ../billing-api-review
cargo test -q
 
# Remover quando terminar
cd ../billing-api
git worktree remove ../billing-api-review

Quando usar isso:

Revisando um PR de um colega enquanto está no meio de um recurso localmente
Executando build de release em release/* enquanto desenvolve em main
Fazendo bissecção de uma regressão sem perturbar o espaço de trabalho atual

Exemplo de Trabalho

git worktree list
git worktree add -b hotfix/2.5.1 ../hotfix v2.5.0
cd ../hotfix
cargo build --release
./target/release/my-service --version
 
git worktree prune  # limpa metadados desatualizados

O que isso demonstra:

Cada worktree tem seu próprio diretório de trabalho e target/ (a menos que compartilhado via configuração)
Um branch não pode ser feito checkout duas vezes - worktrees impõem exclusividade
prune remove registros de worktree inválidos

Mergulho Profundo

Convenção de Layout

~/code/billing-api/          # desenvolvimento principal (feat/*)
~/code/billing-api-review/   # checkout de PR efêmero
~/code/billing-api-hotfix/   # hotfix de produção

rust-analyzer

Aponte o editor para um worktree de cada vez ou use workspace multi-root com moderação - cada árvore carrega um target/ separado para diagnósticos corretos.

Armadilhas

Mesmo branch duas vezes - Git recusa. Correção: crie o worktree em um HEAD desanexado ou com um nome de branch diferente.
Diretórios de worktree esquecidos - acúmulo de disco. Correção: execute git worktree list semanalmente; remova árvores de PR mescladas.
target compartilhado via symlink - pode confundir builds incrementais entre branches. Correção: separe target por árvore, a menos que seja um sccache intencional.
Trabalho não commitado na remoção - perda de dados. Correção: comite ou use stash antes de worktree remove.
Scripts de CI assumindo caminho - cwd codificado quebra. Correção: parametrize a raiz do repositório.

Alternativas

Alternativa	Use Quando	Não Use Quando
`git stash`	Troca rápida de contexto	Builds longos para reproduzir
Segundo `git clone`	Isolamento completo	Duplicação de disco e fetch
Contêiner de desenvolvimento Docker	Ambiente reproduzível	Revisão simples

FAQs

Quantos worktrees?

Normalmente 2-4 ativos; remova os excedentes.

Worktrees e submodules?

Suportado; inicialize submodules por worktree após adicionar.

Padrão de repositório bare?

Avançado: repositório central bare com todos os worktrees como diretórios irmãos.

Relacionados

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Receita

# Do repositório principal
git worktree add ../billing-api-review origin/feat/billing-tax
cd ../billing-api-review
cargo test -q
 
# Remover quando terminar
cd ../billing-api
git worktree remove ../billing-api-review

Quando usar isso:

Revisando um PR de um colega enquanto está no meio de um recurso localmente

Executando build de release em release/* enquanto desenvolve em main

Fazendo bissecção de uma regressão sem perturbar o espaço de trabalho atual

Exemplo de Trabalho

git worktree list
git worktree add -b hotfix/2.5.1 ../hotfix v2.5.0
cd ../hotfix
cargo build --release
./target/release/my-service --version
 
git worktree prune  # limpa metadados desatualizados

O que isso demonstra:

Cada worktree tem seu próprio diretório de trabalho e target/ (a menos que compartilhado via configuração)

Um branch não pode ser feito checkout duas vezes - worktrees impõem exclusividade

prune remove registros de worktree inválidos

Mergulho Profundo

~/code/billing-api/          # desenvolvimento principal (feat/*)
~/code/billing-api-review/   # checkout de PR efêmero
~/code/billing-api-hotfix/   # hotfix de produção

Aponte o editor para um worktree de cada vez ou use workspace multi-root com moderação - cada árvore carrega um target/ separado para diagnósticos corretos.

Armadilhas

Mesmo branch duas vezes - Git recusa. Correção: crie o worktree em um HEAD desanexado ou com um nome de branch diferente.

Diretórios de worktree esquecidos - acúmulo de disco. Correção: execute git worktree list semanalmente; remova árvores de PR mescladas.

target compartilhado via symlink - pode confundir builds incrementais entre branches. Correção: separe target por árvore, a menos que seja um sccache intencional.

Trabalho não commitado na remoção - perda de dados. Correção: comite ou use stash antes de worktree remove.

Scripts de CI assumindo caminho - cwd codificado quebra. Correção: parametrize a raiz do repositório.

Alternativa

Use Quando

Não Use Quando

git stash

Troca rápida de contexto

Builds longos para reproduzir

Segundo git clone

Isolamento completo

Duplicação de disco e fetch

Contêiner de desenvolvimento Docker

Ambiente reproduzível

Revisão simples

Git Worktrees

Buscar na documentação

Git Worktrees