Browse cheat sheets · Git

Technology: GitCategory: Version ControlDifficulty: IntermediateUpdated

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
  1. Problem
  2. Quick answer
  3. Code / commands
  4. 1. Identify which Git operation is in progress
  5. 2. List only unresolved files
  6. 3. Inspect unresolved hunks
  7. 4. Understand conflict markers
  8. 5. Do not keep conflict markers
  9. 6. Understand ours and theirs during a normal merge
  10. 7. Be careful with ours and theirs during rebase
  11. 8. Accept the current side for one file during a merge
  12. 9. Accept the incoming side for one file during a merge
  13. 10. Inspect stage versions directly
  14. 11. Show the common ancestor version
  15. 12. Show the ours version
  16. 13. Show the theirs version
  17. 14. Resolve manually when both sides contain valid changes
  18. 15. Stage a resolved file
  19. 16. Confirm which files remain unresolved
  20. 17. Review the staged resolution
  21. 18. Complete a normal merge
  22. 19. Abort a normal merge
  23. 20. Continue a rebase after resolving
  24. 21. Abort a rebase
  25. 22. Do not use git rebase --skip merely to avoid a conflict
  26. 23. Continue a cherry-pick after conflicts
  27. 24. Abort a cherry-pick
  28. 25. Continue a revert after conflicts
  29. 26. Abort a revert
  30. 27. Handle stash-apply conflicts
  31. 28. Keep the stash until restoration is verified
  32. 29. Use git stash branch for an old conflict-heavy stash
  33. 30. Resolve delete/modify conflicts deliberately
  34. 31. Resolve add/add conflicts
  35. 32. Resolve rename conflicts carefully
  36. 33. Compare branch changes before retrying a difficult merge
  37. 34. Create a safety branch before complex conflict work
  38. 35. Use mergetool only when it improves clarity
  39. 36. Configure a merge tool explicitly
  40. 37. Use VS Code merge editor when appropriate
  41. 38. Search for conflict markers before committing
  42. 39. Run formatting only after semantic resolution
  43. 40. Run tests after resolving
  44. 41. Inspect the exact staged result before completing
  45. 42. Do not include unrelated cleanup in conflict resolution
  46. 43. Resolve generated files from their source when possible
  47. 44. Handle lock-file conflicts with the package manager when possible
  48. 45. Do not resolve binary conflicts by text merging
  49. 46. Watch for semantic conflicts Git does not report
  50. 47. Watch for duplicated logic after clean merges
  51. 48. Use git log --merge during a conflicted merge
  52. 49. Inspect file history for a conflict
  53. 50. Use blame for historical context, not fault assignment
  54. 51. Understand repeated rebase conflicts
  55. 52. Enable rerere only when you understand it
  56. 53. Show rerere status
  57. 54. Prefer smaller, shorter-lived branches
  58. 55. Integrate structural refactors separately when possible
  59. 56. Avoid using conflict resolution as an opportunity to “clean everything up”
  60. 57. Verify branch direction after resolution
  61. 58. Verify feature diff after a rebase
  62. 59. Use reflog if conflict resolution/history work goes wrong
  63. 60. Build a repeatable conflict workflow
  64. What the result means
  65. What to look for
  66. Conflict appears in a file both branches changed heavily
  67. Same conflict appears repeatedly during rebase
  68. ours / theirs seems backwards
  69. Merge completes but tests fail
  70. Huge number of conflicts appears unexpectedly
  71. Conflict is only in generated output
  72. Production notes
  73. A conflict is an integration decision
  74. Conflict resolution should be reviewable
  75. Shared branch history should not be rewritten just to avoid conflict work
  76. Tests are part of conflict resolution
  77. Tool-assisted resolution still requires judgment
  78. Conflict frequency is a workflow signal
  79. Common mistakes
  80. 1. Choosing ours/theirs without checking the operation
  81. 2. Clicking “Accept Both” automatically
  82. 3. Staging a file before verifying the resolution
  83. 4. Running reset --hard when a conflict appears
  84. 5. Using rebase --skip to avoid difficult conflicts
  85. 6. Leaving conflict markers in source
  86. 7. Resolving generated files manually without checking the generation workflow
  87. 8. Treating a clean Git merge as a correct application merge
  88. 9. Mixing unrelated refactoring into the resolution
  89. 10. Continuing before all unresolved paths are cleared
  90. Next step
  91. 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 ours or theirs blindly
  • 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.

Next step

Use the operation and symptom to choose the next action.

  • Normal merge conflict → resolve files, stage, review, test, then commit.
  • Rebase conflict → resolve, stage, git rebase --continue.
  • Cherry-pick conflict → resolve, stage, git cherry-pick --continue.
  • Revert conflict → resolve the intended inverse change, then git revert --continue.
  • Wrong branch or wrong integration direction → abort the operation.
  • Ours/theirs is confusing → inspect index stages and actual file content.
  • Generated or lock file conflicts → resolve canonical inputs and regenerate when appropriate.
  • Conflicts are unexpectedly massive → inspect branch graph and merge base before proceeding.
  • Git reports no conflicts but tests fail → investigate semantic conflicts.
  • Think conflict work damaged history → inspect git reflog and create a recovery branch before further changes.

← All cheat sheets