Git and GitHub / Editorial solution guide

Resolve merge conflicts without losing intended behavior

Read operation state and all relevant versions, then stage and verify a deliberate combined result.

About 3 min readContent reviewed

Read-only knowledge base · No public comments

Recognize the symptoms

Git reports unmerged paths, a file contains conflict markers, or a pull request cannot merge automatically. Some conflicts involve edits and deletions or renames rather than simple competing lines. Removing visible markers can make status look better while silently dropping required behavior, so the symptom is an unresolved integration decision rather than just messy text.

Understand the likely causes

  • The two sides changed assumptions that Git’s automatic strategy cannot combine confidently. Unrelated uncommitted work can complicate the operation, and a rebase can make ours/theirs labels differ from a learner’s expectation. The correct result may contain both changes or a new implementation, not necessarily one complete side.

Identify the operation and protect current work

Read git status before issuing continuation commands. Determine whether this is a merge, rebase, cherry-pick, or stash application and preserve valuable files before further mutation. Do not begin another integration on top of an unresolved one. If the operation started from a clean lab tree, an operation-specific abort is easier to reason about; pre-existing edits require extra care. This guide’s practical work is confined to temporary repositories and never edits a conflict in the actual workspace.

Read base and side content before selecting

For a typical two-branch content merge, stage 1 is the common base, stage 2 the current side, and stage 3 the other side. Some conflict types lack a stage, so inspect the unmerged listing first. Read surrounding code and relevant tests, not only the marked lines. During rebase, use the actual content and operation context rather than assuming ours always means the original feature branch. Generated files may need regeneration from their source after the source conflict is resolved.

bash Inspect an ordinary synthetic content conflict 
git ls-files -u -- notes.txt
git show :1:notes.txt
git show :2:notes.txt
git show :3:notes.txt

Requires the stated temporary merge conflict in notes.txt. These commands read indexed versions and do not resolve anything. A missing stage for another conflict type must be interpreted from the actual unmerged listing.

Implement the combined behavior and mark resolution

Choose the intended semantics, edit the file, remove markers, and inspect the whole result for duplicate or omitted logic. Stage only the resolved paths deliberately. Run whitespace checks, inspect any remaining unmerged paths, and execute focused behavior tests. For a merge, commit the verified resolution; for rebase or cherry-pick, use the matching --continue flow. If the correct result is unclear, preserve evidence and seek domain context rather than picking a side to make the tool quiet.

bash Verify the staged lab resolution before continuing 
git add -- notes.txt
git diff --cached --check
git diff --name-only --diff-filter=U
git diff --cached -- notes.txt

An empty unmerged-path list means the index no longer records unresolved paths, not that the behavior is correct. The staged patch and tests provide the additional evidence. No automatic continuation or publication is performed by this inspection fragment.

Verify the fix

After completing the correct operation, inspect the final graph, clean status, and combined content. Test every requirement introduced by the two original changes plus their interaction. Confirm no conflict markers or accidental duplicate branches of logic remain. If aborting instead, verify the expected pre-operation state and preserved local work; do not assume abort guarantees recovery of arbitrary pre-existing edits. Record any non-obvious semantic choice in the resulting review or commit message.

Keep it from recurring

  • Integrate from an understandable protected state, keep changes coherent, and communicate shared API or schema changes early. Add regression tests for assumptions that conflicted. Avoid broad side-selection shortcuts and blanket staging when unrelated files are present. Rehearse complicated integrations on a temporary named branch before changing shared history.

Official references