Merge conflict resolution flow
Detecting, resolving, and testing concurrent branch merges.
Every development team merges branches, and almost every team discovers that automated merges fail when two developers touched the same lines. This template maps the full flow: detecting the conflict, understanding both versions, resolving it by choosing ours, theirs, or a manual combination, then testing to prove the merge doesn't break the app.
The decision diamonds show where the conflict resolution happens and where tests catch mistakes. This template makes visible the overlooked step: even after a human resolves the conflict, the merge must pass CI again to be safe.
When to use this template
- Onboarding new developers — show them the happy path (no conflicts, auto-merge) and the conflict recovery path so they know what to do when
git mergepauses. - Incident postmortems — when a bad merge gets through CI, trace which step failed. Did someone skip running tests locally? Did CI miss a regression?
- Git workflow documentation — document your team's specific merge strategy: do you squash-merge? rebase? require a merge commit? This template is the skeleton.
How to adapt it
Start with your team's actual merge settings. Common extensions:
- Add a squash-merge option if your team prefers a linear history, replacing the merge commit with a single commit.
- Insert a code review gate between conflict resolution and local testing — some teams require approval before touching a conflict.
- Add a rebase-before-merge check to keep the main branch linear and simplify conflict resolution in future merges.
Visual edits regenerate clean code, so you can sketch your team's conflict-handling policy and merge strategy directly in the diagram without writing Mermaid syntax.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[Team pushes concurrent branches] --> B[Merge into main attempted]
B --> C{Conflicts detected?}
C -->|No| D[Auto-merge succeeds]
C -->|Yes| E[Block merge, notify author]
E --> F[Dev examines conflict markers]
F --> G{Accept ours, theirs, or combine?}
G -->|Accept ours| H[Resolve with local version]
G -->|Accept theirs| I[Resolve with incoming version]
G -->|Combine| J[Manually edit & merge both]
H --> K{All conflicts resolved?}
I --> K
J --> K
K -->|No| F
K -->|Yes| L[Run tests locally]
L --> M{Tests pass?}
M -->|No| N[Fix broken tests]
N --> L
M -->|Yes| O[Push resolved merge commit]
O --> P[CI validates once more]
P --> Q{CI passes?}
Q -->|No| R[Rollback & investigate]
Q -->|Yes| S[Merge completes]
Frequently asked questions
- What is a merge conflict in Git?
- A merge conflict happens when two branches edited the same lines of code and Git cannot automatically decide which version to keep. Git pauses the merge and asks a human to resolve it. The conflict markers (<<<<, ====, >>>>) show which version came from which branch.
- Why do conflicts happen and how do I prevent them?
- Conflicts are inevitable when multiple developers change the same file. Prevent them by communicating changes early, keeping branches short-lived (merge within 1-2 days), and using feature branches that touch different files. When they do happen, resolve them quickly — the longer a conflict sits, the more context you lose.
- How do I resolve a merge conflict?
- Open the conflicting file and look for the conflict markers. Decide which version to keep — ours (your branch), theirs (the branch you are merging in), or a combination. Edit to remove the markers and keep only the code you want, save, stage with `git add`, and then `git merge --continue` or create the merge commit.
- What if the merge conflicts are too complex to resolve manually?
- For complex merges, some teams use merge drivers (e.g., union-merge) or three-way merge tools like `mergetool`. However, the diagram shows the most common path: examine both versions, decide which is right, combine if needed, run tests to verify, and push. Visual edits regenerate the Mermaid code so you can sketch your team's specific conflict-handling policy without syntax hassle.