Merge Conflict Resolution Checklist

A calm, repeatable process for resolving Git merge and rebase conflicts in Python repos - especially pyproject.toml, uv.lock, and Alembic migrations.

How to Use This Checklist

• Walk items in order during an active conflict - do not skip straight to editing markers.
• One file fully resolved and tested before moving to the next when conflicts are large.
• If more than 30 minutes stuck on one file, pause and pair - migrations and lockfiles benefit from a second reviewer.
• Record what caused the conflict in the PR description to prevent repeat collisions.

Phase 1 - Stabilize

1. Confirm operation type: Know whether you are in merge, rebase, or cherry-pick - git status shows current state.
2. List conflicted files: git diff --name-only --diff-filter=U - expect pyproject.toml, uv.lock, alembic/versions/*.py.
3. Abort if wrong branch: git merge --abort or git rebase --abort when you started on incorrect base.
4. Stash unrelated WIP: git stash push -m "pre-conflict" if uncommitted edits mix with conflict resolution.
5. Fetch latest remote: git fetch origin so you resolve against current main, not stale local copy.

Phase 2 - Understand

6. Read both sides: Open conflicted file - <<<<<<<, =======, >>>>>>> mark yours vs incoming.
7. Check commit messages: git log --oneline --left-right HEAD...MERGE_HEAD (merge) or incoming commits on rebase.
8. Identify semantic intent: Is conflict cosmetic (import order) or behavioral (dependency version, migration revision)?
9. Lockfile rule: For uv.lock / poetry.lock - pick winning pyproject.toml side, delete conflict markers, run uv lock.
10. Migration rule: For Alembic - never duplicate revision ids; may need alembic merge heads after resolution.

Phase 3 - Resolve

11. Resolve one file at a time: Remove all conflict markers; leave valid Python/TOML syntax.
12. Prefer upstream dependency policy: When unsure on library version, align with main unless ticket requires bump.
13. Run formatter on touched Python: uv run ruff format on resolved .py files.
14. Stage resolved file: git add <file> only when markers fully removed - git diff --check catches leftovers.
15. Continue operation: git rebase --continue or complete merge commit after all files staged.

Phase 4 - Verify

16. Sync environment: uv sync --frozen must succeed after lock resolution.
17. Lint: uv run ruff check .
18. Typecheck (if configured): uv run mypy src/ or pyright on affected packages.
19. Tests: uv run pytest -q - minimum affected module tests if full suite is slow.
20. Migrations: uv run alembic upgrade head on local DB when migration files conflicted.

Phase 5 - Finish

21. Review diff size: git diff origin/main...HEAD - ensure no accidental deletions of others' work.
22. Force push safely after rebase: git push --force-with-lease only on your feature branch.
23. PR comment: Note conflict files and how you chose versions - helps reviewers focus.
24. Follow up prevention: Split ticket or rebase more often if same files conflict repeatedly.
25. Close loop with author: If incoming change was misunderstood, sync with original commit author before merging.

Applying the Checklist in Order

• Phase 1-2 (1-10): Understanding before editing prevents wrong-side merges that pass tests but break prod deps.
• Phase 3-4 (11-20): Verification gates catch lockfiles that parse but pin incompatible versions.
• Phase 5 (21-25): Communication reduces repeat conflicts on hot files like pyproject.toml.

FAQs

Related

• Branching & Merging - when conflicts arise
• Essential Git Commands - abort/continue commands
• Dependency Resolution and Lockfiles - lock policy
• Alembic - migration merges

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 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+, and uv 0.6+.