Merge Conflict Resolution Checklist
A calm, repeatable process for resolving Git merge and rebase conflicts in Rust repos - especially Cargo.toml, Cargo.lock, and sqlx migrations.
How to Use This Checklist
- Walk items in order during an active conflict - do not skip straight to editing markers.
- Resolve one file fully before moving to the next when conflicts are large.
- If stuck more than 30 minutes on one file, pair - lockfiles and migrations benefit from a second reviewer.
- Record conflict cause in the PR description to prevent repeat collisions.
Phase 1 - Stabilize
- Confirm operation type:
git statusshows merge, rebase, or cherry-pick. - List conflicted files:
git diff --name-only --diff-filter=U. - Abort if wrong branch:
git merge --abortorgit rebase --abort. - Stash unrelated WIP:
git stash push -m "pre-conflict". - Fetch latest remote:
git fetch origin.
Phase 2 - Understand
- Read both sides:
<<<<<<<,=======,>>>>>>>mark yours vs incoming. - Check commit messages:
git log --oneline --left-right HEAD...MERGE_HEAD. - Identify semantic intent: cosmetic formatting vs dependency version vs migration revision.
- Lockfile rule: pick winning
Cargo.tomlside, remove markers, runcargo generate-lockfileorcargo update -p crate. - Migration rule: never duplicate
sqlxrevision ids; may need merge migration after resolution.
Phase 3 - Resolve
- Resolve one file at a time: valid TOML and Rust syntax, no leftover markers.
- Prefer upstream dependency policy: align with
mainunless ticket requires bump. - Run rustfmt on touched Rust:
cargo fmt -- file.rs. - Stage resolved file:
git add <file>;git diff --checkcatches marker leftovers. - Continue operation:
git rebase --continueor complete merge commit.
Phase 4 - Verify
- Locked build:
cargo build --locked. - Fmt:
cargo fmt --all -- --check. - Clippy:
cargo clippy --all-targets -- -D warnings. - Tests:
cargo test --all-features. - Migrations:
sqlx migrate runwhen migration files conflicted.
Phase 5 - Finish
- Review diff size:
git diff origin/main...HEAD. - Force push safely after rebase:
git push --force-with-leaseon your feature branch only. - PR comment: note conflict files and resolution choices.
- Prevention: rebase more often if same files conflict repeatedly.
- Sync with author: clarify misunderstood incoming commits before merge.
FAQs
Always prefer incoming Cargo.lock?
No. Resolve Cargo.toml first, then regenerate lock from merged manifest.
Conflict in target/ directory?
Should not be tracked; add to .gitignore and remove from index.
Related
Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.