# [PATCH 0/7] [doc] Add new page on merge conflicts 44 messages from 2026-09-24 to 2026-10-05. Participants: Julia Evans via GitGitGadget, Junio C Hamano, Jeff King, D. Ben Knoble, Julia Evans, Ben Knoble, Patrick Steinhardt. Thread: https://gitlist.dev/t/66387 ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: ``` Handling merge conflicts is difficult, and currently Git's guidance on merge conflicts isn't giving users the information they need to navigate the process. As usual, the process I used to write this was to collect comments from Git users on the existing documentation, and then address those issues. I listed the specific issues we're aiming to solve in the first commit message in the series. This patch series introduces a new manual page, gitmergeconflicts, which explains the process of explaining a merge conflict with examples. It also links to that new page from the commands which can cause merge conflicts, instead of trying to reexplain the process every time. This is a pretty big change, so here's a list of things I'm still considering in the hopes that it'll help with the discussion: * I wrote that git commit does the same thing as git merge --continue during a git merge , but I'm not sure if that's always true. * Not 100% sure that the explanation of diff3 vs zdiff3 is correct * Right now we're listing git merge, git revert, git rebase, git cherry-pick, and git pull as commands that can cause merge conflicts. I believe that git apply and git am can also result in conflicts when applying a patch, though it's a bit complicated because applying a patch is a different operation than doing a 3-way merge and the tools available for dealing with it are a different. My thought right now is to avoid the issue of applying patches for now (because it's a whole can of worms) and instead just try to not imply that this is necessarily an exhaustive list. Also if/when the git rebase --squash changes land, then we'd need to add git history to this list. * Instead of creating a new page, I considered using an include to have a "handling merge conflicts" section in git rebase, git merge, etc. Merge conflict resolution is complex and it's very useful to be able to include examples: this version ended up at ~300 lines and I think that's too big of an include, especially for short man pages like cherry-pick * Explaining what "ours" and "theirs" mean was one of the hardest parts of writing this. From polling Git users in one of my many informal Mastodon polls about Git, my understanding is that Git users are actually relatively unlikely to actually reason about what "ours" and "theirs" mean when dealing with a merge conflict, and that most people prefer to get more context instead, for example by using a mergetool or by using diff3 or zdiff3. I heard a lot of "I can never remember which is which I so I don't even try". So I put the information about what "ours" and "theirs" mean relatively far down the page (with some cross-references), so that it's easily available but not the main focus. * I removed a couple of mentions of the various _HEAD references. It's hard for me to know exactly where they belong because I personally have never used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I don't know how they're meant to be used. From some quick unscientific polling (at https://social.jvns.ca/@b0rk/117320011885941855), it seems like most Git users have never used them either (and folks who do use a *_HEAD reference mainly seem to use FETCH_HEAD which isn't relevant here), so from that perspective it seems important to avoid emphasizing them too much. The git revert man page doesn't mention REVERT_HEAD and git rebase only mentions REBASE_HEAD in passing. Of course they're all explained in gitrevisions(7) which might be the best place for them. * I'm still not sure what the SYNOPSIS section is for in a "guide" man page which is not about a specific Git command (what is the user intended to use it for?). I tried to leave it out but the CI said it was required. Thanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih, and about 12 others who gave feedback on both the original git merge man page, as well as the proposed improvements. Julia Evans (7): [doc] Add new gitmergeconflicts man page [doc] git-merge: link to new merge conflicts guide [doc] git-rebase: link to new merge conflicts guide [doc] git-revert: link to new merge conflicts guide [doc] git-cherry-pick: link to new merge conflicts guide [doc] git-pull: link to new merge conflicts guide [doc] ignore conflict markers in gitmergeconflicts.adoc .gitattributes | 1 + Documentation/Makefile | 1 + Documentation/git-cherry-pick.adoc | 23 +-- Documentation/git-merge.adoc | 125 +----------- Documentation/git-pull.adoc | 3 +- Documentation/git-rebase.adoc | 13 +- Documentation/git-revert.adoc | 5 + Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++ Documentation/meson.build | 1 + 9 files changed, 320 insertions(+), 146 deletions(-) create mode 100644 Documentation/gitmergeconflicts.adoc base-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/2237 -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` From: Julia Evans Introduce a new page, `gitmergeconflicts`, that explains the process of handling a merge conflict in a way that addresses the following issues, which came from feedback from Git users on the current explanation of merge conflicts in the `git merge` man page: - The process for resolving a merge conflict is only explained in the `git merge` man page, even though there are several other commands which can result in conflicts - Sometimes we use "ours" and "theirs" to refer to the two sides of the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should be consistent. Also the terms "ours" and "theirs" are not explained. Similarly, it says "The part before the `=======` is typically your side...", but doesn't explain what "typically" means. - It introduces the merge format using an analogy to RCS, which very few Git users have ever used - In "The only clean-ups you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean up working tree changes made by 2. and 3.", it's not clear to users what "2" and "3" are supposed to mean - It uses a cultural reference ("Conflict resolution is hard; let's go shopping.") which is confusing or unfamiliar to some people. I think it would be clearer for users to use a code example instead. - It doesn't explain the difference between diff3 and zdiff3 - It sometimes uses the term "area" and sometimes uses the term "hunk" Also document the unified `--abort`, `--continue` workflow in one place, since it's a really nice example of a place Git has a consistent interface between similar commands. Co-Authored-By: Marie Claire LeBlanc Flanagan Signed-off-by: Julia Evans --- Documentation/Makefile | 1 + Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++ Documentation/meson.build | 1 + 3 files changed, 296 insertions(+) create mode 100644 Documentation/gitmergeconflicts.adoc diff --git a/Documentation/Makefile b/Documentation/Makefile index f8dea4b395..bc49641dda 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc MAN7_TXT += giteveryday.adoc MAN7_TXT += gitfaq.adoc MAN7_TXT += gitglossary.adoc +MAN7_TXT += gitmergeconflicts.adoc MAN7_TXT += gitpacking.adoc MAN7_TXT += gitnamespaces.adoc MAN7_TXT += gitremote-helpers.adoc diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc new file mode 100644 index 0000000000..612b683e40 --- /dev/null +++ b/Documentation/gitmergeconflicts.adoc @@ -0,0 +1,294 @@ +gitmergeconflicts(7) +==================== + +NAME +---- +gitmergeconflicts - Guide to handling merge conflicts + + +SYNOPSIS +-------- +Guide to handling merge conflicts + + +DESCRIPTION +----------- + +Merge conflicts can happen during a `git merge`, `git rebase`, `git +cherry-pick`, `git pull`, or `git revert`. All of those commands use +the same merge algorithm, and the process for resolving a merge conflict +is always very similar. + +The most common ways to handle a merge conflict are: + +* Resolve the conflict. (see <> + below for details) +* Or stop the operation and return your branch to its original state + with the appropriate `--abort` command, for example `git merge --abort` + or `git rebase --abort`. See <> below + for how to find the command to run. + + +[[markers]] +MERGE CONFLICT MARKERS +---------------------- + +Merge conflicts happen when both of the sides being merged edit the same +area of a file. When this happens, Git will update the conflicted file +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. +For example, here's a merge conflict where both sides edited a list of +fruits in different ways: + +---- +FRUITS = [ + "apple", +<<<<<<< HEAD + "cherry", +======= + "banana", +>>>>>>> add-fruit + "mango", + "orange", +] +---- + +The code from one side of the merge conflict is between `<<<<<<<` and +`=======`, and the code for the other side is between `=======` and +`>>>>>>>`. See <> below for a full explanation +of which side is which. + + +[[resolve]] +HOW TO RESOLVE A MERGE CONFLICT +------------------------------- + +The process for resolving a merge conflict is: + +1. Run `git status` to get a list of files with merge conflicts +2. For each one, find the conflict markers + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to + fix the conflict +3. Run `git add FILENAME` for each file to mark the conflict as resolved +4. Run the appropriate `--continue` command to continue the operation + that was interrupted by the conflict, for example `git merge --continue` + or `git rebase --continue`. See <> + below for how to find the command to run. ++ +Note: During a `git merge`, `git commit` and `git merge --continue` do +the the same thing. + + +[[example]] +EXAMPLE OF RESOLVING A MERGE CONFLICT +------------------------------------- + +If you see this in your code during a merge conflict: + +---- +FRUITS = [ + "apple", +<<<<<<< HEAD + "cherry", + "mango", +======= + "banana", + "mango", +>>>>>>> add-fruit + "orange", +] +---- + +Then you might edit that part of the code like this, +which includes the fruits from both sides of the conflict: + +---- +FRUITS = [ + "apple", + "banana", + "cherry", + "mango", + "orange", +] +---- + + +[[tools]] +TOOLS FOR HANDLING MERGE CONFLICTS +---------------------------------- + +Here are some ways to get extra context while handling a merge conflict: + +* There are many graphical "merge tools" for Git, which will normally + show you the different versions of the code side by side. + If you have a mergetool configured, `git mergetool` will launch it. + See also `merge.tool` in linkgit:git-config[1] for a list of + the mergetools Git supports. + +* You can set the configuration option `merge.conflictstyle=diff3`. + See <> below for more. + +* Look at the original files. `git show :1:filename` shows the + common ancestor, `git show :2:filename` shows the "ours" + version, and `git show :3:filename` shows the "theirs" + version. + +Here are some ways to track your progress while handling a conflict: + +* Use `git status` to get a list of files with conflicts + +* Use `git diff --check` to make sure you haven't left any merge + conflict markers in a file by accident. It will print "leftover + conflict marker" if it finds any. + +* Use `git diff AUTO_MERGE` to show what changes you've made so far to + resolve the conflicts. + +[[git_status]] +EXAMPLE: GIT STATUS OUTPUT +-------------------------- + +When you're in a merge conflict, you can find out what commands to run +to handle the conflict by running `git status`. + +For example, this `git status` output tells you that: + +* `git rebase --abort` will safely bring your branch back to its + original state +* you should run `git rebase --continue` when you're done resolving all + the conflicts +* there's one file left with conflicts in it: `fruits.py` + +---- +$ git status +You are currently rebasing branch 'main' on '58a9fcc'. + (fix conflicts and then run "git rebase --continue") + (use "git rebase --skip" to skip this patch) + (use "git rebase --abort" to check out the original branch) + +Unmerged paths: + (use "git restore --staged ..." to unstage) + (use "git add ..." to mark resolution) + both modified: fruits.py +---- + + +[[diff3]] +DIFF3 AND ZDIFF3 +---------------- + +By default, Git doesn't include the original code when formatting +a merge conflict. To include the original code, you can set the +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`. +This extra context can make it much easier to understand what's +happening in a merge conflict. + +Here's an example of what a merge conflict would look like when using +`diff3`. It shows, in order, the "ours" side of the conflict, the +original code (`"mangoooo"`), and the "theirs" side of the +conflict. With this view, you can see that both sides fixed the spelling +mistake in "mango", and each added one fruit to the list. + +---- +FRUITS = [ + "apple", +<<<<<<< HEAD + "cherry", + "mango", +||||||| 1c22e48 + "mangoooo", +======= + "banana", + "mango", +>>>>>>> add-fruit + "orange", +] +---- + +Here's the same example using `zdiff3`. `zdiff3` takes lines that are +shared between both sides (the `"mango"` line) and moves them outside +the conflicted area. This makes the conflicted area shorter, but the +downside is that it's impossible to tell if `"mango"` was part of the +original list of fruits or not. + +---- +FRUITS = [ + "apple", +<<<<<<< HEAD + "cherry", +||||||| 1c22e48 + "mangoooo", +======= + "banana", +>>>>>>> add-fruit + "mango", + "orange", +] +---- + + +[[ours]] +"OURS" AND "THEIRS" +------------------- + +Git refers to the first part of a merge conflict (between `<<<<<<<` +and `=======`) as "ours" and the second part (between `=======` and +`>>>>>>>`) as "theirs". + +Normally, "ours" is the commit that was checked out before you started +the merge, and "theirs" is the other commit. + +But when the merge conflict was caused by a `git rebase`, it's the +opposite: "theirs" is the commit that was checked out before you started +the merge. This is because under the hood, `git rebase main` checks out +the `main` commit first before doing the merge operation. + +These terms in Git all mean the same thing when dealing with a merge +conflict: + +* "common ancestor", "base", and "stage 1" +* "ours", "us", "stage 2", and `HEAD` +* "theirs", "them", and "stage 3" + +[[automerge]] +Example of using `AUTO_MERGE` +----------------------------- + +`git diff AUTO_MERGE` will show what changes you've made so far to +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a +merge. It contains the result of running the merge algorithm. + +For example, if we resolved the conflict the way we did in the +<>, the diff would look like this: + +---- + FRUITS = [ + "apple", +-<<<<<<< HEAD +- "cherry", +-======= + "banana", +->>>>>>> add-fruit ++ "cherry", + "mango", + "orange", +] +---- + +[NOTE] +`AUTO_MERGE` is only set if you're using the default Git merge algorithm. + + +SEE ALSO +-------- + +linkgit:git-revert[1] +linkgit:git-merge[1] +linkgit:git-rebase[1] +linkgit:git-cherry-pick[1] +linkgit:git-pull[1] +linkgit:git-diff[1] + +GIT +--- + +Part of the linkgit:git[1] suite diff --git a/Documentation/meson.build b/Documentation/meson.build index f4854f802d..51647957e0 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -202,6 +202,7 @@ manpages = { 'gitfaq.adoc' : 7, 'gitglossary.adoc' : 7, 'gitpacking.adoc' : 7, + 'gitmergeconflicts.adoc' : 7, 'gitnamespaces.adoc' : 7, 'gitremote-helpers.adoc' : 7, 'gitrevisions.adoc' : 7, -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: ``` From: Julia Evans All of the info about merge conflicts has been moved to the new guide Signed-off-by: Julia Evans --- Documentation/git-merge.adoc | 125 +---------------------------------- 1 file changed, 3 insertions(+), 122 deletions(-) diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc index a055384ad6..5b7b41cd10 100644 --- a/Documentation/git-merge.adoc +++ b/Documentation/git-merge.adoc @@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation, A merge stops if there's a conflict that cannot be resolved automatically or if `--no-commit` was provided when initiating the merge. At that point you can run `git merge --abort` or `git merge ---continue`. +--continue`. See linkgit:gitmergeconflicts[7] +(or `git help mergeconflicts`) for a guide to handling merge conflicts. `git merge --abort` will abort the merge process and try to reconstruct the pre-merge state. However, if there were uncommitted changes when the @@ -231,127 +232,6 @@ git merge v1.2.3^0 git merge --ff-only v1.2.3 ---- -HOW CONFLICTS ARE PRESENTED ---------------------------- - -During a merge, the working tree files are updated to reflect the result -of the merge. Among the changes made to the common ancestor's version, -non-overlapping ones (that is, you changed an area of the file while the -other side left that area intact, or vice versa) are incorporated in the -final result verbatim. When both sides made changes to the same area, -however, Git cannot randomly pick one side over the other, and asks you to -resolve it by leaving what both sides did to that area. - -By default, Git uses the same style as the one used by the "merge" program -from the RCS suite to present such a conflicted hunk, like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -or cleanly resolved because both sides changed the same way. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -The area where a pair of conflicting changes happened is marked with markers -+<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======` -is typically your side, and the part afterwards is typically their side. - -The default format does not show what the original said in the conflicting -area. You cannot tell how many lines are deleted and replaced with -Barbie's remark on your side. The only thing you can tell is that your -side wants to say it is hard and you'd prefer to go shopping, while the -other side wants to claim it is easy. - -An alternative style can be used by setting the `merge.conflictStyle` -configuration variable to either `diff3` or `zdiff3`. In `diff3` -style, the above conflict may look like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -<<<<<<< yours:sample.txt -or cleanly resolved because both sides changed the same way. -Conflict resolution is hard; -let's go shopping. -||||||| base:sample.txt -or cleanly resolved because both sides changed identically. -Conflict resolution is hard. -======= -or cleanly resolved because both sides changed the same way. -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -while in `zdiff3` style, it may look like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -or cleanly resolved because both sides changed the same way. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -||||||| base:sample.txt -or cleanly resolved because both sides changed identically. -Conflict resolution is hard. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses -another +|||||||+ marker that is followed by the original text. You can -tell that the original just stated a fact, and your side simply gave in to -that statement and gave up, while the other side tried to have a more -positive attitude. You can sometimes come up with a better resolution by -viewing the original. - - -HOW TO RESOLVE CONFLICTS ------------------------- - -After seeing a conflict, you can do two things: - - * Decide not to merge. The only clean-ups you need are to reset - the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; `git merge --abort` - can be used for this. - - * Resolve the conflicts. Git will mark the conflicts in - the working tree. Edit the files into shape and - `git add` them to the index. Use `git commit` or - `git merge --continue` to seal the deal. The latter command - checks whether there is a (interrupted) merge in progress - before calling `git commit`. - -You can work through the conflict with a number of tools: - - * Use a mergetool. `git mergetool` to launch a graphical - mergetool which will work through the merge with you. - - * Look at the diffs. `git diff` will show a three-way diff, - highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. `git diff AUTO_MERGE` will show what changes you've - made so far to resolve textual conflicts. - - * Look at the diffs from each branch. `git log --merge -p ` - will show diffs first for the `HEAD` version and then the - `MERGE_HEAD` version. - - * Look at the originals. `git show :1:filename` shows the - common ancestor, `git show :2:filename` shows the `HEAD` - version, and `git show :3:filename` shows the `MERGE_HEAD` - version. - - EXAMPLES -------- @@ -406,6 +286,7 @@ linkgit:git-reset[1], linkgit:git-diff[1], linkgit:git-ls-files[1], linkgit:git-add[1], linkgit:git-rm[1], linkgit:git-mergetool[1] +linkgit:gitmergeconflicts[7] GIT --- -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 3/7] [doc] git-rebase: link to new merge conflicts guide Message-ID: <128d69e482687d05aa854e51843a42c14a315d5b.1790261062.git.gitgitgadget@gmail.com> In-Reply-To: ``` From: Julia Evans Remove some of the detail about how to handle a merge conflict, since it's explained in detail in the new guide, and there probably isn't enough detail anyway. Leave the steps since rebase is special and has a `--skip` option which the other commands which cause merge conflicts don't have. Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index f6c22d1598..da70aff498 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the first problematic commit and leave conflict markers. If this happens, you can do one of these things: -1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<) - and make edits to resolve the conflict. For each file you edit, you need to - tell Git that the conflict has been resolved. You can mark the conflict as - resolved with `git add `. After resolving all of the conflicts, +1. Resolve the conflict. After resolving all of the conflicts, you can continue the rebasing process with git rebase --continue @@ -62,6 +59,9 @@ one of these things: git rebase --skip +See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`) +for a full guide to handling merge conflicts. + If you don't specify an `` to rebase onto, the upstream configured in `branch..remote` and `branch..merge` options will be used (see linkgit:git-config[1] for details) and the `--fork-point` option is @@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[] include::config/rebase.adoc[] include::config/sequencer.adoc[] +SEE ALSO +-------- + +linkgit:gitmergeconflicts[7] + GIT --- Part of the linkgit:git[1] suite -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 4/7] [doc] git-revert: link to new merge conflicts guide Message-ID: In-Reply-To: ``` From: Julia Evans Signed-off-by: Julia Evans --- Documentation/git-revert.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc index ffba365e63..0a84447a47 100644 --- a/Documentation/git-revert.adoc +++ b/Documentation/git-revert.adoc @@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory. See "Reset, restore and revert" in linkgit:git[1] for the differences between the three commands. +If there have been new commits since the reverted conflict, there may +be a merge conflict. See linkgit:gitmergeconflicts[7] +(or `git help mergeconflicts`) for a guide to handling merge conflicts. + OPTIONS ------- ...:: @@ -162,6 +166,7 @@ include::config/revert.adoc[] SEE ALSO -------- linkgit:git-cherry-pick[1] +linkgit:gitmergeconflicts[7] GIT --- -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide Message-ID: <03a6b43b5803e6bd9ebba1a49c34cb42202a7f44.1790261062.git.gitgitgadget@gmail.com> In-Reply-To: ``` From: Julia Evans Remove the discussion of merge conflicts and replace it with a link to the guide. Signed-off-by: Julia Evans --- Documentation/git-cherry-pick.adoc | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc index f4cd8b9db7..d93829600b 100644 --- a/Documentation/git-cherry-pick.adoc +++ b/Documentation/git-cherry-pick.adoc @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one introduces, recording a new commit for each. This requires your working tree to be clean (no modifications from the HEAD commit). -When it is not obvious how to apply a change, the following -happens: - -1. The current branch and `HEAD` pointer stay at the last commit - successfully made. -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that - introduced the change that is difficult to apply, unless the - `--no-commit` option was given. -3. Paths in which the change applied cleanly are updated both - in the index file and in your working tree. -4. For conflicting paths, the index file records up to three - versions, as described in the "TRUE MERGE" section of - linkgit:git-merge[1]. The working tree files will include - a description of the conflict bracketed by the usual - conflict markers `<<<<<<<` and `>>>>>>>`. -5. No other modifications are made. - -See linkgit:git-merge[1] for some hints on resolving such -conflicts. +When it is not obvious how to apply a change, there may +be a merge conflict. See linkgit:gitmergeconflicts[7] +(or `git help mergeconflicts`) for a guide to handling merge conflicts. OPTIONS ------- @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^ <4> SEE ALSO -------- linkgit:git-revert[1] +linkgit:gitmergeconflicts[7] GIT --- -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 6/7] [doc] git-pull: link to new merge conflicts guide Message-ID: In-Reply-To: ``` From: Julia Evans Signed-off-by: Julia Evans --- Documentation/git-pull.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc index 88f4fd3926..73f6d460bb 100644 --- a/Documentation/git-pull.adoc +++ b/Documentation/git-pull.adoc @@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour. If there's a merge conflict during the merge or rebase that you don't want to handle, you can safely abort it with `git merge --abort` or -`git rebase --abort`. +`git rebase --abort`. See linkgit:gitmergeconflicts[7] +(or `git help mergeconflicts`) for a guide to handling merge conflicts. OPTIONS ------- -- gitgitgadget ``` ## Julia Evans via GitGitGadget, 2026-09-24 14:44 Subject: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc Message-ID: <4505fdc9a6dec37296952107c90947e43f39bae4.1790261062.git.gitgitgadget@gmail.com> In-Reply-To: ``` From: Julia Evans Signed-off-by: Julia Evans --- .gitattributes | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitattributes b/.gitattributes index 26490ad60a..0a0fc950b1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace /t/oid-info/* text eol=lf /Documentation/git-merge.adoc conflict-marker-size=32 /Documentation/git-merge-file.adoc conflict-marker-size=32 +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32 /Documentation/gitk.adoc conflict-marker-size=32 /Documentation/user-manual.adoc conflict-marker-size=32 /t/t????-*.sh conflict-marker-size=32 -- gitgitgadget ``` ## Junio C Hamano, 2026-09-24 20:36 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` "Julia Evans via GitGitGadget" writes: > Documentation/Makefile | 1 + > Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++ > Documentation/meson.build | 1 + > 3 files changed, 296 insertions(+) > create mode 100644 Documentation/gitmergeconflicts.adoc > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index f8dea4b395..bc49641dda 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc > MAN7_TXT += giteveryday.adoc > MAN7_TXT += gitfaq.adoc > MAN7_TXT += gitglossary.adoc > +MAN7_TXT += gitmergeconflicts.adoc This unfortunately needs to be accompanied with a matching change to help the other build system. You probably want to move your change to set conflict-marker-size for this new file to this step, not at the end as if an afterthought. Documentation/meson.build | 1 + 1 file changed, 1 insertion(+) diff --git c/Documentation/meson.build w/Documentation/meson.build index 51647957e0..10b0637991 100644 --- c/Documentation/meson.build +++ w/Documentation/meson.build @@ -201,6 +201,7 @@ manpages = { 'giteveryday.adoc' : 7, 'gitfaq.adoc' : 7, 'gitglossary.adoc' : 7, + 'gitmergeconflicts.adoc' : 7, 'gitpacking.adoc' : 7, 'gitmergeconflicts.adoc' : 7, 'gitnamespaces.adoc' : 7, ``` ## Junio C Hamano, 2026-09-24 22:04 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` Junio C Hamano writes: > This unfortunately needs to be accompanied with a matching change to > help the other build system. I did get a build failure due to meson, but apparently not due to this step in the 7-patch series. > You probably want to move your change to set conflict-marker-size > for this new file to this step, not at the end as if an > afterthought. This still stands, though. Sorry, a wrong patch and a false alarm. > > > Documentation/meson.build | 1 + > 1 file changed, 1 insertion(+) > > diff --git c/Documentation/meson.build w/Documentation/meson.build > index 51647957e0..10b0637991 100644 > --- c/Documentation/meson.build > +++ w/Documentation/meson.build > @@ -201,6 +201,7 @@ manpages = { > 'giteveryday.adoc' : 7, > 'gitfaq.adoc' : 7, > 'gitglossary.adoc' : 7, > + 'gitmergeconflicts.adoc' : 7, > 'gitpacking.adoc' : 7, > 'gitmergeconflicts.adoc' : 7, > 'gitnamespaces.adoc' : 7, ``` ## Junio C Hamano, 2026-09-24 22:20 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: In-Reply-To: ``` "Julia Evans via GitGitGadget" writes: > Julia Evans (7): > [doc] Add new gitmergeconflicts man page > [doc] git-merge: link to new merge conflicts guide > [doc] git-rebase: link to new merge conflicts guide > [doc] git-revert: link to new merge conflicts guide > [doc] git-cherry-pick: link to new merge conflicts guide > [doc] git-pull: link to new merge conflicts guide > [doc] ignore conflict markers in gitmergeconflicts.adoc With this merged, 'seen' seems to fail $ make check-docs with these lines at the end ... MKDIR -p .build/lint-docs/doc-style/includes LINT DOCSTYLE includes/cmd-config-section-all.adoc LINT DOCSTYLE includes/cmd-config-section-rest.adoc GEN lint-docs-manpages no link: gitmergeconflicts Thanks. ``` ## Jeff King, 2026-09-24 23:37 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: <20260924233726.GB765100@coredump.intra.peff.net> In-Reply-To: ``` On Thu, Sep 24, 2026 at 03:20:30PM -0700, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > > > Julia Evans (7): > > [doc] Add new gitmergeconflicts man page > > [doc] git-merge: link to new merge conflicts guide > > [doc] git-rebase: link to new merge conflicts guide > > [doc] git-revert: link to new merge conflicts guide > > [doc] git-cherry-pick: link to new merge conflicts guide > > [doc] git-pull: link to new merge conflicts guide > > [doc] ignore conflict markers in gitmergeconflicts.adoc > > With this merged, 'seen' seems to fail > > $ make check-docs > > with these lines at the end > > ... > MKDIR -p .build/lint-docs/doc-style/includes > LINT DOCSTYLE includes/cmd-config-section-all.adoc > LINT DOCSTYLE includes/cmd-config-section-rest.adoc > GEN lint-docs-manpages > no link: gitmergeconflicts Weirdly applying Julia's patches myself did not result in the same error. It's only when they're merged to seen. Ah. It's due to ta/command-list-guides-sync-lint, which isn't yet in master. I think that is giving us a good signal, though. The guide should be mentioned in command-list.txt, so that it is linked from git(1). See c655855559 (doc: git: list gitdatamodel(7) as a concept guide, 2026-09-05) for some prior art. -Peff ``` ## D. Ben Knoble, 2026-09-25 16:25 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: In-Reply-To: ``` A big thank you for working on this. On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget wrote: > > Handling merge conflicts is difficult, and currently Git's guidance on merge > conflicts isn't giving users the information they need to navigate the > process. As usual, the process I used to write this was to collect comments > from Git users on the existing documentation, and then address those issues. > I listed the specific issues we're aiming to solve in the first commit > message in the series. > > This patch series introduces a new manual page, gitmergeconflicts, which > explains the process of explaining a merge conflict with examples. It also > links to that new page from the commands which can cause merge conflicts, > instead of trying to reexplain the process every time. > > This is a pretty big change, so here's a list of things I'm still > considering in the hopes that it'll help with the discussion: > > * I wrote that git commit does the same thing as git merge --continue > during a git merge , but I'm not sure if that's always true. See also discussion in https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t > * Right now we're listing git merge, git revert, git rebase, git > cherry-pick, and git pull as commands that can cause merge conflicts. I > believe that git apply and git am can also result in conflicts when > applying a patch, though it's a bit complicated because applying a patch > is a different operation than doing a 3-way merge and the tools available > for dealing with it are a different. My thought right now is to avoid the > issue of applying patches for now (because it's a whole can of worms) and > instead just try to not imply that this is necessarily an exhaustive > list. I think that's a good approach! > Also if/when the git rebase --squash changes land, then we'd need > to add git history to this list. I imagine you meant history squash? I also thought that history had punted on how to deal with conflicts (rejecting any operation which creates them) for now, since we don't have 1st-class conflicts à la Jujutsu. > * Instead of creating a new page, I considered using an include to have a > "handling merge conflicts" section in git rebase, git merge, etc. Merge > conflict resolution is complex and it's very useful to be able to include > examples: this version ended up at ~300 lines and I think that's too big > of an include, especially for short man pages like cherry-pick Sensible. I have often wished some of our includes were actually links to separate documents, to keep overall document size down. > * Explaining what "ours" and "theirs" mean was one of the hardest parts of > writing this. From polling Git users in one of my many informal Mastodon > polls about Git, my understanding is that Git users are actually > relatively unlikely to actually reason about what "ours" and "theirs" > mean when dealing with a merge conflict, and that most people prefer to > get more context instead, for example by using a mergetool or by using > diff3 or zdiff3. I heard a lot of "I can never remember which is which I > so I don't even try". So I put the information about what "ours" and > "theirs" mean relatively far down the page (with some cross-references), > so that it's easily available but not the main focus. I think the biggest reason to (ahem) reason about these is if one wants to restore --{ours,theirs} or restart and try again with a merge strategy -s {ours,theirs} [rare] or merge strategy option -X {ours,theirs} [less rare]. But, leaving it out of focus makes sense to me! > * I removed a couple of mentions of the various _HEAD references. It's hard > for me to know exactly where they belong because I personally have never > used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I > don't know how they're meant to be used. My most frequently use is "git show REBASE_HEAD" (which is what "git rebase --show-current-patch" does, albeit with more typing). :shrug: -- D. Ben Knoble ``` ## D. Ben Knoble, 2026-09-25 16:36 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: ``` Hi Julia, On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget wrote: > > From: Julia Evans > > All of the info about merge conflicts has been moved to the new guide > Among the changes made to the common ancestor's version, > -non-overlapping ones (that is, you changed an area of the file while the > -other side left that area intact, or vice versa) are incorporated in the > -final result verbatim. When both sides made changes to the same area, > -however, Git cannot randomly pick one side over the other, and asks you to > -resolve it by leaving what both sides did to that area. > - * Look at the diffs from each branch. `git log --merge -p ` > - will show diffs first for the `HEAD` version and then the > - `MERGE_HEAD` version. I think these are both valuable pieces of information we have lost in the new guide (unless I misremember just having read patch 1 :). The first explains a bit more about what a conflict *is*. Maybe that's old-hat nowadays, but I think it could be nice to keep a statement about why conflicts exist. The second is a very useful way to get more context to help resolve conflicts! I have an alias "conflict = log --oneline --graph --left-right --boundary --merge" for a similar purpose, and I think the new guide should help folks discover --merge. Often I can get a better sense of how to resolve conflicts by comparing the original changes on each side, or I might at least know who to ask about what to do. -- D. Ben Knoble ``` ## Julia Evans, 2026-09-25 16:59 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com> In-Reply-To: ``` On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote: > Hi Julia, > > On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget > wrote: >> >> From: Julia Evans >> >> All of the info about merge conflicts has been moved to the new guide > >> Among the changes made to the common ancestor's version, >> -non-overlapping ones (that is, you changed an area of the file while the >> -other side left that area intact, or vice versa) are incorporated in the >> -final result verbatim. When both sides made changes to the same area, >> -however, Git cannot randomly pick one side over the other, and asks you to >> -resolve it by leaving what both sides did to that area. > >> - * Look at the diffs from each branch. `git log --merge -p ` >> - will show diffs first for the `HEAD` version and then the >> - `MERGE_HEAD` version. > > I think these are both valuable pieces of information we have lost in > the new guide (unless I misremember just having read patch 1 :). > > The first explains a bit more about what a conflict *is*. Maybe that's > old-hat nowadays, but I think it could be nice to keep a statement > about why conflicts exist. Will think about this! > The second is a very useful way to get more context to help resolve > conflicts! I have an alias "conflict = log --oneline --graph > --left-right --boundary --merge" for a similar purpose, and I think > the new guide should help folks discover --merge. Often I can get a > better sense of how to resolve conflicts by comparing the original > changes on each side, or I might at least know who to ask about what > to do. Thanks, I meant to flag this: the reason I deleted it was really just that I couldn't understand what `git log --merge -p ` did from the documentation and so I removed it until I could figure it out. I thought that `--merge` meant that it had something to do with merge commits, but upon further investigation it looks like that's not true, and that `--merges` is related to merge commits, `--merge` is something totally different which is relevant any time there's a conflict My best guess now is that it would make sense to include this under "Tools to get more context". Maybe something like this: > `git log --merge -p ` will print out all commits which > caused the merge conflict for ``, and the diff > of how they changed the file. ("which caused the merge conflict for" is a little more vague, but I'm trying to convey the intent, and hopefully folks can look at `man git log` if they want to know the specifics) This does sound really useful. ``` ## Junio C Hamano, 2026-09-25 17:17 Subject: Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide Message-ID: In-Reply-To: <03a6b43b5803e6bd9ebba1a49c34cb42202a7f44.1790261062.git.gitgitgadget@gmail.com> ``` "Julia Evans via GitGitGadget" writes: > From: Julia Evans > > Remove the discussion of merge conflicts and replace it with a link to > the guide. > > Signed-off-by: Julia Evans > --- > Documentation/git-cherry-pick.adoc | 23 ++++------------------- > 1 file changed, 4 insertions(+), 19 deletions(-) > > diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc > index f4cd8b9db7..d93829600b 100644 > --- a/Documentation/git-cherry-pick.adoc > +++ b/Documentation/git-cherry-pick.adoc > @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one > introduces, recording a new commit for each. This requires your > working tree to be clean (no modifications from the HEAD commit). > > -When it is not obvious how to apply a change, the following > -happens: > - > -1. The current branch and `HEAD` pointer stay at the last commit > - successfully made. > -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that > - introduced the change that is difficult to apply, unless the > - `--no-commit` option was given. > -3. Paths in which the change applied cleanly are updated both > - in the index file and in your working tree. > -4. For conflicting paths, the index file records up to three > - versions, as described in the "TRUE MERGE" section of > - linkgit:git-merge[1]. The working tree files will include > - a description of the conflict bracketed by the usual > - conflict markers `<<<<<<<` and `>>>>>>>`. > -5. No other modifications are made. > - > -See linkgit:git-merge[1] for some hints on resolving such > -conflicts. > +When it is not obvious how to apply a change, there may > +be a merge conflict. See linkgit:gitmergeconflicts[7] > +(or `git help mergeconflicts`) for a guide to handling merge conflicts. The new document may explain how to resolve conflicts, but are the details removed from here that are specific to the 'cherry-pick' operation also covered there? For example, during a difficult cherry-pick, it is often handy to be able to run 'git show CHERRY_PICK_HEAD', but now users are not told about the pseudo-ref, which seems like a real loss. The fact that cleanly auto-resolved contents for paths are recorded in the index may be shared with all other merge-like operations, and it need not be part of the "how to resolve a conflicted merge-like operation" recipe, but users need to be assured that this is what happens somewhere in the documentation set. The list removed here served that purpose for this specific command, but it is now gone. I do not recall offhand whether we explicitly tell our users that all merge-like operations update the index with cleanly auto-resolved results and only leave conflicts to be hand-resolved by the user, but even if we did so elsewhere, I do not see any reference to that in the existing text of the 'cherry-pick' manual, nor does this patch series add such a link. At least item #2 and #3 should be kept in the list, I think. A better alternative might be to add your new reference, and shorten the description given in item #4, and leave everything else as before. Thanks. > > OPTIONS > ------- > @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^ <4> > SEE ALSO > -------- > linkgit:git-revert[1] > +linkgit:gitmergeconflicts[7] > > GIT > --- ``` ## Junio C Hamano, 2026-09-25 18:19 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com> ``` "Julia Evans" writes: > Thanks, I meant to flag this: the reason I deleted it was really > just that I couldn't understand what `git log --merge -p ` did > from the documentation and so I removed it until I could figure it out. It looks at the index to figure out which paths we got conflicts on, and then does "git log -p ". You can give a pathspec from the command line to further limit the output. >> `git log --merge -p ` will print out all commits which >> caused the merge conflict for ``, and the diff >> of how they changed the file. If you _know_ which exact single file you are interested in, there is not much you gain from the "--merge" option. "--left-right" option may be a lot more useful there. It let's you see which side of the merge gave you what changes. ``` ## Ben Knoble, 2026-09-25 19:32 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: <7EF35E41-8DB6-49B4-BFC6-6BE335047E60@gmail.com> In-Reply-To: ``` > Le 25 sept. 2026 à 14:19, Junio C Hamano a écrit : > > "Julia Evans" writes: > >> Thanks, I meant to flag this: the reason I deleted it was really >> just that I couldn't understand what `git log --merge -p ` did >> from the documentation and so I removed it until I could figure it out. > > It looks at the index to figure out which paths we got conflicts on, > and then does "git log -p ". You can > give a pathspec from the command line to further limit the output. This explanation omits the manual’s “HEAD…” argument that the merge option implies, which is important for understanding the option and my alias ;) ``` ## Ben Knoble, 2026-09-25 19:34 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com> ``` > Le 25 sept. 2026 à 12:59, Julia Evans a écrit : > >  > >> On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote: >> Hi Julia, [snip] >> The second is a very useful way to get more context to help resolve >> conflicts! I have an alias "conflict = log --oneline --graph >> --left-right --boundary --merge" for a similar purpose, and I think >> the new guide should help folks discover --merge. Often I can get a >> better sense of how to resolve conflicts by comparing the original >> changes on each side, or I might at least know who to ask about what >> to do. > > Thanks, I meant to flag this: the reason I deleted it was really > just that I couldn't understand what `git log --merge -p ` did > from the documentation and so I removed it until I could figure it out. > I thought that `--merge` meant that it had something to do with merge > commits, but upon further investigation it looks like that's not true, and > that `--merges` is related to merge commits, `--merge` is something > totally different which is relevant any time there's a conflict > > My best guess now is that it would make sense to include this > under "Tools to get more context". Maybe something like this: > >> `git log --merge -p ` will print out all commits which >> caused the merge conflict for ``, and the diff >> of how they changed the file. > > ("which caused the merge conflict for" is a little more vague, but > I'm trying to convey the intent, and hopefully folks can look at > `man git log` if they want to know the specifics) > > This does sound really useful. That reads well enough for me! Thanks. ``` ## Junio C Hamano, 2026-09-25 21:49 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <7EF35E41-8DB6-49B4-BFC6-6BE335047E60@gmail.com> ``` Ben Knoble writes: >> Le 25 sept. 2026 à 14:19, Junio C Hamano a écrit : >> >> "Julia Evans" writes: >> >>> Thanks, I meant to flag this: the reason I deleted it was really >>> just that I couldn't understand what `git log --merge -p ` did >>> from the documentation and so I removed it until I could figure it out. >> >> It looks at the index to figure out which paths we got conflicts on, >> and then does "git log -p ". You can >> give a pathspec from the command line to further limit the output. > > This explanation omits the manual’s “HEAD…” argument > that the merge option implies, which is important for > understanding the option and my alias ;) Ahh, yes, you're right. HEAD...MERGE_HEAD is the more important half of what --merge gives us that I failed to mention. And without the symmetric difference traversal it gives, --left-right would of course not work, either. ``` ## Julia Evans, 2026-09-28 20:41 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: <01f196af-3a6a-40e6-86c9-f8b4ce7bfe47@app.fastmail.com> In-Reply-To: <20260924233726.GB765100@coredump.intra.peff.net> ``` > I think that is giving us a good signal, though. The guide should be > mentioned in command-list.txt, so that it is linked from git(1). Thanks, will fix this (and will move the conflict-marker-size change). Should I be trying to apply my patches to `seen` before submitting them? - Julia ``` ## Julia Evans, 2026-09-28 20:58 Subject: Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide Message-ID: In-Reply-To: ``` > The new document may explain how to resolve conflicts, but are the > details removed from here that are specific to the 'cherry-pick' > operation also covered there? I'll update this series to make fewer changes to this page as you suggest to make the diff smaller. > For example, during a difficult cherry-pick, it is often handy to be > able to run 'git show CHERRY_PICK_HEAD', but now users are not told > about the pseudo-ref, which seems like a real loss. I'll put this back for now, but I removed it because I couldn't understand why CHERRY_PICK_HEAD might be useful, and some of my user research showed that almost nobody uses `CHERRY_PICK_HEAD`. I always appreciate people telling me why these things are actually useful though, and even if very few people use something, maybe more people would use it if it was clear why it's useful :) My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is only useful if you're cherry-picking multiple commits at the same time. Is the following an accurate explanation?: > If the conflict happened when cherry picking multiple commits, you can run > `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply. > The fact that cleanly auto-resolved contents for paths are recorded > in the index may be shared with all other merge-like operations, > and it need not be part of the "how to resolve a conflicted > merge-like operation" recipe, but users need to be assured that this > is what happens somewhere in the documentation set. The list > removed here served that purpose for this specific command, but it > is now gone. That makes sense to me. One major benefit of making a centralized page is that each man page explains different aspects of the merge conflict process, and we can make sure that anyone who needs to solve a merge conflict is aware of all the aspects. I'll think about how to explain that. ``` ## Junio C Hamano, 2026-09-28 21:25 Subject: Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide Message-ID: In-Reply-To: ``` "Julia Evans" writes: > My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is > only useful if you're cherry-picking multiple commits at the same time. > Is the following an accurate explanation?: > >> If the conflict happened when cherry picking multiple commits, you can run >> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply. You do not have to limit yourself to the multi-pick case. If you make it a habit to use CHERRY_PICK_HEAD, you do not have to remember exactly which commit you specified on the command line to pick when stopped by a conflict during a cherry-pick. This is especially true for those who have already made it a habit to use MERGE_HEAD when stopped by a conflict during a merge. Not having to think when you can mechanically perform a routine task is bliss. ``` ## Jeff King, 2026-09-29 01:32 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: <20260929013233.GA1089022@coredump.intra.peff.net> In-Reply-To: <01f196af-3a6a-40e6-86c9-f8b4ce7bfe47@app.fastmail.com> ``` On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote: > > I think that is giving us a good signal, though. The guide should be > > mentioned in command-list.txt, so that it is linked from git(1). > > Thanks, will fix this (and will move the conflict-marker-size change). > > Should I be trying to apply my patches to `seen` before submitting them? In general, no, you don't have to. In this case it turned up useful information for changing your series, but that's rare. The more likely outcome is that there's nothing to be changed in your series, but there's a conflict (either textual or semantic) between two topics that has to be resolved by the maintainer. Of course if you know about that conflict and can warn people in the cover letter (and sometimes even suggest a resolution, or work around it somehow), that can distribute some of the load. But I don't know that I would recommend for everyone to manually merge their topic to 'seen' in the hopes that it finds something useful. It usually won't. But depending on the rest of your workflow, you might get advanced warning of such interactions for free-ish. For example, I merge all of my personal topics every day to the "jch" branch to build the version of Git that I run day-to-day. So I learn about those interactions early when my build fails, or my personal copy breaks. ;) But that's not something I'd expect most people to do. If you do want to look ahead, I think "next" or "jch" is often a more useful target. A topic on the seen branch just means it was seen by the maintainer, and might not even pass all of the tests. Whereas "next" is fairly stable, and "jch" is (I believe) what Junio runs day to day (so a subset of "seen" that seems pretty stable). -Peff ``` ## Junio C Hamano, 2026-09-29 01:56 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: In-Reply-To: <20260929013233.GA1089022@coredump.intra.peff.net> ``` Jeff King writes: > On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote: > >> > I think that is giving us a good signal, though. The guide should be >> > mentioned in command-list.txt, so that it is linked from git(1). >> >> Thanks, will fix this (and will move the conflict-marker-size change). >> >> Should I be trying to apply my patches to `seen` before submitting them? > > In general, no, you don't have to. In this case it turned up useful > ... > If you do want to look ahead, I think "next" or "jch" is often a more > useful target. As Julia is working mostly on documentation modernization, what you and I view as an advantage may not be as relevant to her as it is to those who work with code. Regardless of which "more advanced" branch you pick to cross-check with other topics in flight, I do not think you want to apply your patches _on_ that branch. Rather, apply your patches on a stable base (e.g., a release tag, or the tip of then-current 'master'), and make a trial merge of your topic branch into the "more advanced" target branch. Even without building, you may find merge conflicts, through which you will learn what other contributors are working on in the same area. You may run git log --merge --left-right -p right there while you have conflicts, and may even learn that a helper function or two your topic would benefit from have already been written in their topics. Even when there is no textual conflict, 'make' (just building alone) may reveal that an API function your topic depends on has been updated by another topic in flight, and the result does not even build as a consequence. Again, you learn about the topics by others that may be very relevant to you. If you are working in a fairly isolated area, none of the above may happen, of course. > A topic on the seen branch just means it was seen by the > maintainer, and might not even pass all of the tests. Whereas "next" is > fairly stable, and "jch" is (I believe) what Junio runs day to day (so a > subset of "seen" that seems pretty stable). These days my personal rule is to make sure that the topics must be in 'jch' before it is marked with "Will merge to 'next'". ``` ## Patrick Steinhardt, 2026-09-30 13:19 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` On Thu, Sep 24, 2026 at 02:44:16PM +0000, Julia Evans via GitGitGadget wrote: > diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc > new file mode 100644 > index 0000000000..612b683e40 > --- /dev/null > +++ b/Documentation/gitmergeconflicts.adoc > @@ -0,0 +1,294 @@ > +gitmergeconflicts(7) > +==================== > + > +NAME > +---- > +gitmergeconflicts - Guide to handling merge conflicts > + > + > +SYNOPSIS > +-------- > +Guide to handling merge conflicts > + > + > +DESCRIPTION > +----------- > + > +Merge conflicts can happen during a `git merge`, `git rebase`, `git > +cherry-pick`, `git pull`, or `git revert`. All of those commands use Should all of these be using linkgit:, like for example in linkgit:git-merge[1]? > +the same merge algorithm, and the process for resolving a merge conflict > +is always very similar. There's also git-am(1), but only when adding the "--3way" flag. So maybe it's best to ignore that command indeed. > +The most common ways to handle a merge conflict are: > + > +* Resolve the conflict. (see <> > + below for details) > +* Or stop the operation and return your branch to its original state > + with the appropriate `--abort` command, for example `git merge --abort` > + or `git rebase --abort`. See <> below > + for how to find the command to run. I wonder whether the explanation should be expanded a bit to briefly explain how Git performs a 3-way merge in the first place. I feel like it's quite important to understand what the three different sides of the merge are to make sense of it. But I may be too far detached from the "normal" user, so this may only cause more confusion for our users. > +[[markers]] > +MERGE CONFLICT MARKERS > +---------------------- > + > +Merge conflicts happen when both of the sides being merged edit the same > +area of a file. When this happens, Git will update the conflicted file I wonder whether we want to use "hunk" instead of "area". It's jargon again, but I have never heard anybody speak about an "area" before myself. > +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. > +For example, here's a merge conflict where both sides edited a list of > +fruits in different ways: > + > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", > +======= > + "banana", > +>>>>>>> add-fruit A bit of a tangent, but sometimes I wonder whether we should make the respective commits a bit easier to access. For example, we could put the equivalent of `git rev-parse --reference ` here for each of the sides. > + "mango", > + "orange", > +] > +---- > + > +The code from one side of the merge conflict is between `<<<<<<<` and > +`=======`, and the code for the other side is between `=======` and > +`>>>>>>>`. See <> below for a full explanation > +of which side is which. > + > + > +[[resolve]] > +HOW TO RESOLVE A MERGE CONFLICT > +------------------------------- > + > +The process for resolving a merge conflict is: > + > +1. Run `git status` to get a list of files with merge conflicts > +2. For each one, find the conflict markers > + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to > + fix the conflict > +3. Run `git add FILENAME` for each file to mark the conflict as resolved > +4. Run the appropriate `--continue` command to continue the operation > + that was interrupted by the conflict, for example `git merge --continue` > + or `git rebase --continue`. See <> > + below for how to find the command to run. > ++ > +Note: During a `git merge`, `git commit` and `git merge --continue` do > +the the same thing. s/the the/the/ Maybe we should also say "During a conflicted `git merge`.", but maybe that's redundant. > +[[example]] > +EXAMPLE OF RESOLVING A MERGE CONFLICT > +------------------------------------- > + > +If you see this in your code during a merge conflict: > + > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", > + "mango", > +======= > + "banana", > + "mango", > +>>>>>>> add-fruit > + "orange", > +] > +---- > + > +Then you might edit that part of the code like this, > +which includes the fruits from both sides of the conflict: I tend to forget that by default, we only render ours/theirs in the conflict. I always feel like that makes it way harder to resolve conflicts as you don't have the context of what the code looked like originally. So I have diff3 configured locally for ages. > +---- > +FRUITS = [ > + "apple", > + "banana", > + "cherry", > + "mango", > + "orange", > +] > +---- > + > + > +[[tools]] > +TOOLS FOR HANDLING MERGE CONFLICTS > +---------------------------------- > + > +Here are some ways to get extra context while handling a merge conflict: > + > +* There are many graphical "merge tools" for Git, which will normally > + show you the different versions of the code side by side. > + If you have a mergetool configured, `git mergetool` will launch it. > + See also `merge.tool` in linkgit:git-config[1] for a list of > + the mergetools Git supports. There's also `git merge-tool --tool-help` to list all available drivers. [snip] > +[[diff3]] > +DIFF3 AND ZDIFF3 > +---------------- > + > +By default, Git doesn't include the original code when formatting > +a merge conflict. To include the original code, you can set the > +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`. > +This extra context can make it much easier to understand what's > +happening in a merge conflict. Indeed. [snip] > +[[ours]] > +"OURS" AND "THEIRS" > +------------------- > + > +Git refers to the first part of a merge conflict (between `<<<<<<<` > +and `=======`) as "ours" and the second part (between `=======` and > +`>>>>>>>`) as "theirs". > + > +Normally, "ours" is the commit that was checked out before you started > +the merge, and "theirs" is the other commit. > + > +But when the merge conflict was caused by a `git rebase`, it's the > +opposite: "theirs" is the commit that was checked out before you started > +the merge. This is because under the hood, `git rebase main` checks out > +the `main` commit first before doing the merge operation. Hmm. This part is a bit confusing to me. "ours" is always the commit that's currently checked out, and "theirs" is always the one that is getting merged into the checked-out commit. How about a variant of the following instead? In a conflict, the side between `<<<<<<<` and `=======` is "ours" and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is always the side that `HEAD` points to while the merge happens; "theirs" is the commit being merged into it. For `git merge `, `HEAD` is your current branch, so "ours" is your branch and "theirs" is ``. For `git rebase `, `HEAD` is first moved to `` and your commits are then replayed on top one at a time. So "ours" is the already-rebased history starting at ``, and "theirs" is the commit from your original branch that is currently being replayed. > +These terms in Git all mean the same thing when dealing with a merge > +conflict: > + > +* "common ancestor", "base", and "stage 1" > +* "ours", "us", "stage 2", and `HEAD` > +* "theirs", "them", and "stage 3" I wouldn't say that "stage N" is equivalent to the respective other terms. These stages rather refer to the different versions of a specific file as recorded in the index, they do not indicate a specific commit. In contrast to that, all the other terms may also indicate a specific version of a file, but may also refer to the commits. Patrick ``` ## Patrick Steinhardt, 2026-09-30 13:19 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: ``` On Thu, Sep 24, 2026 at 02:44:17PM +0000, Julia Evans via GitGitGadget wrote: > From: Julia Evans > > All of the info about merge conflicts has been moved to the new guide Pedantic nit: missing punctuation. Other than that I agree with Ben, one part that we lose here is some context on what a merge conflict even is. Patrick ``` ## Julia Evans, 2026-09-30 19:53 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: <5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com> In-Reply-To: ``` >> +Merge conflicts can happen during a `git merge`, `git rebase`, `git >> +cherry-pick`, `git pull`, or `git revert`. All of those commands use > > Should all of these be using linkgit:, like for example in > linkgit:git-merge[1]? Makes sense to me, will change. >> +The most common ways to handle a merge conflict are: >> + >> +* Resolve the conflict. (see <> >> + below for details) >> +* Or stop the operation and return your branch to its original state >> + with the appropriate `--abort` command, for example `git merge --abort` >> + or `git rebase --abort`. See <> below >> + for how to find the command to run. > > I wonder whether the explanation should be expanded a bit to briefly > explain how Git performs a 3-way merge in the first place. I feel like > it's quite important to understand what the three different sides of the > merge are to make sense of it. > > But I may be too far detached from the "normal" user, so this may only > cause more confusion for our users. I think it would cause more confusion. I did some experiments in explaining merge conflicts using the concept of 3-way merge a couple of years ago and it didn't go well. My experience was that what users they found the most useful was learning about the tools Git offers (like `git diff --check` and `diff3`), so that's why this document focuses on tools and formatting much more than concepts. I think it would be cool to find a way to explain how 3-way merge works at in this document in some later iteration though, maybe at the end. Definitely some folks would find it interesting. I didn't understand 3-way merge myself until a couple of years ago and it was fun for me to learn, but it didn't really help me use Git effectively. (this is quickly becoming a bit of a novel, but it's often very counterintuitive how some facts that seem "fundamental" about how Git works actually turn out to not be very important to understand in practice to use it effectively. It's something I find tough to talk about on this mailing list because it's something I've only been able to learn empirically) >> +[[markers]] >> +MERGE CONFLICT MARKERS >> +---------------------- >> + >> +Merge conflicts happen when both of the sides being merged edit the same >> +area of a file. When this happens, Git will update the conflicted file > > I wonder whether we want to use "hunk" instead of "area". It's jargon > again, but I have never heard anybody speak about an "area" before > myself. Ah thanks, I think I took "area" from the `git-merge` man page. I looked up how I explained this previously and I used "lines of code", which I think communicates the same meaning without the jargon. I'll try that instead. >> +Note: During a `git merge`, `git commit` and `git merge --continue` do >> +the the same thing. > > s/the the/the/ Will fix. >> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. >> +For example, here's a merge conflict where both sides edited a list of >> +fruits in different ways: >> + >> +---- >> +FRUITS = [ >> + "apple", >> +<<<<<<< HEAD >> + "cherry", >> +======= >> + "banana", >> +>>>>>>> add-fruit > Hide quoted text > > A bit of a tangent, but sometimes I wonder whether we should make the > respective commits a bit easier to access. For example, we could put the > equivalent of `git rev-parse --reference ` here for each of the > sides. Personally I'm not sure if the commit ID would do much for me, but I feel like it would help me if it were possible to include the commit message. > I tend to forget that by default, we only render ours/theirs in the > conflict. I always feel like that makes it way harder to resolve > conflicts as you don't have the context of what the code looked like > originally. So I have diff3 configured locally for ages. Every time I show people diff3 someone tells me how happy they are to learn it :) >> +* There are many graphical "merge tools" for Git, which will normally >> + show you the different versions of the code side by side. >> + If you have a mergetool configured, `git mergetool` will launch it. >> + See also `merge.tool` in linkgit:git-config[1] for a list of >> + the mergetools Git supports. > > There's also `git merge-tool --tool-help` to list all available drivers. Oh, cool! It's fun that it autodetects which ones you have installed on your system. I'll suggest that. > > [snip] >> +[[ours]] >> +"OURS" AND "THEIRS" >> +------------------- >> + >> +Git refers to the first part of a merge conflict (between `<<<<<<<` >> +and `=======`) as "ours" and the second part (between `=======` and >> +`>>>>>>>`) as "theirs". >> + >> +Normally, "ours" is the commit that was checked out before you started >> +the merge, and "theirs" is the other commit. >> + >> +But when the merge conflict was caused by a `git rebase`, it's the >> +opposite: "theirs" is the commit that was checked out before you started >> +the merge. This is because under the hood, `git rebase main` checks out >> +the `main` commit first before doing the merge operation. > > Hmm. This part is a bit confusing to me. "ours" is always the commit > that's currently checked out, and "theirs" is always the one that is > getting merged into the checked-out commit. > > How about a variant of the following instead? > > In a conflict, the side between `<<<<<<<` and `=======` is "ours" > and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is > always the side that `HEAD` points to while the merge happens; "theirs" > is the commit being merged into it. > > For `git merge `, `HEAD` is your current branch, so "ours" is > your branch and "theirs" is ``. > > For `git rebase `, `HEAD` is first moved to `` and > your commits are then replayed on top one at a time. So "ours" is the > already-rebased history starting at ``, and "theirs" is the > commit from your original branch that is currently being replayed. Thanks, your suggestion gives me some other ways to think about this. I think I'll try to write something shorter that is unambiguous, instead of trying to use more words to make it feel more intuitive. I don't think I actually know anyone who feels it's easy to understand the way merge conflicts are presented, and more explanation may not help. It might be more useful here to encourage (again) folks to use one of the many amazing tools available (in the "tools" section) to get more context. >> +These terms in Git all mean the same thing when dealing with a merge >> +conflict: >> + >> +* "common ancestor", "base", and "stage 1" >> +* "ours", "us", "stage 2", and `HEAD` >> +* "theirs", "them", and "stage 3" > > I wouldn't say that "stage N" is equivalent to the respective other > terms. These stages rather refer to the different versions of a specific > file as recorded in the index, they do not indicate a specific commit. > In contrast to that, all the other terms may also indicate a specific > version of a file, but may also refer to the commits. Thanks, will try to figure out how to make it more accurate. We could also refer to gitdatamodel if folks want to learn what the term "stage" means too. Thanks for the review! - Julia ``` ## Junio C Hamano, 2026-09-30 20:37 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: <5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com> ``` "Julia Evans" writes: >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. >>> +For example, here's a merge conflict where both sides edited a list of >>> +fruits in different ways: >>> + >>> +---- >>> +FRUITS = [ >>> + "apple", >>> +<<<<<<< HEAD >>> + "cherry", >>> +======= >>> + "banana", >>> +>>>>>>> add-fruit >> Hide quoted text >> >> A bit of a tangent, but sometimes I wonder whether we should make the >> respective commits a bit easier to access. For example, we could put the >> equivalent of `git rev-parse --reference ` here for each of the >> sides. > > Personally I'm not sure if the commit ID would do much for me, but I feel > like it would help me if it were possible to include the commit message. It would also help the resolution, not just committing after you are done. It may not matter while picking between cherry and banana to show your personal preference on fruits, but in a more involved conflicted merge, it may help to be able to view "git show $commit", "git diff ...$commit", and "git diff $commit..." where $commit is the "add-fruit" side of the merge to understand what they wanted to do, and what we have done while they weren't looking. >> I tend to forget that by default, we only render ours/theirs in the >> conflict. I always feel like that makes it way harder to resolve >> conflicts as you don't have the context of what the code looked like >> originally. So I have diff3 configured locally for ages. > > Every time I show people diff3 someone tells me how happy they > are to learn it :) Yes, we should encourage "merge.conflictstyle=diff3" (I feel about this strongly enough to think it should become the default). Knowing what the original was before one side wanted to say "cherry" while the other side wanted to say "banana" sometimes helps a great deal to decide what to do with the conflict. ``` ## Patrick Steinhardt, 2026-10-01 05:14 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote: > "Julia Evans" writes: > > >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. > >>> +For example, here's a merge conflict where both sides edited a list of > >>> +fruits in different ways: > >>> + > >>> +---- > >>> +FRUITS = [ > >>> + "apple", > >>> +<<<<<<< HEAD > >>> + "cherry", > >>> +======= > >>> + "banana", > >>> +>>>>>>> add-fruit > >> Hide quoted text > >> > >> A bit of a tangent, but sometimes I wonder whether we should make the > >> respective commits a bit easier to access. For example, we could put the > >> equivalent of `git rev-parse --reference ` here for each of the > >> sides. > > > > Personally I'm not sure if the commit ID would do much for me, but I feel > > like it would help me if it were possible to include the commit message. > > It would also help the resolution, not just committing after you are > done. It may not matter while picking between cherry and banana to > show your personal preference on fruits, but in a more involved > conflicted merge, it may help to be able to view "git show $commit", > "git diff ...$commit", and "git diff $commit..." where $commit is > the "add-fruit" side of the merge to understand what they wanted to > do, and what we have done while they weren't looking. Yup. Doesn't mean we cannot _also_ include the names that we have above. So in the above example it could be for example: +FRUITS = [ + "apple", +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01) + "cherry", +======= + "banana", +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03) That format would have a bunch of advantages: - We don't have to teach users about special refs like MERGE_HEAD to let them figure out how to access each of the commits. - It gives a bit more context about what each specific side does, at least if you have good commit messages. - It also gives a sense of timing because we include dates, and that may help in some situations to figure out what's what. I'll create an issue on the GitLab side and ask someone in the team to maybe give this a try. > >> I tend to forget that by default, we only render ours/theirs in the > >> conflict. I always feel like that makes it way harder to resolve > >> conflicts as you don't have the context of what the code looked like > >> originally. So I have diff3 configured locally for ages. > > > > Every time I show people diff3 someone tells me how happy they > > are to learn it :) > > Yes, we should encourage "merge.conflictstyle=diff3" (I feel about > this strongly enough to think it should become the default). > Knowing what the original was before one side wanted to say "cherry" > while the other side wanted to say "banana" sometimes helps a great > deal to decide what to do with the conflict. I very much agree that it should be the default. Patrick ``` ## Julia Evans, 2026-10-01 12:10 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: <86a7df9d-362a-4530-82db-44ef7500fd10@app.fastmail.com> In-Reply-To: ``` > +FRUITS = [ > + "apple", > +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01) > + "cherry", > +======= > + "banana", > +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03) > > That format would have a bunch of advantages: > > - We don't have to teach users about special refs like MERGE_HEAD to > let them figure out how to access each of the commits. > > - It gives a bit more context about what each specific side does, at > least if you have good commit messages. > > - It also gives a sense of timing because we include dates, and that > may help in some situations to figure out what's what. This is so cool, I love the idea of including the dates and the commit messages!!! I think this would be very helpful for the reasons you say. Though re "We don't have to teach users about special refs like MERGE_HEAD": I think that users today could run`git show HEAD` or `git show add-fruit` to see the commits on each side? I've never used MERGE_HEAD though so maybe I'm misunderstanding what it does. I think adding the commit ID makes it clearer too. I just ran downstairs to show my partner this example at 8am because I was so excited about it :) (he liked it too) ``` ## Julia Evans, 2026-10-02 17:01 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: <4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com> In-Reply-To: <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com> ``` On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote: > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote: >> Hi Julia, >> >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget >> wrote: >>> >>> From: Julia Evans >>> >>> All of the info about merge conflicts has been moved to the new guide >> >>> Among the changes made to the common ancestor's version, >>> -non-overlapping ones (that is, you changed an area of the file while the >>> -other side left that area intact, or vice versa) are incorporated in the >>> -final result verbatim. When both sides made changes to the same area, >>> -however, Git cannot randomly pick one side over the other, and asks you to >>> -resolve it by leaving what both sides did to that area. >> I think these are both valuable pieces of information we have lost in >> the new guide (unless I misremember just having read patch 1 :). >> >> The first explains a bit more about what a conflict *is*. Maybe that's >> old-hat nowadays, but I think it could be nice to keep a statement >> about why conflicts exist. > > Will think about this! After talking this through with my collaborator Marie, we wrote a new "what is a merge conflict?" section which I'll include in the v2. Like I mentioned before elsewhere it takes a super light approach to introducing the 3-way merge. (there is intentionally no mention of "since they diverged from the common ancestor" etc) WHAT IS A MERGE CONFLICT? ------------------------- When Git merges two commits together, it looks at the changes that each side has made and combines those changes. For example, if one side edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of `hello.py`, then it can easily combine them. But if both sides edited overlapping lines of the same file (for example one side edited lines 1-5 and the other edited lines 3-6), Git will not try to guess how to combine those changes. This is called a "merge conflict". When this happens, Git shows you both sides' edits and asks you to pick how to resolve them. It: * Stages all of the files which were successfully merged * For the files with conflicts, it leaves them unstaged, puts both sides' edits in the file, and leaves <> that you need to resolve. ``` ## Julia Evans, 2026-10-02 17:39 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: <91396552-f86b-47d7-9805-8f6056c2ed66@app.fastmail.com> In-Reply-To: ``` Thanks for the review! >> * I wrote that git commit does the same thing as git merge --continue >> during a git merge , but I'm not sure if that's always true. > > See also discussion in > https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t Wow, that's a very interesting read. I'm more informed than I was before I read it but also at the same time more confused :). It makes me think that "git commit does the same thing as git merge --continue" is maybe not true but also I don't know what the difference might be. I've put an item on my TODO list to remove `git commit does the same thing as git merge --continue`" and to try to replace it with a more vague sentence that I guess says you can use either command without being so specific on whether they are exactly the same. >> Also if/when the git rebase --squash changes land, then we'd need >> to add git history to this list. > > I imagine you meant history squash? I also thought that history had > punted on how to deal with conflicts (rejecting any operation which > creates them) for now, since we don't have 1st-class conflicts à la > Jujutsu. Good to know! Removed this from my v2 cover letter draft. ``` ## Junio C Hamano, 2026-10-02 17:50 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com> ``` "Julia Evans" writes: > Like I mentioned before elsewhere it takes a super light approach to > introducing the 3-way merge. (there is intentionally no mention > of "since they diverged from the common ancestor" etc) > > WHAT IS A MERGE CONFLICT? > ------------------------- > > When Git merges two commits together, it looks at the changes that > each side has made and combines those changes. For example, if one side > edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of > `hello.py`, then it can easily combine them. Some immediate reactions. - Is it obvious that the reason why it can "easily combine" them, or would it help to be more explicit (i.e., "as there is no overlap")? - The second "of `hello.py`" forced me to go back and look at the first one again to make sure we are talking about the same file. I would imagine if the latter were "lines 20-25 of the same file", it would have read better at least to me. > But if both sides edited overlapping lines of the same file (for example > one side edited lines 1-5 and the other edited lines 3-6), Git will > not try to guess how to combine those changes. This is called a "merge > conflict". - "cannot guess" would be more direct than "will not try to guess". > When this happens, Git shows you both sides' edits and asks you to pick > how to resolve them. It: > > * Stages all of the files which were successfully merged - "merged without conflicts" would be more direct than "successfully merged". > * For the files with conflicts, it leaves them unstaged, puts both > sides' edits in the file, and leaves <> > that you need to resolve. - "unstaged" sounds as if somebody ran "git rm --cached" on the paths, but that is not what you want to tell your readers. - "it leaves them unstaged" -> "it remembers them as conflicted", perhaps? This hints that Git has a mechanism to remember the conflicted paths even after you removed the conflict markers from the file to your readers. ``` ## Junio C Hamano, 2026-10-02 17:58 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` Junio C Hamano writes: >>>> +FRUITS = [ >>>> + "apple", >>>> +<<<<<<< HEAD >>>> + "cherry", >>>> +======= >>>> + "banana", >>>> +>>>>>>> add-fruit > >> Every time I show people diff3 someone tells me how happy they >> are to learn it :) > > Yes, we should encourage "merge.conflictstyle=diff3" (I feel about > this strongly enough to think it should become the default). > Knowing what the original was before one side wanted to say "cherry" > while the other side wanted to say "banana" sometimes helps a great > deal to decide what to do with the conflict. Before I forget, here is a good illustration to tell why diff3 style is often essential to correct conflict resolution that we can tell new users. You may want to throw it in to your new manual pages. If the conflict looks like this FRUITS = [ "apple", <<<<<<< HEAD "cherry", ||||||| ======= "banana", >>>>>>> add-fruit then we can tell that in the beginning there was only 'apple', and one side wanted to add 'cherry', while the other side wanted to add 'banana'. It is likely that we would make both sides happy by adding both of them. But on the other hand, if the conflict looks like this FRUITS = [ "apple", <<<<<<< HEAD "cherry", ||||||| "banana", "cherry", ======= "banana", >>>>>>> add-fruit we can tell that before two sides started editing, we had 'apple', 'banana', and 'cherry'. While both wanted to keep 'apple', one side did not want 'banana', and the other side did not want 'cherry'. It is plausible that we can please both of them by removing these two. With just two-sides, the user who is trying to resolve the conflict cannot tell the difference. ``` ## Julia Evans, 2026-10-02 18:53 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: <7861e492-6fa4-4768-afdd-65cd346b85be@app.fastmail.com> In-Reply-To: ``` >> WHAT IS A MERGE CONFLICT? >> ------------------------- >> >> When Git merges two commits together, it looks at the changes that >> each side has made and combines those changes. For example, if one side >> edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of >> `hello.py`, then it can easily combine them. > > Some immediate reactions. Thanks, incorporated a few of these ("it marks them as conflicted", "since there's no overlap", "the same file") >> But if both sides edited overlapping lines of the same file (for example >> one side edited lines 1-5 and the other edited lines 3-6), Git will >> not try to guess how to combine those changes. This is called a "merge >> conflict". > > - "cannot guess" would be more direct than "will not try to guess". The way I think about it as a user is that Git takes an intentionally conservative approach and I appreciate the conservatism. Compared to a more aggressive syntax-aware merge system like `mergiraf` which has done merges I don't agree with. ``` ## Junio C Hamano, 2026-10-02 21:38 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <7861e492-6fa4-4768-afdd-65cd346b85be@app.fastmail.com> ``` "Julia Evans" writes: >> - "cannot guess" would be more direct than "will not try to guess". > > The way I think about it as a user is that Git takes an intentionally conservative > approach and I appreciate the conservatism. Compared to a more aggressive > syntax-aware merge system like `mergiraf` which has done merges I don't > agree with. Your disagreement with their result suggests that they guessed when they could not do so reliably. I agree that our approach is more conservative, but we can call it being more honest. ;-). ``` ## D. Ben Knoble, 2026-10-03 02:25 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com> ``` On Fri, Oct 2, 2026 at 1:01 PM Julia Evans wrote: > > > > On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote: > > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote: > >> Hi Julia, > >> > >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget > >> wrote: > >>> > >>> From: Julia Evans > >>> > >>> All of the info about merge conflicts has been moved to the new guide > >> > >>> Among the changes made to the common ancestor's version, > >>> -non-overlapping ones (that is, you changed an area of the file while the > >>> -other side left that area intact, or vice versa) are incorporated in the > >>> -final result verbatim. When both sides made changes to the same area, > >>> -however, Git cannot randomly pick one side over the other, and asks you to > >>> -resolve it by leaving what both sides did to that area. > > >> I think these are both valuable pieces of information we have lost in > >> the new guide (unless I misremember just having read patch 1 :). > >> > >> The first explains a bit more about what a conflict *is*. Maybe that's > >> old-hat nowadays, but I think it could be nice to keep a statement > >> about why conflicts exist. > > > > Will think about this! > > After talking this through with my collaborator Marie, we wrote a new > "what is a merge conflict?" section which I'll include in the v2. > > Like I mentioned before elsewhere it takes a super light approach to > introducing the 3-way merge. (there is intentionally no mention > of "since they diverged from the common ancestor" etc) > > WHAT IS A MERGE CONFLICT? > ------------------------- > > When Git merges two commits together, it looks at the changes that > each side has made and combines those changes. For example, if one side > edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of > `hello.py`, then it can easily combine them. > > But if both sides edited overlapping lines of the same file (for example > one side edited lines 1-5 and the other edited lines 3-6), Git will > not try to guess how to combine those changes. This is called a "merge > conflict". > > When this happens, Git shows you both sides' edits and asks you to pick > how to resolve them. It: > > * Stages all of the files which were successfully merged > * For the files with conflicts, it leaves them unstaged, puts both > sides' edits in the file, and leaves <> > that you need to resolve. > I quite like this. I'm sure it oversimplifies somewhere, but at least I personally cannot immediately see where (or how it does any harm to) ;) Thanks! PS Unlike Junio---perhaps due to my lack of older Git history and terminology, despite using Git since 2016?---I would never have read "unstaged" as *deleted* from the index. Just changed and not updated in the index (i.e., not "git add"-ed). -- D. Ben Knoble ``` ## D. Ben Knoble, 2026-10-03 02:29 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: In-Reply-To: <91396552-f86b-47d7-9805-8f6056c2ed66@app.fastmail.com> ``` On Fri, Oct 2, 2026 at 1:40 PM Julia Evans wrote: > > Thanks for the review! > > >> * I wrote that git commit does the same thing as git merge --continue > >> during a git merge , but I'm not sure if that's always true. > > > > See also discussion in > > https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t > > Wow, that's a very interesting read. I'm more informed than I was before > I read it but also at the same time more confused :). It makes me think > that "git commit does the same thing as git merge --continue" is maybe > not true but also I don't know what the difference might be. > > I've put an item on my TODO list to remove > `git commit does the same thing as git merge --continue`" and to try to > replace it with a more vague sentence that I guess says you can use > either command without being so specific on whether they are exactly > the same. For now I would say the subtleties in that conversation really make me lean towards the following: - "git --continue" is, for most users in most cases, the right thing to do. It's what "git status" recommends and will practically never do anything surprising (?). - However, it may not always be exactly what you *want*---and you'll usually know when you want to go "outside" the normal sequencer and commit directly (because you'll have understood some nuanced details about what can happen). For merge it may be the case that they're the same, I suppose (I'm genuinely not sure), but I would prefer to simplify folks' paths by recommending one of the few uniform interfaces we have :) ``` ## Junio C Hamano, 2026-10-03 04:12 Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: ``` "D. Ben Knoble" writes: > PS Unlike Junio---perhaps due to my lack of older Git history and > terminology, despite using Git since 2016?---I would never have read > "unstaged" as *deleted* from the index. Just changed and not updated > in the index (i.e., not "git add"-ed). I agree such an interpretation is certainly possible. The verb "to unstage" would be the opposite of "to stage", but it is ambiguous what kind of oppositeness you want to express. This is unlike "to stage" whose possible interpretation is fairly narrow. You register the contents that you consider desirable for the path using various means. On the other hand, "to unstage" is undoing the result of your earlier act "to stage", but it may mean reverting to what is recorded in HEAD (i.e., "git reset HEAD -- path"), undoing the fact that you added a path to the index (i.e., "git rm --cached -- path"). Neither interpretation is what you want when talking about what a conflicted merge does to remember the three stages for a conflicted path in the index. Hence my suggestion to avoid using the verb. ``` ## Julia Evans, 2026-10-05 16:54 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: <5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com> ``` >> [snip] >>> +[[ours]] >>> +"OURS" AND "THEIRS" >>> +------------------- >>> + >>> +Git refers to the first part of a merge conflict (between `<<<<<<<` >>> +and `=======`) as "ours" and the second part (between `=======` and >>> +`>>>>>>>`) as "theirs". >>> + >>> +Normally, "ours" is the commit that was checked out before you started >>> +the merge, and "theirs" is the other commit. >>> + >>> +But when the merge conflict was caused by a `git rebase`, it's the >>> +opposite: "theirs" is the commit that was checked out before you started >>> +the merge. This is because under the hood, `git rebase main` checks out >>> +the `main` commit first before doing the merge operation. >> >> Hmm. This part is a bit confusing to me. "ours" is always the commit >> that's currently checked out, and "theirs" is always the one that is >> getting merged into the checked-out commit. >> >> How about a variant of the following instead? >> >> In a conflict, the side between `<<<<<<<` and `=======` is "ours" >> and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is >> always the side that `HEAD` points to while the merge happens; "theirs" >> is the commit being merged into it. >> >> For `git merge `, `HEAD` is your current branch, so "ours" is >> your branch and "theirs" is ``. >> >> For `git rebase `, `HEAD` is first moved to `` and >> your commits are then replayed on top one at a time. So "ours" is the >> already-rebased history starting at ``, and "theirs" is the >> commit from your original branch that is currently being replayed. > > Thanks, your suggestion gives me some other ways to think about this. > > I think I'll try to write something shorter that is unambiguous, > instead of trying > to use more words to make it feel more intuitive. I don't think I > actually know > anyone who feels it's easy to understand the way merge conflicts are > presented, and more explanation may not help. > > It might be more useful here to encourage (again) folks to use one of the many > amazing tools available (in the "tools" section) to get more context. > >>> +These terms in Git all mean the same thing when dealing with a merge >>> +conflict: >>> + >>> +* "common ancestor", "base", and "stage 1" >>> +* "ours", "us", "stage 2", and `HEAD` >>> +* "theirs", "them", and "stage 3" >> >> I wouldn't say that "stage N" is equivalent to the respective other >> terms. These stages rather refer to the different versions of a specific >> file as recorded in the index, they do not indicate a specific commit. >> In contrast to that, all the other terms may also indicate a specific >> version of a file, but may also refer to the commits. > > Thanks, will try to figure out how to make it more accurate. > We could also refer to gitdatamodel if folks want to learn what the > term "stage" means too. Marie and I worked on the OURS AND THEIRS section today and I think it's clearer now but also longer (instead of shorter which was my dream). We added an attempt at humor at the end to hopefully help things a bit. "OURS" AND "THEIRS" ------------------- Sometimes during a merge conflict, Git will use the terms "ours" and "theirs" (or "us" and "them"). For example, `git status` might say that a file was `deleted by us`. "Ours" and "theirs" are both commits: "ours" is the current `HEAD` commit, and "theirs" is the other side being merged. The first part of a merge conflict (between `<<<<<<<` and `=======`) is from the "ours" side, and the second part (between `=======` and `>>>>>>>`) is from the "theirs" side. ---- FRUITS = [ "apple", <<<<<<< HEAD "cherry", <- ours ======= "banana", <- theirs >>>>>>> add-fruit "mango", "orange", ] ---- During a rebase, it can seem "upside down" because the "ours" commit is from the branch you're rebasing on (for instance `main` in `git rebase main`). These terms in Git all mean the same thing when dealing with a merge conflict: * "common ancestor" and "base". The files from this commit are "in stage 1". * "ours", "us", and `HEAD`. The files from this commit are "in stage 2". * "theirs", "them". The files from this commit are "in stage 3". If you're confused about what something like "deleted by us" means, it's often easiest to use some of the tools from <> above to get more context. Finding the commit that deleted the file and seeing why is usually more helpful than trying to abstractly reason through what "us" means. ``` ## Junio C Hamano, 2026-10-05 17:22 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` "Julia Evans" writes: > Marie and I worked on the OURS AND THEIRS section today and I think it's clearer > now but also longer (instead of shorter which was my dream). We added an attempt > at humor at the end to hopefully help things a bit. > > "OURS" AND "THEIRS" > ------------------- > > Sometimes during a merge conflict, Git will use the terms "ours" and > "theirs" (or "us" and "them"). For example, `git status` might say that > a file was `deleted by us`. > > "Ours" and "theirs" are both commits: "ours" is the current > `HEAD` commit, and "theirs" is the other side being merged. > > The first part of a merge conflict (between `<<<<<<<` and `=======`) is > from the "ours" side, and the second part (between `=======` and > `>>>>>>>`) is from the "theirs" side. > > ---- > FRUITS = [ > "apple", > <<<<<<< HEAD > "cherry", <- ours > ======= > "banana", <- theirs > >>>>>>> add-fruit > "mango", > "orange", > ] > ---- > > During a rebase, it can seem "upside down" because the "ours" commit is > from the branch you're rebasing on (for instance `main` in `git rebase > main`). > > These terms in Git all mean the same thing when dealing with a merge > conflict: > > * "common ancestor" and "base". The files from this commit are "in stage 1". > * "ours", "us", and `HEAD`. The files from this commit are "in stage 2". > * "theirs", "them". The files from this commit are "in stage 3". > > If you're confused about what something like "deleted by us" means, it's > often easiest to use some of the tools from > <> above to get more context. > Finding the commit that deleted the file and seeing why is usually more > helpful than trying to abstractly reason through what "us" means. May I ask what is in scope for this effort? We previously discussed updating the conflict markers (the 'HEAD' and 'add-fruit' labels in the example above). Doing so would require code changes, which goes beyond mere documentation updates. But if a minor code change like that makes the documentation much easier to understand, I think we should consider doing so. Along the same line, if git status stopped saying "deleted by us" and instead used a different phrase, would that help reduce the "upside down" confusion [*]? Is it acceptable to bend the code a little if it helps the documentation? [Footnote] * I suspect that the "upside down" feeling is not really about the terms "ours" and "theirs" themselves. Rather, it comes from how one conceptualizes what 'rebase' does compared to 'merge'. During a rebase, we temporarily pretend that we are working on the upstream branch and replay our local changes on top of it. Once the user adopts this mindset, displaying the upstream state first (the point from which we start building the consolidated history) followed by the local state (what was done differently by the local side) becomes consistent with how 'merge' displays conflicts (where we start from our local state and merge the incoming changes). ``` ## Julia Evans, 2026-10-05 18:49 Subject: Re: [PATCH 0/7] [doc] Add new page on merge conflicts Message-ID: <623cdf71-8076-4967-aff1-3ebeb57d1e3a@app.fastmail.com> In-Reply-To: ``` On Fri, Oct 2, 2026, at 10:29 PM, D. Ben Knoble wrote: > On Fri, Oct 2, 2026 at 1:40 PM Julia Evans wrote: >> >> Thanks for the review! >> >> >> * I wrote that git commit does the same thing as git merge --continue >> >> during a git merge , but I'm not sure if that's always true. >> > >> > See also discussion in >> > https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t >> >> Wow, that's a very interesting read. I'm more informed than I was before >> I read it but also at the same time more confused :). It makes me think >> that "git commit does the same thing as git merge --continue" is maybe >> not true but also I don't know what the difference might be. >> >> I've put an item on my TODO list to remove >> `git commit does the same thing as git merge --continue`" and to try to >> replace it with a more vague sentence that I guess says you can use >> either command without being so specific on whether they are exactly >> the same. > > For now I would say the subtleties in that conversation really make me > lean towards the following: > > - "git --continue" is, for most users in most cases, the right > thing to do. It's what "git status" recommends and will practically > never do anything surprising (?). I was actually surprised to discover that `git status` does not recommend `git merge --continue`: it recommends `git commit`. Maybe we should change that though? I agree it makes sense to be consistent with what `git status` recommends. > - However, it may not always be exactly what you *want*---and you'll > usually know when you want to go "outside" the normal sequencer and > commit directly (because you'll have understood some nuanced details > about what can happen). > > For merge it may be the case that they're the same, I suppose (I'm > genuinely not sure), but I would prefer to simplify folks' paths by > recommending one of the few uniform interfaces we have :) The only other thing that gives me pause about recommending folks `git merge --continue` too strongly is that as we know Git users are slow to change their habits, and we don't want to confuse anyone. If someone is currently using `git commit` I want to know that they can keep doing it the same way with no worries. Maybe if we change `git status` to recommend `git merge --continue`, and we think there are no real advantages to using `git commit` instead of `git merge --continue`, then we could say something like this: NOTE: `git commit` is an older alternative to `git merge --continue`. You can use either one after resolving a `git merge`. ``` ## Julia Evans, 2026-10-05 19:11 Subject: Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page Message-ID: In-Reply-To: ``` >> During a rebase, it can seem "upside down" because the "ours" commit is >> from the branch you're rebasing on (for instance `main` in `git rebase >> main`). >> >> These terms in Git all mean the same thing when dealing with a merge >> conflict: >> >> * "common ancestor" and "base". The files from this commit are "in stage 1". >> * "ours", "us", and `HEAD`. The files from this commit are "in stage 2". >> * "theirs", "them". The files from this commit are "in stage 3". >> >> If you're confused about what something like "deleted by us" means, it's >> often easiest to use some of the tools from >> <> above to get more context. >> Finding the commit that deleted the file and seeing why is usually more >> helpful than trying to abstractly reason through what "us" means. > > May I ask what is in scope for this effort? > > We previously discussed updating the conflict markers (the 'HEAD' > and 'add-fruit' labels in the example above). Doing so would > require code changes, which goes beyond mere documentation updates. > But if a minor code change like that makes the documentation much > easier to understand, I think we should consider doing so. > > Along the same line, if git status stopped saying "deleted by us" > and instead used a different phrase, would that help reduce the > "upside down" confusion [*]? Is it acceptable to bend the code > a little if it helps the documentation? I agree that would make sense. I have some changes to advice (on other areas) in local branches on my machine already :) I think of it as sort of "documentation driven development" (write the documentation, and if it feels upsetting what the documentation is saying, then try to change the code so we're happier with the docs!) I don't have a clear idea for how to improve the way `git status` presents merge conflicts to make it less confusing right now though. Brainstorming a bit, here's some commentary on this `git status` output: On branch main Your branch and 'origin/main' have diverged, and have 2 and 1 different commits each, respectively. (use "git pull" if you want to integrate the remote branch with yours) You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge) Unmerged paths: (use "git add ..." to mark resolution) both modified: fruits.py no changes added to commit (use "git add" and/or "git commit -a") 1. `(use "git pull" if you want to integrate the remote branch with yours)` is not helpful advice here, it's not even allowed to run `git pull` in the middle of a merge conflict. 2. `git add` is sort of not helpful here, all of the unmerged files currently have conflict markers, so the next step is definitely not to run `git add`, it's to edit one of the unmerged files. But perhaps it's unrealistic to be running the equivalent of `git diff --check` in `git status` just to help users out. 3. Not sure if "unmerged" is the best term here, maybe "conflicted"? 4. It gives the advice to use `git add` twice which is weird. 5. One part of the advice refers to the process of fixing conflicts as "fix conflicts" but the other part calls it "mark resolution". Should probably be consistent there. But as you can see those comments are all over the place, some of them are just wording changes, some of them would involve adding a bunch of conditional logic to the advice system that might not be realistic, I don't know. > [Footnote] > > * I suspect that the "upside down" feeling is not really about the > terms "ours" and "theirs" themselves. Rather, it comes from how > one conceptualizes what 'rebase' does compared to 'merge'. > During a rebase, we temporarily pretend that we are working on > the upstream branch and replay our local changes on top of it. > Once the user adopts this mindset, displaying the upstream state > first (the point from which we start building the consolidated > history) followed by the local state (what was done differently > by the local side) becomes consistent with how 'merge' displays > conflicts (where we start from our local state and merge the > incoming changes). I will say that I know all of these facts but it has never helped me to remember "ours" and "theirs" :). I'm pretty resistant in general to telling people they need to adopt the "right mindset", IMO it's normal for people to have different points of view. When explaining Git I heard a lot of "yes I know all that but I just don't like to think about it that way" and it really helped me to learn to respect when folks said that and try to see it from their point of view. ```