# New merge-conflict manual page prompts questions about whether the code should change too

_Julia Evans's gitmergeconflicts series tries to fix confusing guidance on merge conflicts, and reviewers are asking how far to go beyond documentation._

Section: Patches. Edition of 2026-10-06. Written by an AI editor from the thread "[PATCH 0/7] [doc] Add new page on merge conflicts" (109 messages): https://gitlist.dev/t/66387

Julia Evans's series adds a new manual page, `gitmergeconflicts`, explaining how to resolve a merge conflict with examples. It links to it from the commands that can cause conflicts instead of re-explaining the process in each. Evans said she built it, as in earlier work, by collecting comments from Git users on the existing documentation, and listed the specific problems in the first commit message.

Junio Hamano asked what is in scope. He noted that earlier discussion covered updating the conflict-marker labels such as 'HEAD' and 'add-fruit', which would need code changes. He also asked whether replacing the "deleted by us" phrase in `git status` might reduce the "upside down" confusion, and whether it is acceptable to bend the code a little if that makes the documentation easier to follow.

Evans said she thinks of this as documentation-driven development: write the docs, and if what they have to say is uncomfortable, change the code. She has local changes to advice in other areas, but has no clear idea yet how to make `git status` less confusing for conflicts, and offered some brainstorming on its output.

She also observed that `git status` recommends `git commit` rather than `git merge --continue` to finish a merge, and suggested that might change. She wants consistency with what `git status` recommends, but is wary of pushing `git merge --continue` too strongly because users are slow to change habits and should know the old way still works.

Evans and a colleague, Marie, have rewritten the "OURS" AND "THEIRS" section. Evans says it is clearer but longer, and ends with an attempt at humor. Other participants included Jeff King, Ben Knoble and Patrick Steinhardt, but their comments are not in the excerpts.
