Checklist de Resolução de Conflitos de Merge
Um processo calmo e repetível para resolver conflitos de merge e rebase do Git em repositórios Python - especialmente pyproject.toml, uv.lock e migrações Alembic.
Como Usar Este Checklist
- Percorra os itens em ordem durante um conflito ativo - não pule direto para a edição de marcadores.
- Um arquivo totalmente resolvido e testado antes de passar para o próximo, quando os conflitos forem grandes.
- Se ficar preso em um arquivo por mais de 30 minutos, pause e pareie - migrações e lockfiles se beneficiam de um segundo revisor.
- Registre o que causou o conflito na descrição do PR para evitar colisões repetidas.
Fase 1 - Estabilizar
- Confirme o tipo de operação: Saiba se você está em
merge,rebaseoucherry-pick-git statusmostra o estado atual. - Liste os arquivos em conflito:
git diff --name-only --diff-filter=U- esperepyproject.toml,uv.lock,alembic/versions/*.py. - Aborte se estiver no branch errado:
git merge --abortougit rebase --abortquando você começou na base incorreta. - Faça stash de trabalho não relacionado:
git stash push -m "pre-conflito"se edições não commitadas se misturarem com a resolução de conflitos. - Busque o último remoto:
git fetch originpara que você resolva contra omainatual, não uma cópia local desatualizada.
Fase 2 - Entender
- Leia ambos os lados: Abra o arquivo em conflito -
<<<<<<<,=======,>>>>>>>marcam o seu vs. o recebido. - Verifique as mensagens de commit:
git log --oneline --left-right HEAD...MERGE_HEAD(merge) ou commits recebidos no rebase. - Identifique a intenção semântica: O conflito é cosmético (ordem de importação) ou comportamental (versão da dependência, revisão da migração)?
- Regra do Lockfile: Para
uv.lock/poetry.lock- escolha o lado vencedor dopyproject.toml, delete os marcadores de conflito, executeuv lock. - Regra de Migração: Para Alembic - nunca duplique IDs de revisão; pode ser necessário
alembic mergeheads após a resolução.
Fase 3 - Resolver
- Resolva um arquivo por vez: Remova todos os marcadores de conflito; deixe sintaxe Python/TOML válida.
- Prefira a política de dependência upstream: Quando em dúvida sobre a versão da biblioteca, alinhe com
main, a menos que o ticket exija um aumento. - Execute o formatador em Python tocado:
uv run ruff formatnos arquivos.pyresolvidos. - Adicione o arquivo resolvido:
git add <arquivo>somente quando os marcadores forem totalmente removidos -git diff --checkdetecta sobras. - Continue a operação:
git rebase --continueou complete o commit de merge após todos os arquivos serem adicionados.
Fase 4 - Verificar
- Sincronize o ambiente:
uv sync --frozendeve ter sucesso após a resolução do lockfile. - Execute o linter:
uv run ruff check . - Verifique tipos (se configurado):
uv run mypy src/ou pyright nos pacotes afetados. - Testes:
uv run pytest -q- testes do módulo mínimo afetado se a suíte completa for lenta. - Migrações:
uv run alembic upgrade headno banco de dados local quando os arquivos de migração entrarem em conflito.
Fase 5 - Finalizar
- Revise o tamanho do diff:
git diff origin/main...HEAD- garanta que não haja exclusões acidentais do trabalho de outros. - Force push com segurança após rebase:
git push --force-with-leaseapenas no seu branch de feature. - Comentário no PR: Anote os arquivos em conflito e como você escolheu as versões - ajuda os revisores a focar.
- Prevenção de acompanhamento: Divida o ticket ou faça rebase com mais frequência se os mesmos arquivos entrarem em conflito repetidamente.
- Feche o ciclo com o autor: Se a mudança recebida foi mal compreendida, sincronize com o autor do commit original antes de fazer o merge.
Aplicando o Checklist em Ordem
- Fases 1-2 (1-10): Entender antes de editar evita merges do lado errado que passam nos testes, mas quebram dependências de produção.
- Fases 3-4 (11-20): Verificações de portão capturam lockfiles que analisam, mas fixam versões incompatíveis.
- Fase 5 (21-25): A comunicação reduz conflitos repetidos em arquivos "quentes" como
pyproject.toml.
FAQs
Merge ou abortar um rebase confuso?
Se os conflitos tocarem em mais de ~10 arquivos inesperadamente, aborte e tente um commit de merge em vez disso - ou faça merge do main uma vez e depois retome rebases menores.
Resolução automática da IDE é segura?
Use a mesclagem de 3 vias da IDE para fontes Python; nunca resolva automaticamente lockfiles ou migrações.
Conflito apenas em __pycache__ ou .venv?
Esses devem ser ignorados pelo git - git rm --cached e corrija o .gitignore, não comite artefatos.
Conflitos JSON de Notebook?
Prefira o nbstripout pre-commit para prevenir; veja Git para Dados/Notebooks.
Relacionados
- Branching & Merging - quando os conflitos surgem
- Comandos Essenciais do Git - comandos abort/continue
- Resolução de Dependências e Lockfiles - política de lock
- Alembic - merges de migração
Versões do 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+.