Browse cheat sheets · Git
Resolve Merge Conflicts
Resolve Git merge conflicts safely by identifying the operation in progress, understanding ours and theirs, reviewing the intended combined result, and completing or aborting the merge without losing work.
On this page
- Problem
- Quick answer
- Code / commands
- 1. Identify which Git operation is in progress
- 2. List only unresolved files
- 3. Inspect unresolved hunks
- 4. Understand conflict markers
- 5. Do not keep conflict markers
- 6. Understand ours and theirs during a normal merge
- 7. Be careful with ours and theirs during rebase
- 8. Accept the current side for one file during a merge
- 9. Accept the incoming side for one file during a merge
- 10. Inspect stage versions directly
- 11. Show the common ancestor version
- 12. Show the ours version
- 13. Show the theirs version
- 14. Resolve manually when both sides contain valid changes
- 15. Stage a resolved file
- 16. Confirm which files remain unresolved
- 17. Review the staged resolution
- 18. Complete a normal merge
- 19. Abort a normal merge
- 20. Continue a rebase after resolving
- 21. Abort a rebase
- 22. Do not use git rebase --skip merely to avoid a conflict
- 23. Continue a cherry-pick after conflicts
- 24. Abort a cherry-pick
- 25. Continue a revert after conflicts
- 26. Abort a revert
- 27. Handle stash-apply conflicts
- 28. Keep the stash until restoration is verified
- 29. Use git stash branch for an old conflict-heavy stash
- 30. Resolve delete/modify conflicts deliberately
- 31. Resolve add/add conflicts
- 32. Resolve rename conflicts carefully
- 33. Compare branch changes before retrying a difficult merge
- 34. Create a safety branch before complex conflict work
- 35. Use mergetool only when it improves clarity
- 36. Configure a merge tool explicitly
- 37. Use VS Code merge editor when appropriate
- 38. Search for conflict markers before committing
- 39. Run formatting only after semantic resolution
- 40. Run tests after resolving
- 41. Inspect the exact staged result before completing
- 42. Do not include unrelated cleanup in conflict resolution
- 43. Resolve generated files from their source when possible
- 44. Handle lock-file conflicts with the package manager when possible
- 45. Do not resolve binary conflicts by text merging
- 46. Watch for semantic conflicts Git does not report
- 47. Watch for duplicated logic after clean merges
- 48. Use git log --merge during a conflicted merge
- 49. Inspect file history for a conflict
- 50. Use blame for historical context, not fault assignment
- 51. Understand repeated rebase conflicts
- 52. Enable rerere only when you understand it
- 53. Show rerere status
- 54. Prefer smaller, shorter-lived branches
- 55. Integrate structural refactors separately when possible
- 56. Avoid using conflict resolution as an opportunity to “clean everything up”
- 57. Verify branch direction after resolution
- 58. Verify feature diff after a rebase
- 59. Use reflog if conflict resolution/history work goes wrong
- 60. Build a repeatable conflict workflow
- What the result means
- What to look for
- Conflict appears in a file both branches changed heavily
- Same conflict appears repeatedly during rebase
- ours / theirs seems backwards
- Merge completes but tests fail
- Huge number of conflicts appears unexpectedly
- Conflict is only in generated output
- Production notes
- A conflict is an integration decision
- Conflict resolution should be reviewable
- Shared branch history should not be rewritten just to avoid conflict work
- Tests are part of conflict resolution
- Tool-assisted resolution still requires judgment
- Conflict frequency is a workflow signal
- Common mistakes
- 1. Choosing ours/theirs without checking the operation
- 2. Clicking “Accept Both” automatically
- 3. Staging a file before verifying the resolution
- 4. Running reset --hard when a conflict appears
- 5. Using rebase --skip to avoid difficult conflicts
- 6. Leaving conflict markers in source
- 7. Resolving generated files manually without checking the generation workflow
- 8. Treating a clean Git merge as a correct application merge
- 9. Mixing unrelated refactoring into the resolution
- 10. Continuing before all unresolved paths are cleared
- Next step
- Related deep dives
Problem
Git stopped during a merge, rebase, cherry-pick, stash apply, or revert because two changes could not be combined automatically.
The hard part is not removing conflict markers.
The real problem is deciding what the final code should be without:
- losing valid changes from either side
- choosing
oursortheirsblindly - resolving against the wrong branch
- committing conflict markers
- hiding semantic conflicts that Git cannot detect
- completing the wrong Git operation
- discarding work while trying to recover
The goal is to identify the operation, understand both sides, resolve the intended behavior, validate the result, and then continue or abort safely.
Quick answer
Start with:
git status
List unresolved files:
git diff --name-only --diff-filter=U
Inspect conflicts:
git diff
A conflict typically looks like:
<<<<<<< HEAD
current-side content
=======
incoming-side content
>>>>>>> branch-or-commit
Resolve the file manually, remove the markers, then stage it:
git add path/to/file
Complete the operation:
Merge
→ git commit
Rebase
→ git rebase --continue
Cherry-pick
→ git cherry-pick --continue
Revert
→ git revert --continue
If the operation is wrong or unsafe:
Merge
→ git merge --abort
Rebase
→ git rebase --abort
Cherry-pick
→ git cherry-pick --abort
Revert
→ git revert --abort
Do not run git reset --hard just because a conflict appeared.
Code / commands
1. Identify which Git operation is in progress
Run:
git status
Git will tell you whether you are in:
- a merge
- a rebase
- a cherry-pick
- a revert
- a normal working-tree state
The correct continue/abort command depends on the operation.
2. List only unresolved files
git diff --name-only --diff-filter=U
This gives you the files Git still considers unmerged.
Use it when a conflict spans many files.
3. Inspect unresolved hunks
git diff
During an unresolved merge-like operation, this shows conflict regions and surrounding changes.
Review the code, not only the filenames.
4. Understand conflict markers
Typical conflict:
<<<<<<< HEAD
return old_behavior();
=======
return new_behavior();
>>>>>>> feature/new-behavior
The sections mean:
<<<<<<< HEAD
content from one side
=======
separator
>>>>>>> ...
content from the other side
Your job is to replace the entire conflict block with the correct final code.
5. Do not keep conflict markers
Bad final file:
<<<<<<< HEAD
...
=======
...
>>>>>>> feature
Git may allow staging if the markers are edited in unusual ways, but the application will contain invalid or unintended content.
Search before committing:
git grep -n '<<<<<<<\|=======\|>>>>>>>'
Review every match because some repositories may intentionally contain similar strings in tests or documentation.
6. Understand ours and theirs during a normal merge
If you are on:
main
and run:
git merge feature/report-engine
then during that merge:
ours
→ main / current branch
theirs
→ feature/report-engine / incoming branch
This is the intuitive case.
7. Be careful with ours and theirs during rebase
During rebase, the labels can feel reversed from a developer’s mental model because Git is replaying commits onto the new base.
Do not decide based on the words alone.
Use:
git status
git diff
and inspect the actual content.
Resolve according to the intended final code.
8. Accept the current side for one file during a merge
git restore --ours path/to/file
Then stage:
git add path/to/file
Use only when the entire file should come from the current side.
9. Accept the incoming side for one file during a merge
git restore --theirs path/to/file
Then:
git add path/to/file
Use only when the entire file should come from the incoming side.
Most real conflicts need a combined manual resolution instead.
10. Inspect stage versions directly
During an unmerged conflict, Git’s index can hold multiple stages.
Inspect them with:
git ls-files -u
Typical stages:
1 = common ancestor
2 = ours
3 = theirs
This is useful for advanced debugging when conflict markers are unclear.
11. Show the common ancestor version
git show :1:path/to/file
Use when you need to understand what both sides changed from.
12. Show the ours version
git show :2:path/to/file
13. Show the theirs version
git show :3:path/to/file
These stage references are especially useful for complex manual conflict analysis.
14. Resolve manually when both sides contain valid changes
Example conflict:
<<<<<<< HEAD
timeout = 30
retries = 2
=======
timeout = 60
backoff_seconds = 5
>>>>>>> feature/retry-policy
Possible correct combined result:
timeout = 60
retries = 2
backoff_seconds = 5
The right answer depends on application intent.
A conflict is a code-design decision, not a text-selection exercise.
15. Stage a resolved file
git add path/to/file
Staging tells Git:
I consider this conflict resolved.
It does not prove the resolution is correct.
16. Confirm which files remain unresolved
git status
or:
git diff --name-only --diff-filter=U
Do not continue until the unresolved list is empty.
17. Review the staged resolution
After staging:
git diff --cached
This is critical.
It shows what will be recorded when the merge/rebase/cherry-pick/revert continues.
18. Complete a normal merge
After all conflicts are staged:
git commit
Git normally prepares a merge commit message.
Review it before saving.
19. Abort a normal merge
git merge --abort
Use when:
- you merged the wrong branch
- conflict scope is unexpectedly large
- the integration approach is unsafe
- you need to return to the pre-merge state
20. Continue a rebase after resolving
git add path/to/file
git rebase --continue
Repeat for each replayed commit that conflicts.
21. Abort a rebase
git rebase --abort
This returns the branch toward its pre-rebase state.
Use when the selected base or rebase strategy was wrong.
22. Do not use git rebase --skip merely to avoid a conflict
git rebase --skip
drops the commit currently being replayed.
Use only when that commit is truly unnecessary or already represented elsewhere.
23. Continue a cherry-pick after conflicts
git add path/to/file
git cherry-pick --continue
24. Abort a cherry-pick
git cherry-pick --abort
Use if the selected commit should not be applied.
25. Continue a revert after conflicts
git add path/to/file
git revert --continue
26. Abort a revert
git revert --abort
Use when reversing the commit is not safe or the wrong commit was selected.
27. Handle stash-apply conflicts
If:
git stash apply stash@{0}
creates conflicts, use:
git status
git diff
Resolve and stage the files normally.
There is no:
git stash --continue
command.
28. Keep the stash until restoration is verified
When important work is involved:
git stash apply stash@{0}
is safer than:
git stash pop
because the stash remains available while you resolve and verify the working tree.
29. Use git stash branch for an old conflict-heavy stash
git stash branch recovered-wip stash@{0}
This creates a branch from the commit where the stash was originally created, applies the stash there, and drops it on successful application.
This can reduce conflicts when the current branch has moved far away.
30. Resolve delete/modify conflicts deliberately
Example:
one branch deleted config.py
other branch modified config.py
Ask:
Should the file still exist?
If yes, restore/resolve and stage it.
If no, remove it and stage the deletion:
git rm config.py
Do not keep or delete automatically without understanding why one side removed it.
31. Resolve add/add conflicts
If both branches created the same path with different content, Git cannot know whether they represent:
- two implementations of the same thing
- two files that should be merged
- one obsolete implementation
Open both versions and design the intended final file.
32. Resolve rename conflicts carefully
Rename-related conflicts may involve:
- rename/rename
- rename/delete
- rename/modify
Check:
git status
and inspect the involved paths.
Do not rely only on filename similarity; verify file identity and intended destination.
33. Compare branch changes before retrying a difficult merge
After aborting:
git diff origin/main...feature/report-engine
and:
git log \
--oneline \
--graph \
--decorate \
origin/main \
feature/report-engine
Use this to understand the divergence before attempting integration again.
34. Create a safety branch before complex conflict work
git branch backup-before-conflict-resolution
This is useful before:
- complicated rebase
- manual branch surgery
- risky conflict cleanup
A branch reference is cheap insurance.
35. Use mergetool only when it improves clarity
If configured:
git mergetool
A three-way merge tool can show:
base
ours
theirs
result
This can be easier than raw markers for large files.
The tool does not decide application correctness for you.
36. Configure a merge tool explicitly
Example pattern:
git config --global merge.tool <tool-name>
Exact tool configuration depends on the editor/merge tool installed.
Do not copy a tool command blindly without confirming it exists in your environment.
37. Use VS Code merge editor when appropriate
If VS Code is your configured editor, conflicted files can be opened in its merge editor.
The same rule applies:
Current / Incoming / Both
are editing aids.
They are not substitutes for understanding the desired final behavior.
38. Search for conflict markers before committing
git grep -n '<<<<<<<\|=======\|>>>>>>>'
Also inspect the staged patch:
git diff --cached
This catches accidentally retained markers.
39. Run formatting only after semantic resolution
Do not let automatic formatting obscure the actual conflict while deciding between changes.
Safer order:
resolve behavior
→ stage/review
→ format if needed
→ review final diff
→ test
40. Run tests after resolving
At minimum, run the checks relevant to the project:
unit tests
integration tests
lint
typecheck
build
Git can resolve text.
It cannot determine whether the combined application behavior is correct.
41. Inspect the exact staged result before completing
git diff --cached
For a merge commit, also inspect:
git status
Make sure only intended files are staged.
42. Do not include unrelated cleanup in conflict resolution
Avoid simultaneously:
- renaming unrelated files
- formatting entire modules
- refactoring nearby code
- changing dependencies
Keep conflict resolution focused so the integration diff is reviewable.
43. Resolve generated files from their source when possible
If a generated file conflicts:
package-lock
compiled output
generated schema
codegen artifact
first understand the project’s canonical generation process.
Often the correct approach is:
resolve source/input
→ regenerate artifact
rather than manually merging generated output.
Do not apply this blindly to files whose generated state is intentionally version-controlled with specialized rules.
44. Handle lock-file conflicts with the package manager when possible
For dependency lock files, manual conflict-marker editing can easily produce invalid state.
A common strategy is:
resolve dependency manifest
→ regenerate lock file with the correct package manager/version
→ inspect resulting diff
Follow the repository’s documented dependency workflow.
45. Do not resolve binary conflicts by text merging
For binary files, Git cannot merge content meaningfully.
Choose the intended version or regenerate the artifact.
Then stage the resolved file.
46. Watch for semantic conflicts Git does not report
Example:
Branch A:
calculate_total(items)
Branch B changes the function signature:
def calculate_total(items, currency):
...
If the edits occur in different files, Git may merge them without conflict even though the code is broken.
After integration, run tests/build/type checks.
47. Watch for duplicated logic after clean merges
Two branches may independently add:
retry handling
validation
feature flags
configuration
Git can merge both automatically even if the combined behavior is redundant or contradictory.
Review the feature-level diff, not only files with textual conflicts.
48. Use git log --merge during a conflicted merge
During an unresolved merge:
git log --merge --oneline
This can help show commits from the two sides that touch conflicted paths.
Use it for historical context.
49. Inspect file history for a conflict
git log \
--oneline \
-- path/to/file
For patches:
git log \
-p \
-- path/to/file
Useful when you need to understand why each side changed the same code.
50. Use blame for historical context, not fault assignment
git blame path/to/file
Use it to find relevant commits.
Then inspect those commits:
git show <commit>
51. Understand repeated rebase conflicts
A rebase replays commits one by one.
If several commits modify the same area, similar conflicts can occur multiple times.
Options include:
- resolve each replay faithfully
- abort and reorganize private commits
- use merge instead if replaying history adds too much risk
52. Enable rerere only when you understand it
git config rerere.enabled true
rerere can remember previous conflict resolutions and reuse them when the same conflict reappears.
Review reused resolutions.
Do not assume remembered means still correct.
53. Show rerere status
When rerere is enabled:
git rerere status
This helps identify files for which Git is recording/reusing conflict resolutions.
54. Prefer smaller, shorter-lived branches
Frequent large conflicts often indicate:
- long-lived feature branches
- broad refactors
- overlapping ownership
- infrequent integration
Reducing divergence can prevent conflicts rather than making conflict tools more sophisticated.
55. Integrate structural refactors separately when possible
If one branch:
renames 100 files
while another:
changes business logic in those files
conflicts become harder to reason about.
Separate mechanical refactors from behavior changes when practical.
56. Avoid using conflict resolution as an opportunity to “clean everything up”
The goal is to preserve intended behavior from both lines of development.
Large unrelated edits make:
- review harder
- rollback harder
- conflict reasoning harder
Keep the resolution minimal.
57. Verify branch direction after resolution
For a merge:
git log \
--oneline \
--graph \
--decorate \
-15
Confirm the expected branches were integrated.
58. Verify feature diff after a rebase
git diff origin/main...HEAD
Make sure conflict resolution did not accidentally remove required feature changes.
59. Use reflog if conflict resolution/history work goes wrong
git reflog
Find the earlier branch tip.
Then:
git switch -c conflict-recovery <old-commit>
Do this before more destructive history changes.
60. Build a repeatable conflict workflow
Use:
1. git status
2. identify operation
3. list unresolved files
4. inspect each conflict
5. understand base/ours/theirs
6. resolve intended behavior
7. git add resolved files
8. git diff --cached
9. search for conflict markers
10. run tests/build
11. continue or commit
12. inspect final history
This is safer than clicking “Accept Both” repeatedly and hoping the result works.
What the result means
| State/command | Meaning |
|---|---|
git status |
Shows operation and unresolved paths |
git diff --name-only --diff-filter=U |
Lists unmerged files |
git diff |
Shows unresolved conflict content |
git restore --ours |
Takes current-side file version in applicable merge state |
git restore --theirs |
Takes incoming-side file version in applicable merge state |
git add |
Marks resolved content in the index |
git merge --abort |
Aborts current merge |
git rebase --continue |
Continues replay after resolution |
git rebase --abort |
Restores pre-rebase state |
git cherry-pick --continue |
Continues cherry-pick |
git revert --continue |
Continues revert |
git ls-files -u |
Shows unmerged index stages |
git show :1:file |
Common ancestor |
git show :2:file |
Ours |
git show :3:file |
Theirs |
The most important distinction is:
textual conflict resolution
!=
application correctness
What to look for
Conflict appears in a file both branches changed heavily
Inspect the history and the common ancestor before resolving.
The right answer may require combining intent, not choosing one side.
Same conflict appears repeatedly during rebase
Several commits are being replayed over the same changed area.
Consider whether merge or private-history cleanup would be safer.
ours / theirs seems backwards
You may be in a rebase or another replay operation.
Inspect actual content rather than relying on labels.
Merge completes but tests fail
Look for semantic conflicts Git could not detect.
Review changes in nearby files and interfaces.
Huge number of conflicts appears unexpectedly
Stop and check:
- current branch
- incoming branch
- merge base
- whether the branch was created from the expected base
Aborting may be safer than resolving the wrong integration.
Conflict is only in generated output
Resolve the canonical source and regenerate where the repository’s workflow supports it.
Production notes
A conflict is an integration decision
Git reports overlapping edits.
It cannot determine which business behavior is correct.
Conflict resolution should be reviewable
Keep resolutions focused and avoid unrelated refactors.
This makes pull-request review and rollback safer.
Shared branch history should not be rewritten just to avoid conflict work
Do not replace a difficult shared merge with a destructive force-push strategy.
Preserve collaboration safety.
Tests are part of conflict resolution
Especially after conflicts in:
- API contracts
- database code
- configuration
- build files
- dependency manifests
- serialization models
Tool-assisted resolution still requires judgment
IDE buttons such as:
Accept Current
Accept Incoming
Accept Both
are editing operations, not architectural decisions.
Conflict frequency is a workflow signal
Repeated large conflicts may indicate:
- branches live too long
- teams modify the same modules simultaneously
- refactors are too broad
- integration happens too late
Fixing workflow can be more valuable than mastering conflict commands.
Common mistakes
1. Choosing ours/theirs without checking the operation
During rebase, the mental model is especially easy to get wrong.
2. Clicking “Accept Both” automatically
Both blocks may duplicate logic or produce invalid behavior.
3. Staging a file before verifying the resolution
git add means Git considers it resolved.
Review first.
4. Running reset --hard when a conflict appears
Most conflicts can be safely resolved or aborted without destroying local work.
5. Using rebase --skip to avoid difficult conflicts
This drops the replayed commit.
6. Leaving conflict markers in source
Search before committing.
7. Resolving generated files manually without checking the generation workflow
Regeneration may be safer and reproducible.
8. Treating a clean Git merge as a correct application merge
Semantic conflicts may remain.
9. Mixing unrelated refactoring into the resolution
This makes review and rollback harder.
10. Continuing before all unresolved paths are cleared
Use git status and the unmerged-file query to verify.
Was this helpful?
What could be better?
Thanks — that helps me improve Javi Builds.
Stay in the loop
Get the Javi Builds updates you actually care about.
Check your inbox
I sent you a confirmation link. Your subscription will be active after you confirm it.