Branching & Merging

Branches de funcionalidades, merge e estratégias de rebase para serviços Python que enviam pyproject.toml, lockfiles e migrações Alembic juntos.

Receita

git checkout main && git pull --rebase origin main
git checkout -b feat/api-91-refunds
# trabalhe...
git fetch origin && git rebase origin/main
git push -u origin feat/api-91-refunds
# abra PR -> squash merge para main após CI verde

Quando usar isso:

• Iniciando trabalho de ticket isolado de main
• Integrando o main mais recente antes da revisão do PR
• Criando trains release/x.y com aplicativos Django/FastAPI
• Backporting de hotfixes com cherry-pick

Exemplo de Trabalho

# Ciclo de vida do branch de funcionalidade
git switch -c feat/worker-retries main
uv run pytest -q
git commit -am "feat(worker): retry smtp errors [WRK-12]"
git fetch origin
git rebase origin/main
# conflito em uv.lock -> regenere o lock após resolver pyproject
uv lock
git add pyproject.toml uv.lock
git rebase --continue
git push --force-with-lease origin feat/worker-retries

O que isso demonstra:

• Branch a partir de main atualizado
• Rebase integra upstream sem commits de merge no branch de funcionalidade
• Conflitos de lockfile resolvidos por regeneração, não edição manual
• Force-with-lease push forçado seguro após rebase

Mergulho Profundo

Como Funciona

• Fast-forward - O ponteiro do branch avança quando não há commits divergentes.
• Commit de merge - Combina dois históricos com um nó de merge.
• Rebase - Reexecuta commits em uma nova base - reescreve SHAs.
• Squash merge - O PR se torna um único commit em main.

Tipos de Branch

Notas Python

# Cherry-pick de correção de migração para o branch de release
git switch release/2.3
git cherry-pick abc1234  # commit com revisão Alembic
uv run alembic upgrade head
uv run pytest -q

Armadilhas

• Branches de funcionalidades de longa duração - Conflitos de lockfile e migração explodem. Correção: faça merge ou rebase de main diariamente.
• Squash perdendo informações de revert - Difícil de usar git bisect. Correção: título de PR significativo se torna a mensagem de squash.
• Rebase após o início da revisão do PR - Confunde revisores com force push. Correção: comunique ou faça merge em vez disso.
• Fazer merge de main em release/* - Puxa funcionalidades não verificadas. Correção: apenas cherry-pick.
• Conflitos de revisão Alembic - Cabeças duplicadas após branches paralelos. Correção: faça merge das cabeças de migração antes da implantação.
• Conflitos de wheel binária - Raro no git; artefatos grandes não devem estar no repositório. Correção: Git LFS ou índice de pacotes.

Alternativas

FAQs

Relacionados

• Comandos Essenciais do Git - comandos diários
• Checklist de Resolução de Conflitos de Merge - processo calmo
• Git Worktrees - checkouts paralelos
• Pipelines de CI/CD - proteções de branch

Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.