{"thread":{"id":"66387","subject":"[PATCH 0/7] [doc] Add new page on merge conflicts","startedAt":"2026-09-24T14:44:24Z","lastAt":"2026-10-26T17:22:23Z","messageCount":109,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Jeff King","D. Ben Knoble","Julia Evans","Ben Knoble","Patrick Steinhardt"],"isPatch":true,"patchVersion":1,"patchTotal":7},"messages":[{"id":"553192","messageId":"pull.2237.git.1790261062.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":null,"subject":"[PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:15Z","receivedAt":"2026-09-24T14:44:24Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Handling merge conflicts is difficult, and currently Git's guidance on merge\nconflicts isn't giving users the information they need to navigate the\nprocess. As usual, the process I used to write this was to collect comments\nfrom Git users on the existing documentation, and then address those issues.\nI listed the specific issues we're aiming to solve in the first commit\nmessage in the series.\n\nThis patch series introduces a new manual page, gitmergeconflicts, which\nexplains the process of explaining a merge conflict with examples. It also\nlinks to that new page from the commands which can cause merge conflicts,\ninstead of trying to reexplain the process every time.\n\nThis is a pretty big change, so here's a list of things I'm still\nconsidering in the hopes that it'll help with the discussion:\n\n * I wrote that git commit does the same thing as git merge --continue\n   during a git merge , but I'm not sure if that's always true.\n * Not 100% sure that the explanation of diff3 vs zdiff3 is correct\n * Right now we're listing git merge, git revert, git rebase, git\n   cherry-pick, and git pull as commands that can cause merge conflicts. I\n   believe that git apply and git am can also result in conflicts when\n   applying a patch, though it's a bit complicated because applying a patch\n   is a different operation than doing a 3-way merge and the tools available\n   for dealing with it are a different. My thought right now is to avoid the\n   issue of applying patches for now (because it's a whole can of worms) and\n   instead just try to not imply that this is necessarily an exhaustive\n   list. Also if/when the git rebase --squash changes land, then we'd need\n   to add git history to this list.\n * Instead of creating a new page, I considered using an include to have a\n   \"handling merge conflicts\" section in git rebase, git merge, etc. Merge\n   conflict resolution is complex and it's very useful to be able to include\n   examples: this version ended up at ~300 lines and I think that's too big\n   of an include, especially for short man pages like cherry-pick\n * Explaining what \"ours\" and \"theirs\" mean was one of the hardest parts of\n   writing this. From polling Git users in one of my many informal Mastodon\n   polls about Git, my understanding is that Git users are actually\n   relatively unlikely to actually reason about what \"ours\" and \"theirs\"\n   mean when dealing with a merge conflict, and that most people prefer to\n   get more context instead, for example by using a mergetool or by using\n   diff3 or zdiff3. I heard a lot of \"I can never remember which is which I\n   so I don't even try\". So I put the information about what \"ours\" and\n   \"theirs\" mean relatively far down the page (with some cross-references),\n   so that it's easily available but not the main focus.\n * I removed a couple of mentions of the various _HEAD references. It's hard\n   for me to know exactly where they belong because I personally have never\n   used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I\n   don't know how they're meant to be used. From some quick unscientific\n   polling (at https://social.jvns.ca/@b0rk/117320011885941855), it seems\n   like most Git users have never used them either (and folks who do use a\n   *_HEAD reference mainly seem to use FETCH_HEAD which isn't relevant\n   here), so from that perspective it seems important to avoid emphasizing\n   them too much. The git revert man page doesn't mention REVERT_HEAD and\n   git rebase only mentions REBASE_HEAD in passing. Of course they're all\n   explained in gitrevisions(7) which might be the best place for them.\n * I'm still not sure what the SYNOPSIS section is for in a \"guide\" man page\n   which is not about a specific Git command (what is the user intended to\n   use it for?). I tried to leave it out but the CI said it was required.\n\nThanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\nand about 12 others who gave feedback on both the original git merge man\npage, as well as the proposed improvements.\n\nJulia Evans (7):\n  [doc] Add new gitmergeconflicts man page\n  [doc] git-merge: link to new merge conflicts guide\n  [doc] git-rebase: link to new merge conflicts guide\n  [doc] git-revert: link to new merge conflicts guide\n  [doc] git-cherry-pick: link to new merge conflicts guide\n  [doc] git-pull: link to new merge conflicts guide\n  [doc] ignore conflict markers in gitmergeconflicts.adoc\n\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/git-cherry-pick.adoc   |  23 +--\n Documentation/git-merge.adoc         | 125 +-----------\n Documentation/git-pull.adoc          |   3 +-\n Documentation/git-rebase.adoc        |  13 +-\n Documentation/git-revert.adoc        |   5 +\n Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n 9 files changed, 320 insertions(+), 146 deletions(-)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2237\n-- \ngitgitgadget\n"},{"id":"553193","messageId":"ad4853dc36cdb883c9a8dc6bda747a5ea318e7a8.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:16Z","receivedAt":"2026-09-24T14:44:25Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nIntroduce a new page, `gitmergeconflicts`, that explains the process of\nhandling a merge conflict in a way that addresses the following issues,\nwhich came from feedback from Git users on the current explanation of\nmerge conflicts in the `git merge` man page:\n\n- The process for resolving a merge conflict is only explained in the\n  `git merge` man page, even though there are several other commands\n  which can result in conflicts\n- Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n  the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n  be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n  Similarly, it says \"The part before the `=======` is typically your\n  side...\", but doesn't explain what \"typically\" means.\n- It introduces the merge format using an analogy to RCS, which very few\n  Git users have ever used\n- In \"The only clean-ups you need are to reset the index file to the\n  `HEAD` commit to reverse 2. and to clean up working tree changes made\n  by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n  to mean\n- It uses a cultural reference (\"Conflict resolution is hard; let's go\n  shopping.\") which is confusing or unfamiliar to some people. I think it\n  would be clearer for users to use a code example instead.\n- It doesn't explain the difference between diff3 and zdiff3\n- It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n\nAlso document the unified `--abort`, `--continue` workflow in one\nplace, since it's a really nice example of a place Git has a consistent\ninterface between similar commands.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/Makefile               |   1 +\n Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n 3 files changed, 296 insertions(+)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..bc49641dda 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\n MAN7_TXT += gitglossary.adoc\n+MAN7_TXT += gitmergeconflicts.adoc\n MAN7_TXT += gitpacking.adoc\n MAN7_TXT += gitnamespaces.adoc\n MAN7_TXT += gitremote-helpers.adoc\ndiff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\nnew file mode 100644\nindex 0000000000..612b683e40\n--- /dev/null\n+++ b/Documentation/gitmergeconflicts.adoc\n@@ -0,0 +1,294 @@\n+gitmergeconflicts(7)\n+====================\n+\n+NAME\n+----\n+gitmergeconflicts - Guide to handling merge conflicts\n+\n+\n+SYNOPSIS\n+--------\n+Guide to handling merge conflicts\n+\n+\n+DESCRIPTION\n+-----------\n+\n+Merge conflicts can happen during a `git merge`, `git rebase`, `git\n+cherry-pick`, `git pull`, or `git revert`. All of those commands use\n+the same merge algorithm, and the process for resolving a merge conflict\n+is always very similar.\n+\n+The most common ways to handle a merge conflict are:\n+\n+* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n+  below for details)\n+* Or stop the operation and return your branch to its original state\n+  with the appropriate `--abort` command, for example `git merge --abort`\n+  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n+  for how to find the command to run.\n+\n+\n+[[markers]]\n+MERGE CONFLICT MARKERS\n+----------------------\n+\n+Merge conflicts happen when both of the sides being merged edit the same\n+area of a file. When this happens, Git will update the conflicted file\n+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n+For example, here's a merge conflict where both sides edited a list of\n+fruits in different ways:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+The code from one side of the merge conflict is between `<<<<<<<` and\n+`=======`, and the code for the other side is between `=======` and\n+`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n+of which side is which.\n+\n+\n+[[resolve]]\n+HOW TO RESOLVE A MERGE CONFLICT\n+-------------------------------\n+\n+The process for resolving a merge conflict is:\n+\n+1. Run `git status` to get a list of files with merge conflicts\n+2. For each one, find the conflict markers\n+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n+   fix the conflict\n+3. Run `git add FILENAME` for each file to mark the conflict as resolved\n+4. Run the appropriate `--continue` command to continue the operation\n+   that was interrupted by the conflict, for example `git merge --continue`\n+   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n+   below for how to find the command to run.\n++\n+Note: During a `git merge`, `git commit` and `git merge --continue` do\n+the the same thing.\n+\n+\n+[[example]]\n+EXAMPLE OF RESOLVING A MERGE CONFLICT\n+-------------------------------------\n+\n+If you see this in your code during a merge conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+Then you might edit that part of the code like this,\n+which includes the fruits from both sides of the conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"banana\",\n+    \"cherry\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[tools]]\n+TOOLS FOR HANDLING MERGE CONFLICTS\n+----------------------------------\n+\n+Here are some ways to get extra context while handling a merge conflict:\n+\n+* There are many graphical \"merge tools\" for Git, which will normally\n+  show you the different versions of the code side by side.\n+  If you have a mergetool configured, `git mergetool` will launch it.\n+  See also `merge.tool` in linkgit:git-config[1] for a list of\n+  the mergetools Git supports.\n+\n+* You can set the configuration option `merge.conflictstyle=diff3`.\n+  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n+\n+* Look at the original files.  `git show :1:filename` shows the\n+  common ancestor, `git show :2:filename` shows the \"ours\"\n+  version, and `git show :3:filename` shows the \"theirs\"\n+  version.\n+\n+Here are some ways to track your progress while handling a conflict:\n+\n+* Use `git status` to get a list of files with conflicts\n+\n+* Use `git diff --check` to make sure you haven't left any merge\n+  conflict markers in a file by accident. It will print \"leftover\n+  conflict marker\" if it finds any.\n+\n+* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n+  resolve the conflicts.\n+\n+[[git_status]]\n+EXAMPLE: GIT STATUS OUTPUT\n+--------------------------\n+\n+When you're in a merge conflict, you can find out what commands to run\n+to handle the conflict by running `git status`.\n+\n+For example, this `git status` output tells you that:\n+\n+* `git rebase --abort` will safely bring your branch back to its\n+  original state\n+* you should run `git rebase --continue` when you're done resolving all\n+  the conflicts\n+* there's one file left with conflicts in it: `fruits.py`\n+\n+----\n+$ git status\n+You are currently rebasing branch 'main' on '58a9fcc'.\n+  (fix conflicts and then run \"git rebase --continue\")\n+  (use \"git rebase --skip\" to skip this patch)\n+  (use \"git rebase --abort\" to check out the original branch)\n+\n+Unmerged paths:\n+  (use \"git restore --staged <file>...\" to unstage)\n+  (use \"git add <file>...\" to mark resolution)\n+        both modified:   fruits.py\n+----\n+\n+\n+[[diff3]]\n+DIFF3 AND ZDIFF3\n+----------------\n+\n+By default, Git doesn't include the original code when formatting\n+a merge conflict. To include the original code, you can set the\n+configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n+This extra context can make it much easier to understand what's\n+happening in a merge conflict.\n+\n+Here's an example of what a merge conflict would look like when using\n+`diff3`. It shows, in order, the \"ours\" side of the conflict, the\n+original code (`\"mangoooo\"`), and the \"theirs\" side of the\n+conflict. With this view, you can see that both sides fixed the spelling\n+mistake in \"mango\", and each added one fruit to the list.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+||||||| 1c22e48\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+Here's the same example using `zdiff3`. `zdiff3` takes lines that are\n+shared between both sides (the `\"mango\"` line) and moves them outside\n+the conflicted area. This makes the conflicted area shorter, but the\n+downside is that it's impossible to tell if `\"mango\"` was part of the\n+original list of fruits or not.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+||||||| 1c22e48\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[ours]]\n+\"OURS\" AND \"THEIRS\"\n+-------------------\n+\n+Git refers to the first part of a merge conflict (between `<<<<<<<`\n+and `=======`) as \"ours\" and the second part (between `=======` and\n+`>>>>>>>`) as \"theirs\".\n+\n+Normally, \"ours\" is the commit that was checked out before you started\n+the merge, and \"theirs\" is the other commit.\n+\n+But when the merge conflict was caused by a `git rebase`, it's the\n+opposite: \"theirs\" is the commit that was checked out before you started\n+the merge. This is because under the hood, `git rebase main` checks out\n+the `main` commit first before doing the merge operation.\n+\n+These terms in Git all mean the same thing when dealing with a merge\n+conflict:\n+\n+* \"common ancestor\", \"base\", and \"stage 1\"\n+* \"ours\", \"us\", \"stage 2\", and `HEAD`\n+* \"theirs\", \"them\", and \"stage 3\"\n+\n+[[automerge]]\n+Example of using `AUTO_MERGE`\n+-----------------------------\n+\n+`git diff AUTO_MERGE` will show what changes you've made so far to\n+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n+merge. It contains the result of running the merge algorithm.\n+\n+For example, if we resolved the conflict the way we did in the\n+<<example,example above>>, the diff would look like this:\n+\n+----\n+ FRUITS = [\n+     \"apple\",\n+-<<<<<<< HEAD\n+-    \"cherry\",\n+-=======\n+     \"banana\",\n+->>>>>>> add-fruit\n++    \"cherry\",\n+     \"mango\",\n+     \"orange\",\n+]\n+----\n+\n+[NOTE]\n+`AUTO_MERGE` is only set if you're using the default Git merge algorithm.\n+\n+\n+SEE ALSO\n+--------\n+\n+linkgit:git-revert[1]\n+linkgit:git-merge[1]\n+linkgit:git-rebase[1]\n+linkgit:git-cherry-pick[1]\n+linkgit:git-pull[1]\n+linkgit:git-diff[1]\n+\n+GIT\n+---\n+\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f4854f802d..51647957e0 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -202,6 +202,7 @@ manpages = {\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n   'gitpacking.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n   'gitremote-helpers.adoc' : 7,\n   'gitrevisions.adoc' : 7,\n-- \ngitgitgadget\n\n"},{"id":"553194","messageId":"a1686a2d82ef9357ecff07c1247092d3dd5ecf95.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:17Z","receivedAt":"2026-09-24T14:44:27Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAll of the info about merge conflicts has been moved to the new guide\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-merge.adoc | 125 +----------------------------------\n 1 file changed, 3 insertions(+), 122 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex a055384ad6..5b7b41cd10 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation,\n A merge stops if there's a conflict that cannot be resolved\n automatically or if `--no-commit` was provided when initiating the\n merge. At that point you can run `git merge --abort` or `git merge\n---continue`.\n+--continue`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n `git merge --abort` will abort the merge process and try to reconstruct\n the pre-merge state. However, if there were uncommitted changes when the\n@@ -231,127 +232,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-HOW CONFLICTS ARE PRESENTED\n----------------------------\n-\n-During a merge, the working tree files are updated to reflect the result\n-of the merge.  Among the changes made to the common ancestor's version,\n-non-overlapping ones (that is, you changed an area of the file while the\n-other side left that area intact, or vice versa) are incorporated in the\n-final result verbatim.  When both sides made changes to the same area,\n-however, Git cannot randomly pick one side over the other, and asks you to\n-resolve it by leaving what both sides did to that area.\n-\n-By default, Git uses the same style as the one used by the \"merge\" program\n-from the RCS suite to present such a conflicted hunk, like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-The area where a pair of conflicting changes happened is marked with markers\n-+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n-is typically your side, and the part afterwards is typically their side.\n-\n-The default format does not show what the original said in the conflicting\n-area.  You cannot tell how many lines are deleted and replaced with\n-Barbie's remark on your side.  The only thing you can tell is that your\n-side wants to say it is hard and you'd prefer to go shopping, while the\n-other side wants to claim it is easy.\n-\n-An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n-style, the above conflict may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-<<<<<<< yours:sample.txt\n-or cleanly resolved because both sides changed the same way.\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-or cleanly resolved because both sides changed the same way.\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-while in `zdiff3` style, it may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n-another +|||||||+ marker that is followed by the original text.  You can\n-tell that the original just stated a fact, and your side simply gave in to\n-that statement and gave up, while the other side tried to have a more\n-positive attitude.  You can sometimes come up with a better resolution by\n-viewing the original.\n-\n-\n-HOW TO RESOLVE CONFLICTS\n-------------------------\n-\n-After seeing a conflict, you can do two things:\n-\n- * Decide not to merge.  The only clean-ups you need are to reset\n-   the index file to the `HEAD` commit to reverse 2. and to clean\n-   up working tree changes made by 2. and 3.; `git merge --abort`\n-   can be used for this.\n-\n- * Resolve the conflicts.  Git will mark the conflicts in\n-   the working tree.  Edit the files into shape and\n-   `git add` them to the index.  Use `git commit` or\n-   `git merge --continue` to seal the deal. The latter command\n-   checks whether there is a (interrupted) merge in progress\n-   before calling `git commit`.\n-\n-You can work through the conflict with a number of tools:\n-\n- * Use a mergetool.  `git mergetool` to launch a graphical\n-   mergetool which will work through the merge with you.\n-\n- * Look at the diffs.  `git diff` will show a three-way diff,\n-   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n-   versions. `git diff AUTO_MERGE` will show what changes you've\n-   made so far to resolve textual conflicts.\n-\n- * Look at the diffs from each branch. `git log --merge -p <path>`\n-   will show diffs first for the `HEAD` version and then the\n-   `MERGE_HEAD` version.\n-\n- * Look at the originals.  `git show :1:filename` shows the\n-   common ancestor, `git show :2:filename` shows the `HEAD`\n-   version, and `git show :3:filename` shows the `MERGE_HEAD`\n-   version.\n-\n-\n EXAMPLES\n --------\n \n@@ -406,6 +286,7 @@ linkgit:git-reset[1],\n linkgit:git-diff[1], linkgit:git-ls-files[1],\n linkgit:git-add[1], linkgit:git-rm[1],\n linkgit:git-mergetool[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"553195","messageId":"128d69e482687d05aa854e51843a42c14a315d5b.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 3/7] [doc] git-rebase: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:18Z","receivedAt":"2026-09-24T14:44:28Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove some of the detail about how to handle a merge conflict, since\nit's explained in detail in the new guide, and there probably isn't\nenough detail anyway.\n\nLeave the steps since rebase is special and has a `--skip` option which\nthe other commands which cause merge conflicts don't have.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-rebase.adoc | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..da70aff498 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the\n first problematic commit and leave conflict markers. If this happens, you can do\n one of these things:\n \n-1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)\n-   and make edits to resolve the conflict. For each file you edit, you need to\n-   tell Git that the conflict has been resolved. You can mark the conflict as\n-   resolved with  `git add <filename>`. After resolving all of the conflicts,\n+1. Resolve the conflict. After resolving all of the conflicts,\n    you can continue the rebasing process with\n \n    git rebase --continue\n@@ -62,6 +59,9 @@ one of these things:\n \n    git rebase --skip\n \n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a full guide to handling merge conflicts.\n+\n If you don't specify an `<upstream>` to rebase onto, the upstream configured in\n `branch.<name>.remote` and `branch.<name>.merge` options will be used (see\n linkgit:git-config[1] for details) and the `--fork-point` option is\n@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[]\n include::config/rebase.adoc[]\n include::config/sequencer.adoc[]\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitmergeconflicts[7]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \ngitgitgadget\n\n"},{"id":"553196","messageId":"ab459231e024c5c254ee7f336fcac2e249309bd4.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 4/7] [doc] git-revert: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:19Z","receivedAt":"2026-09-24T14:44:29Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-revert.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e63..0a84447a47 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n+If there have been new commits since the reverted conflict, there may\n+be a merge conflict. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n+\n OPTIONS\n -------\n <commit>...::\n@@ -162,6 +166,7 @@ include::config/revert.adoc[]\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"553197","messageId":"03a6b43b5803e6bd9ebba1a49c34cb42202a7f44.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:20Z","receivedAt":"2026-09-24T14:44:31Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove the discussion of merge conflicts and replace it with a link to\nthe guide.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-cherry-pick.adoc | 23 ++++-------------------\n 1 file changed, 4 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex f4cd8b9db7..d93829600b 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one\n introduces, recording a new commit for each.  This requires your\n working tree to be clean (no modifications from the HEAD commit).\n \n-When it is not obvious how to apply a change, the following\n-happens:\n-\n-1. The current branch and `HEAD` pointer stay at the last commit\n-   successfully made.\n-2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that\n-   introduced the change that is difficult to apply, unless the\n-   `--no-commit` option was given.\n-3. Paths in which the change applied cleanly are updated both\n-   in the index file and in your working tree.\n-4. For conflicting paths, the index file records up to three\n-   versions, as described in the \"TRUE MERGE\" section of\n-   linkgit:git-merge[1].  The working tree files will include\n-   a description of the conflict bracketed by the usual\n-   conflict markers `<<<<<<<` and `>>>>>>>`.\n-5. No other modifications are made.\n-\n-See linkgit:git-merge[1] for some hints on resolving such\n-conflicts.\n+When it is not obvious how to apply a change, there may\n+be a merge conflict. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n@@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n SEE ALSO\n --------\n linkgit:git-revert[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n"},{"id":"553198","messageId":"d3904f0ca7ad0c2274d642dfc72b863647df487f.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 6/7] [doc] git-pull: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:21Z","receivedAt":"2026-09-24T14:44:32Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-pull.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 88f4fd3926..73f6d460bb 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n \n If there's a merge conflict during the merge or rebase that you don't\n want to handle, you can safely abort it with `git merge --abort` or\n-`git rebase --abort`.\n+`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"553199","messageId":"4505fdc9a6dec37296952107c90947e43f39bae4.1790261062.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-24T14:44:22Z","receivedAt":"2026-09-24T14:44:33Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n .gitattributes | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/.gitattributes b/.gitattributes\nindex 26490ad60a..0a0fc950b1 100644\n--- a/.gitattributes\n+++ b/.gitattributes\n@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n /t/oid-info/* text eol=lf\n /Documentation/git-merge.adoc conflict-marker-size=32\n /Documentation/git-merge-file.adoc conflict-marker-size=32\n+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n /Documentation/gitk.adoc conflict-marker-size=32\n /Documentation/user-manual.adoc conflict-marker-size=32\n /t/t????-*.sh conflict-marker-size=32\n-- \ngitgitgadget\n"},{"id":"553239","messageId":"xmqqa4p61j4w.fsf@gitster.g","threadId":"66387","inReplyTo":"ad4853dc36cdb883c9a8dc6bda747a5ea318e7a8.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-24T20:36:47Z","receivedAt":"2026-09-24T20:36:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  Documentation/Makefile               |   1 +\n>  Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++\n>  Documentation/meson.build            |   1 +\n>  3 files changed, 296 insertions(+)\n>  create mode 100644 Documentation/gitmergeconflicts.adoc\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index f8dea4b395..bc49641dda 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n>  MAN7_TXT += giteveryday.adoc\n>  MAN7_TXT += gitfaq.adoc\n>  MAN7_TXT += gitglossary.adoc\n> +MAN7_TXT += gitmergeconflicts.adoc\n\nThis unfortunately needs to be accompanied with a matching change to\nhelp the other build system.\n\nYou probably want to move your change to set conflict-marker-size\nfor this new file to this step, not at the end as if an\nafterthought.\n\n\n Documentation/meson.build | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git c/Documentation/meson.build w/Documentation/meson.build\nindex 51647957e0..10b0637991 100644\n--- c/Documentation/meson.build\n+++ w/Documentation/meson.build\n@@ -201,6 +201,7 @@ manpages = {\n   'giteveryday.adoc' : 7,\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitpacking.adoc' : 7,\n   'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n"},{"id":"553243","messageId":"xmqqo6dmz4p2.fsf@gitster.g","threadId":"66387","inReplyTo":"xmqqa4p61j4w.fsf@gitster.g","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-24T22:04:41Z","receivedAt":"2026-09-24T22:04:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> This unfortunately needs to be accompanied with a matching change to\n> help the other build system.\n\nI did get a build failure due to meson, but apparently not due to\nthis step in the 7-patch series.\n\n> You probably want to move your change to set conflict-marker-size\n> for this new file to this step, not at the end as if an\n> afterthought.\n\nThis still stands, though.\n\nSorry, a wrong patch and a false alarm.\n\n>\n>\n>  Documentation/meson.build | 1 +\n>  1 file changed, 1 insertion(+)\n>\n> diff --git c/Documentation/meson.build w/Documentation/meson.build\n> index 51647957e0..10b0637991 100644\n> --- c/Documentation/meson.build\n> +++ w/Documentation/meson.build\n> @@ -201,6 +201,7 @@ manpages = {\n>    'giteveryday.adoc' : 7,\n>    'gitfaq.adoc' : 7,\n>    'gitglossary.adoc' : 7,\n> +  'gitmergeconflicts.adoc' : 7,\n>    'gitpacking.adoc' : 7,\n>    'gitmergeconflicts.adoc' : 7,\n>    'gitnamespaces.adoc' : 7,\n"},{"id":"553247","messageId":"xmqq33uyz3yp.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-24T22:20:30Z","receivedAt":"2026-09-24T22:20:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Julia Evans (7):\n>   [doc] Add new gitmergeconflicts man page\n>   [doc] git-merge: link to new merge conflicts guide\n>   [doc] git-rebase: link to new merge conflicts guide\n>   [doc] git-revert: link to new merge conflicts guide\n>   [doc] git-cherry-pick: link to new merge conflicts guide\n>   [doc] git-pull: link to new merge conflicts guide\n>   [doc] ignore conflict markers in gitmergeconflicts.adoc\n\nWith this merged, 'seen' seems to fail\n\n\t$ make check-docs\n\nwith these lines at the end\n\n            ...\n            MKDIR -p .build/lint-docs/doc-style/includes\n            LINT DOCSTYLE includes/cmd-config-section-all.adoc\n            LINT DOCSTYLE includes/cmd-config-section-rest.adoc\n            GEN lint-docs-manpages\n        no link: gitmergeconflicts\n\nThanks.\n"},{"id":"553252","messageId":"20260924233726.GB765100@coredump.intra.peff.net","threadId":"66387","inReplyTo":"xmqq33uyz3yp.fsf@gitster.g","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-24T23:37:26Z","receivedAt":"2026-09-24T23:37:27Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Sep 24, 2026 at 03:20:30PM -0700, Junio C Hamano wrote:\n\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n> > Julia Evans (7):\n> >   [doc] Add new gitmergeconflicts man page\n> >   [doc] git-merge: link to new merge conflicts guide\n> >   [doc] git-rebase: link to new merge conflicts guide\n> >   [doc] git-revert: link to new merge conflicts guide\n> >   [doc] git-cherry-pick: link to new merge conflicts guide\n> >   [doc] git-pull: link to new merge conflicts guide\n> >   [doc] ignore conflict markers in gitmergeconflicts.adoc\n> \n> With this merged, 'seen' seems to fail\n> \n> \t$ make check-docs\n> \n> with these lines at the end\n> \n>             ...\n>             MKDIR -p .build/lint-docs/doc-style/includes\n>             LINT DOCSTYLE includes/cmd-config-section-all.adoc\n>             LINT DOCSTYLE includes/cmd-config-section-rest.adoc\n>             GEN lint-docs-manpages\n>         no link: gitmergeconflicts\n\nWeirdly applying Julia's patches myself did not result in the same\nerror. It's only when they're merged to seen. Ah. It's due to\nta/command-list-guides-sync-lint, which isn't yet in master.\n\nI think that is giving us a good signal, though. The guide should be\nmentioned in command-list.txt, so that it is linked from git(1). See\nc655855559 (doc: git: list gitdatamodel(7) as a concept guide,\n2026-09-05) for some prior art.\n\n-Peff\n"},{"id":"553295","messageId":"CALnO6CA_=OsznkQ4iT0vBMWf3L=bmVKMBdk1MTHQdaKEcKwn4g@mail.gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-09-25T16:25:44Z","receivedAt":"2026-09-25T16:25:57Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"A big thank you for working on this.\n\nOn Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> Handling merge conflicts is difficult, and currently Git's guidance on merge\n> conflicts isn't giving users the information they need to navigate the\n> process. As usual, the process I used to write this was to collect comments\n> from Git users on the existing documentation, and then address those issues.\n> I listed the specific issues we're aiming to solve in the first commit\n> message in the series.\n>\n> This patch series introduces a new manual page, gitmergeconflicts, which\n> explains the process of explaining a merge conflict with examples. It also\n> links to that new page from the commands which can cause merge conflicts,\n> instead of trying to reexplain the process every time.\n>\n> This is a pretty big change, so here's a list of things I'm still\n> considering in the hopes that it'll help with the discussion:\n>\n>  * I wrote that git commit does the same thing as git merge --continue\n>    during a git merge , but I'm not sure if that's always true.\n\nSee also discussion in\nhttps://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t\n\n>  * Right now we're listing git merge, git revert, git rebase, git\n>    cherry-pick, and git pull as commands that can cause merge conflicts. I\n>    believe that git apply and git am can also result in conflicts when\n>    applying a patch, though it's a bit complicated because applying a patch\n>    is a different operation than doing a 3-way merge and the tools available\n>    for dealing with it are a different. My thought right now is to avoid the\n>    issue of applying patches for now (because it's a whole can of worms) and\n>    instead just try to not imply that this is necessarily an exhaustive\n>    list.\n\nI think that's a good approach!\n\n> Also if/when the git rebase --squash changes land, then we'd need\n>    to add git history to this list.\n\nI imagine you meant history squash? I also thought that history had\npunted on how to deal with conflicts (rejecting any operation which\ncreates them) for now, since we don't have 1st-class conflicts à la\nJujutsu.\n\n>  * Instead of creating a new page, I considered using an include to have a\n>    \"handling merge conflicts\" section in git rebase, git merge, etc. Merge\n>    conflict resolution is complex and it's very useful to be able to include\n>    examples: this version ended up at ~300 lines and I think that's too big\n>    of an include, especially for short man pages like cherry-pick\n\nSensible. I have often wished some of our includes were actually links\nto separate documents, to keep overall document size down.\n\n>  * Explaining what \"ours\" and \"theirs\" mean was one of the hardest parts of\n>    writing this. From polling Git users in one of my many informal Mastodon\n>    polls about Git, my understanding is that Git users are actually\n>    relatively unlikely to actually reason about what \"ours\" and \"theirs\"\n>    mean when dealing with a merge conflict, and that most people prefer to\n>    get more context instead, for example by using a mergetool or by using\n>    diff3 or zdiff3. I heard a lot of \"I can never remember which is which I\n>    so I don't even try\". So I put the information about what \"ours\" and\n>    \"theirs\" mean relatively far down the page (with some cross-references),\n>    so that it's easily available but not the main focus.\n\nI think the biggest reason to (ahem) reason about these is if one\nwants to restore --{ours,theirs} or restart and try again with a merge\nstrategy -s {ours,theirs} [rare] or merge strategy option -X\n{ours,theirs} [less rare].\n\nBut, leaving it out of focus makes sense to me!\n\n>  * I removed a couple of mentions of the various _HEAD references. It's hard\n>    for me to know exactly where they belong because I personally have never\n>    used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I\n>    don't know how they're meant to be used.\n\nMy most frequently use is \"git show REBASE_HEAD\" (which is what \"git\nrebase --show-current-patch\" does, albeit with more typing). :shrug:\n\n-- \nD. Ben Knoble\n"},{"id":"553299","messageId":"CALnO6CDdoqE2hyZMJg6OZkzNtcnjNXRz=HO4q6cZVpF_wbTXyw@mail.gmail.com","threadId":"66387","inReplyTo":"a1686a2d82ef9357ecff07c1247092d3dd5ecf95.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-09-25T16:36:10Z","receivedAt":"2026-09-25T16:36:24Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"Hi Julia,\n\nOn Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> From: Julia Evans <julia@jvns.ca>\n>\n> All of the info about merge conflicts has been moved to the new guide\n\n> Among the changes made to the common ancestor's version,\n> -non-overlapping ones (that is, you changed an area of the file while the\n> -other side left that area intact, or vice versa) are incorporated in the\n> -final result verbatim.  When both sides made changes to the same area,\n> -however, Git cannot randomly pick one side over the other, and asks you to\n> -resolve it by leaving what both sides did to that area.\n\n> - * Look at the diffs from each branch. `git log --merge -p <path>`\n> -   will show diffs first for the `HEAD` version and then the\n> -   `MERGE_HEAD` version.\n\nI think these are both valuable pieces of information we have lost in\nthe new guide (unless I misremember just having read patch 1 :).\n\nThe first explains a bit more about what a conflict *is*. Maybe that's\nold-hat nowadays, but I think it could be nice to keep a statement\nabout why conflicts exist.\n\nThe second is a very useful way to get more context to help resolve\nconflicts! I have an alias \"conflict = log --oneline --graph\n--left-right --boundary --merge\" for a similar purpose, and I think\nthe new guide should help folks discover --merge. Often I can get a\nbetter sense of how to resolve conflicts by comparing the original\nchanges on each side, or I might at least know who to ask about what\nto do.\n\n-- \nD. Ben Knoble\n"},{"id":"553303","messageId":"2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com","threadId":"66387","inReplyTo":"CALnO6CDdoqE2hyZMJg6OZkzNtcnjNXRz=HO4q6cZVpF_wbTXyw@mail.gmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-25T16:59:35Z","receivedAt":"2026-09-25T16:59:59Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:\n> Hi Julia,\n>\n> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>>\n>> From: Julia Evans <julia@jvns.ca>\n>>\n>> All of the info about merge conflicts has been moved to the new guide\n>\n>> Among the changes made to the common ancestor's version,\n>> -non-overlapping ones (that is, you changed an area of the file while the\n>> -other side left that area intact, or vice versa) are incorporated in the\n>> -final result verbatim.  When both sides made changes to the same area,\n>> -however, Git cannot randomly pick one side over the other, and asks you to\n>> -resolve it by leaving what both sides did to that area.\n>\n>> - * Look at the diffs from each branch. `git log --merge -p <path>`\n>> -   will show diffs first for the `HEAD` version and then the\n>> -   `MERGE_HEAD` version.\n>\n> I think these are both valuable pieces of information we have lost in\n> the new guide (unless I misremember just having read patch 1 :).\n>\n> The first explains a bit more about what a conflict *is*. Maybe that's\n> old-hat nowadays, but I think it could be nice to keep a statement\n> about why conflicts exist.\n\nWill think about this!\n\n> The second is a very useful way to get more context to help resolve\n> conflicts! I have an alias \"conflict = log --oneline --graph\n> --left-right --boundary --merge\" for a similar purpose, and I think\n> the new guide should help folks discover --merge. Often I can get a\n> better sense of how to resolve conflicts by comparing the original\n> changes on each side, or I might at least know who to ask about what\n> to do.\n\nThanks, I meant to flag this: the reason I deleted it was really\njust that I couldn't understand what `git log --merge -p <path>`  did\nfrom the documentation and so I removed it until I could figure it out.\nI thought that `--merge` meant that it had something to do with merge\ncommits, but upon further investigation it looks like that's not true, and\nthat `--merges` is related to merge commits, `--merge` is something\ntotally different which is relevant any time there's a conflict\n\nMy best guess now is that it would make sense to include this\nunder \"Tools to get more context\". Maybe something like this:\n\n> `git log --merge -p <filename>`  will print out all commits which\n>   caused the merge conflict for `<filename>`, and the diff\n>  of how they changed the file. \n\n(\"which caused the merge conflict for\" is a little more vague, but\nI'm trying to convey the intent, and hopefully folks can look at\n`man git log` if they want to know the specifics)\n\nThis does sound really useful.\n"},{"id":"553304","messageId":"xmqqpky1uu6t.fsf@gitster.g","threadId":"66387","inReplyTo":"03a6b43b5803e6bd9ebba1a49c34cb42202a7f44.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T17:17:30Z","receivedAt":"2026-09-25T17:17:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Remove the discussion of merge conflicts and replace it with a link to\n> the guide.\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-cherry-pick.adoc | 23 ++++-------------------\n>  1 file changed, 4 insertions(+), 19 deletions(-)\n>\n> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\n> index f4cd8b9db7..d93829600b 100644\n> --- a/Documentation/git-cherry-pick.adoc\n> +++ b/Documentation/git-cherry-pick.adoc\n> @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one\n>  introduces, recording a new commit for each.  This requires your\n>  working tree to be clean (no modifications from the HEAD commit).\n>  \n> -When it is not obvious how to apply a change, the following\n> -happens:\n> -\n> -1. The current branch and `HEAD` pointer stay at the last commit\n> -   successfully made.\n> -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that\n> -   introduced the change that is difficult to apply, unless the\n> -   `--no-commit` option was given.\n> -3. Paths in which the change applied cleanly are updated both\n> -   in the index file and in your working tree.\n> -4. For conflicting paths, the index file records up to three\n> -   versions, as described in the \"TRUE MERGE\" section of\n> -   linkgit:git-merge[1].  The working tree files will include\n> -   a description of the conflict bracketed by the usual\n> -   conflict markers `<<<<<<<` and `>>>>>>>`.\n> -5. No other modifications are made.\n> -\n> -See linkgit:git-merge[1] for some hints on resolving such\n> -conflicts.\n> +When it is not obvious how to apply a change, there may\n> +be a merge conflict. See linkgit:gitmergeconflicts[7]\n> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n\nThe new document may explain how to resolve conflicts, but are the\ndetails removed from here that are specific to the 'cherry-pick'\noperation also covered there?\n\nFor example, during a difficult cherry-pick, it is often handy to be\nable to run 'git show CHERRY_PICK_HEAD', but now users are not told\nabout the pseudo-ref, which seems like a real loss.\n\nThe fact that cleanly auto-resolved contents for paths are recorded\nin the index may be shared with all other merge-like operations,\nand it need not be part of the \"how to resolve a conflicted\nmerge-like operation\" recipe, but users need to be assured that this\nis what happens somewhere in the documentation set.  The list\nremoved here served that purpose for this specific command, but it\nis now gone.\n\nI do not recall offhand whether we explicitly tell our users that\nall merge-like operations update the index with cleanly auto-resolved\nresults and only leave conflicts to be hand-resolved by the user,\nbut even if we did so elsewhere, I do not see any reference to that\nin the existing text of the 'cherry-pick' manual, nor does this\npatch series add such a link.  At least item #2 and #3 should be\nkept in the list, I think.  A better alternative might be to add\nyour new reference, and shorten the description given in item #4,\nand leave everything else as before.\n\nThanks.\n\n>  \n>  OPTIONS\n>  -------\n> @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n>  SEE ALSO\n>  --------\n>  linkgit:git-revert[1]\n> +linkgit:gitmergeconflicts[7]\n>  \n>  GIT\n>  ---\n"},{"id":"553307","messageId":"xmqqld8purb8.fsf@gitster.g","threadId":"66387","inReplyTo":"2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T18:19:39Z","receivedAt":"2026-09-25T18:19:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Thanks, I meant to flag this: the reason I deleted it was really\n> just that I couldn't understand what `git log --merge -p <path>`  did\n> from the documentation and so I removed it until I could figure it out.\n\nIt looks at the index to figure out which paths we got conflicts on,\nand then does \"git log -p <those> <conflicted> <paths>\".  You can\ngive a pathspec from the command line to further limit the output.\n\n>> `git log --merge -p <filename>`  will print out all commits which\n>>   caused the merge conflict for `<filename>`, and the diff\n>>  of how they changed the file. \n\nIf you _know_ which exact single file you are interested in, there\nis not much you gain from the \"--merge\" option.  \"--left-right\"\noption may be a lot more useful there.  It let's you see which side\nof the merge gave you what changes.\n"},{"id":"553314","messageId":"7EF35E41-8DB6-49B4-BFC6-6BE335047E60@gmail.com","threadId":"66387","inReplyTo":"xmqqld8purb8.fsf@gitster.g","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-09-25T19:32:34Z","receivedAt":"2026-09-25T19:32:49Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 25 sept. 2026 à 14:19, Junio C Hamano <gitster@pobox.com> a écrit :\n> \n> ﻿\"Julia Evans\" <julia@jvns.ca> writes:\n> \n>> Thanks, I meant to flag this: the reason I deleted it was really\n>> just that I couldn't understand what `git log --merge -p <path>`  did\n>> from the documentation and so I removed it until I could figure it out.\n> \n> It looks at the index to figure out which paths we got conflicts on,\n> and then does \"git log -p <those> <conflicted> <paths>\".  You can\n> give a pathspec from the command line to further limit the output.\n\nThis explanation omits the manual’s “HEAD…<other>” argument\nthat the merge option implies, which is important for\nunderstanding the option and my alias ;)"},{"id":"553315","messageId":"C66B019E-9107-49BA-B54A-6B82BF11CB77@gmail.com","threadId":"66387","inReplyTo":"2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-09-25T19:34:09Z","receivedAt":"2026-09-25T19:34:22Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 25 sept. 2026 à 12:59, Julia Evans <julia@jvns.ca> a écrit :\n> \n> ﻿\n> \n>> On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:\n>> Hi Julia,\n\n[snip]\n\n>> The second is a very useful way to get more context to help resolve\n>> conflicts! I have an alias \"conflict = log --oneline --graph\n>> --left-right --boundary --merge\" for a similar purpose, and I think\n>> the new guide should help folks discover --merge. Often I can get a\n>> better sense of how to resolve conflicts by comparing the original\n>> changes on each side, or I might at least know who to ask about what\n>> to do.\n> \n> Thanks, I meant to flag this: the reason I deleted it was really\n> just that I couldn't understand what `git log --merge -p <path>`  did\n> from the documentation and so I removed it until I could figure it out.\n> I thought that `--merge` meant that it had something to do with merge\n> commits, but upon further investigation it looks like that's not true, and\n> that `--merges` is related to merge commits, `--merge` is something\n> totally different which is relevant any time there's a conflict\n> \n> My best guess now is that it would make sense to include this\n> under \"Tools to get more context\". Maybe something like this:\n> \n>> `git log --merge -p <filename>`  will print out all commits which\n>>  caused the merge conflict for `<filename>`, and the diff\n>> of how they changed the file.\n> \n> (\"which caused the merge conflict for\" is a little more vague, but\n> I'm trying to convey the intent, and hopefully folks can look at\n> `man git log` if they want to know the specifics)\n> \n> This does sound really useful.\n\nThat reads well enough for me! Thanks. "},{"id":"553334","messageId":"xmqqjyo9t30c.fsf@gitster.g","threadId":"66387","inReplyTo":"7EF35E41-8DB6-49B4-BFC6-6BE335047E60@gmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T21:49:55Z","receivedAt":"2026-09-25T21:49:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Knoble <ben.knoble@gmail.com> writes:\n\n>> Le 25 sept. 2026 à 14:19, Junio C Hamano <gitster@pobox.com> a écrit :\n>> \n>> ﻿\"Julia Evans\" <julia@jvns.ca> writes:\n>> \n>>> Thanks, I meant to flag this: the reason I deleted it was really\n>>> just that I couldn't understand what `git log --merge -p <path>`  did\n>>> from the documentation and so I removed it until I could figure it out.\n>> \n>> It looks at the index to figure out which paths we got conflicts on,\n>> and then does \"git log -p <those> <conflicted> <paths>\".  You can\n>> give a pathspec from the command line to further limit the output.\n>\n> This explanation omits the manual’s “HEAD…<other>” argument\n> that the merge option implies, which is important for\n> understanding the option and my alias ;)\n\nAhh, yes, you're right.  HEAD...MERGE_HEAD is the more important\nhalf of what --merge gives us that I failed to mention.\n\nAnd without the symmetric difference traversal it gives,\n--left-right would of course not work, either.\n"},{"id":"553522","messageId":"01f196af-3a6a-40e6-86c9-f8b4ce7bfe47@app.fastmail.com","threadId":"66387","inReplyTo":"20260924233726.GB765100@coredump.intra.peff.net","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-28T20:41:54Z","receivedAt":"2026-09-28T20:42:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I think that is giving us a good signal, though. The guide should be\n> mentioned in command-list.txt, so that it is linked from git(1).\n\nThanks, will fix this (and will move the conflict-marker-size change).\n\nShould I be trying to apply my patches to `seen` before submitting them?\n\n- Julia\n"},{"id":"553527","messageId":"cc1af300-d296-49c8-98ae-8b30ef11ada3@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqpky1uu6t.fsf@gitster.g","subject":"Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-28T20:58:31Z","receivedAt":"2026-09-28T20:58:52Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n> The new document may explain how to resolve conflicts, but are the\n> details removed from here that are specific to the 'cherry-pick'\n> operation also covered there?\n\nI'll update this series to make fewer changes to this page as you\nsuggest to make the diff smaller.\n\n> For example, during a difficult cherry-pick, it is often handy to be\n> able to run 'git show CHERRY_PICK_HEAD', but now users are not told\n> about the pseudo-ref, which seems like a real loss.\n\nI'll put this back for now, but I removed it because I couldn't\nunderstand why CHERRY_PICK_HEAD might be useful, and some of my user research\nshowed that almost nobody uses `CHERRY_PICK_HEAD`. I always appreciate people\ntelling me why these things are actually useful though, and even if very few\npeople use something, maybe more people would use it if it was clear why it's\nuseful :)\n\nMy best guess (based on what you said) is that `CHERRY_PICK_HEAD` is\nonly useful if you're cherry-picking multiple commits at the same time.\nIs the following an accurate explanation?:\n\n> If the conflict happened when cherry picking multiple commits, you can run\n> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.\n\n\n\n> The fact that cleanly auto-resolved contents for paths are recorded\n> in the index may be shared with all other merge-like operations,\n> and it need not be part of the \"how to resolve a conflicted\n> merge-like operation\" recipe, but users need to be assured that this\n> is what happens somewhere in the documentation set.  The list\n> removed here served that purpose for this specific command, but it\n> is now gone.\n\nThat makes sense to me. One major benefit of making a\ncentralized page is that each man page explains different aspects\nof the merge conflict process, and we can make sure that anyone\nwho needs to solve a merge conflict is aware of all the aspects. \nI'll think about how to explain that.\n"},{"id":"553529","messageId":"xmqqh5j9kr0y.fsf@gitster.g","threadId":"66387","inReplyTo":"cc1af300-d296-49c8-98ae-8b30ef11ada3@app.fastmail.com","subject":"Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-28T21:25:01Z","receivedAt":"2026-09-28T21:25:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is\n> only useful if you're cherry-picking multiple commits at the same time.\n> Is the following an accurate explanation?:\n>\n>> If the conflict happened when cherry picking multiple commits, you can run\n>> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.\n\nYou do not have to limit yourself to the multi-pick case.  If you\nmake it a habit to use CHERRY_PICK_HEAD, you do not have to remember\nexactly which commit you specified on the command line to pick when\nstopped by a conflict during a cherry-pick.  This is especially true\nfor those who have already made it a habit to use MERGE_HEAD when\nstopped by a conflict during a merge.  Not having to think when you\ncan mechanically perform a routine task is bliss.\n\n"},{"id":"553533","messageId":"20260929013233.GA1089022@coredump.intra.peff.net","threadId":"66387","inReplyTo":"01f196af-3a6a-40e6-86c9-f8b4ce7bfe47@app.fastmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-29T01:32:33Z","receivedAt":"2026-09-29T01:32:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote:\n\n> > I think that is giving us a good signal, though. The guide should be\n> > mentioned in command-list.txt, so that it is linked from git(1).\n> \n> Thanks, will fix this (and will move the conflict-marker-size change).\n> \n> Should I be trying to apply my patches to `seen` before submitting them?\n\nIn general, no, you don't have to. In this case it turned up useful\ninformation for changing your series, but that's rare. The more likely\noutcome is that there's nothing to be changed in your series, but\nthere's a conflict (either textual or semantic) between two topics that\nhas to be resolved by the maintainer.\n\nOf course if you know about that conflict and can warn people in the\ncover letter (and sometimes even suggest a resolution, or work around it\nsomehow), that can distribute some of the load. But I don't know that I\nwould recommend for everyone to manually merge their topic to 'seen' in\nthe hopes that it finds something useful. It usually won't.\n\nBut depending on the rest of your workflow, you might get advanced\nwarning of such interactions for free-ish. For example, I merge all of\nmy personal topics every day to the \"jch\" branch to build the version of\nGit that I run day-to-day. So I learn about those interactions early\nwhen my build fails, or my personal copy breaks. ;) But that's not\nsomething I'd expect most people to do.\n\nIf you do want to look ahead, I think \"next\" or \"jch\" is often a more\nuseful target. A topic on the seen branch just means it was seen by the\nmaintainer, and might not even pass all of the tests. Whereas \"next\" is\nfairly stable, and \"jch\" is (I believe) what Junio runs day to day (so a\nsubset of \"seen\" that seems pretty stable).\n\n-Peff\n"},{"id":"553535","messageId":"xmqqse2skegz.fsf@gitster.g","threadId":"66387","inReplyTo":"20260929013233.GA1089022@coredump.intra.peff.net","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-29T01:56:12Z","receivedAt":"2026-09-29T01:56:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote:\n>\n>> > I think that is giving us a good signal, though. The guide should be\n>> > mentioned in command-list.txt, so that it is linked from git(1).\n>> \n>> Thanks, will fix this (and will move the conflict-marker-size change).\n>> \n>> Should I be trying to apply my patches to `seen` before submitting them?\n>\n> In general, no, you don't have to. In this case it turned up useful\n> ...\n> If you do want to look ahead, I think \"next\" or \"jch\" is often a more\n> useful target.\n\nAs Julia is working mostly on documentation modernization, what you\nand I view as an advantage may not be as relevant to her as it is to\nthose who work with code.\n\nRegardless of which \"more advanced\" branch you pick to cross-check\nwith other topics in flight, I do not think you want to apply your\npatches _on_ that branch.  Rather, apply your patches on a stable\nbase (e.g., a release tag, or the tip of then-current 'master'), and\nmake a trial merge of your topic branch into the \"more advanced\"\ntarget branch.\n\nEven without building, you may find merge conflicts, through which\nyou will learn what other contributors are working on in the same\narea.  You may run git log --merge --left-right -p right there while\nyou have conflicts, and may even learn that a helper function or two\nyour topic would benefit from have already been written in their\ntopics.  Even when there is no textual conflict, 'make' (just\nbuilding alone) may reveal that an API function your topic depends\non has been updated by another topic in flight, and the result does\nnot even build as a consequence.  Again, you learn about the topics\nby others that may be very relevant to you.\n\nIf you are working in a fairly isolated area, none of the above may\nhappen, of course.\n\n> A topic on the seen branch just means it was seen by the\n> maintainer, and might not even pass all of the tests. Whereas \"next\" is\n> fairly stable, and \"jch\" is (I believe) what Junio runs day to day (so a\n> subset of \"seen\" that seems pretty stable).\n\nThese days my personal rule is to make sure that the topics must be\nin 'jch' before it is marked with \"Will merge to 'next'\".\n"},{"id":"553695","messageId":"ar0MVRV5X8zgZfLy@pks.im","threadId":"66387","inReplyTo":"ad4853dc36cdb883c9a8dc6bda747a5ea318e7a8.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-09-30T13:19:17Z","receivedAt":"2026-09-30T13:19:30Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Sep 24, 2026 at 02:44:16PM +0000, Julia Evans via GitGitGadget wrote:\n> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n> new file mode 100644\n> index 0000000000..612b683e40\n> --- /dev/null\n> +++ b/Documentation/gitmergeconflicts.adoc\n> @@ -0,0 +1,294 @@\n> +gitmergeconflicts(7)\n> +====================\n> +\n> +NAME\n> +----\n> +gitmergeconflicts - Guide to handling merge conflicts\n> +\n> +\n> +SYNOPSIS\n> +--------\n> +Guide to handling merge conflicts\n> +\n> +\n> +DESCRIPTION\n> +-----------\n> +\n> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n> +cherry-pick`, `git pull`, or `git revert`. All of those commands use\n\nShould all of these be using linkgit:, like for example in\nlinkgit:git-merge[1]?\n\n> +the same merge algorithm, and the process for resolving a merge conflict\n> +is always very similar.\n\nThere's also git-am(1), but only when adding the \"--3way\" flag. So maybe\nit's best to ignore that command indeed.\n\n> +The most common ways to handle a merge conflict are:\n> +\n> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n> +  below for details)\n> +* Or stop the operation and return your branch to its original state\n> +  with the appropriate `--abort` command, for example `git merge --abort`\n> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n> +  for how to find the command to run.\n\nI wonder whether the explanation should be expanded a bit to briefly\nexplain how Git performs a 3-way merge in the first place. I feel like\nit's quite important to understand what the three different sides of the\nmerge are to make sense of it.\n\nBut I may be too far detached from the \"normal\" user, so this may only\ncause more confusion for our users.\n\n> +[[markers]]\n> +MERGE CONFLICT MARKERS\n> +----------------------\n> +\n> +Merge conflicts happen when both of the sides being merged edit the same\n> +area of a file. When this happens, Git will update the conflicted file\n\nI wonder whether we want to use \"hunk\" instead of \"area\". It's jargon\nagain, but I have never heard anybody speak about an \"area\" before\nmyself.\n\n> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n> +For example, here's a merge conflict where both sides edited a list of\n> +fruits in different ways:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +=======\n> +    \"banana\",\n> +>>>>>>> add-fruit\n\nA bit of a tangent, but sometimes I wonder whether we should make the\nrespective commits a bit easier to access. For example, we could put the\nequivalent of `git rev-parse --reference <commit>` here for each of the\nsides.\n\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +The code from one side of the merge conflict is between `<<<<<<<` and\n> +`=======`, and the code for the other side is between `=======` and\n> +`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n> +of which side is which.\n> +\n> +\n> +[[resolve]]\n> +HOW TO RESOLVE A MERGE CONFLICT\n> +-------------------------------\n> +\n> +The process for resolving a merge conflict is:\n> +\n> +1. Run `git status` to get a list of files with merge conflicts\n> +2. For each one, find the conflict markers\n> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n> +   fix the conflict\n> +3. Run `git add FILENAME` for each file to mark the conflict as resolved\n> +4. Run the appropriate `--continue` command to continue the operation\n> +   that was interrupted by the conflict, for example `git merge --continue`\n> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n> +   below for how to find the command to run.\n> ++\n> +Note: During a `git merge`, `git commit` and `git merge --continue` do\n> +the the same thing.\n\ns/the the/the/\n\nMaybe we should also say \"During a conflicted `git merge`.\", but maybe\nthat's redundant.\n\n> +[[example]]\n> +EXAMPLE OF RESOLVING A MERGE CONFLICT\n> +-------------------------------------\n> +\n> +If you see this in your code during a merge conflict:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +    \"mango\",\n> +=======\n> +    \"banana\",\n> +    \"mango\",\n> +>>>>>>> add-fruit\n> +    \"orange\",\n> +]\n> +----\n> +\n> +Then you might edit that part of the code like this,\n> +which includes the fruits from both sides of the conflict:\n\nI tend to forget that by default, we only render ours/theirs in the\nconflict. I always feel like that makes it way harder to resolve\nconflicts as you don't have the context of what the code looked like\noriginally. So I have diff3 configured locally for ages.\n\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +    \"banana\",\n> +    \"cherry\",\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +\n> +[[tools]]\n> +TOOLS FOR HANDLING MERGE CONFLICTS\n> +----------------------------------\n> +\n> +Here are some ways to get extra context while handling a merge conflict:\n> +\n> +* There are many graphical \"merge tools\" for Git, which will normally\n> +  show you the different versions of the code side by side.\n> +  If you have a mergetool configured, `git mergetool` will launch it.\n> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n> +  the mergetools Git supports.\n\nThere's also `git merge-tool --tool-help` to list all available drivers.\n\n[snip]\n> +[[diff3]]\n> +DIFF3 AND ZDIFF3\n> +----------------\n> +\n> +By default, Git doesn't include the original code when formatting\n> +a merge conflict. To include the original code, you can set the\n> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n> +This extra context can make it much easier to understand what's\n> +happening in a merge conflict.\n\nIndeed.\n\n[snip]\n> +[[ours]]\n> +\"OURS\" AND \"THEIRS\"\n> +-------------------\n> +\n> +Git refers to the first part of a merge conflict (between `<<<<<<<`\n> +and `=======`) as \"ours\" and the second part (between `=======` and\n> +`>>>>>>>`) as \"theirs\".\n> +\n> +Normally, \"ours\" is the commit that was checked out before you started\n> +the merge, and \"theirs\" is the other commit.\n> +\n> +But when the merge conflict was caused by a `git rebase`, it's the\n> +opposite: \"theirs\" is the commit that was checked out before you started\n> +the merge. This is because under the hood, `git rebase main` checks out\n> +the `main` commit first before doing the merge operation.\n\nHmm. This part is a bit confusing to me. \"ours\" is always the commit\nthat's currently checked out, and \"theirs\" is always the one that is\ngetting merged into the checked-out commit.\n\nHow about a variant of the following instead?\n\n  In a conflict, the side between `<<<<<<<` and `=======` is \"ours\"\n  and the side between `=======` and `>>>>>>>` is \"theirs\". \"Ours\" is\n  always the side that `HEAD` points to while the merge happens; \"theirs\"\n  is the commit being merged into it.\n\n  For `git merge <other>`, `HEAD` is your current branch, so \"ours\" is\n  your branch and \"theirs\" is `<other>`.\n\n  For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and\n  your commits are then replayed on top one at a time. So \"ours\" is the\n  already-rebased history starting at `<upstream>`, and \"theirs\" is the\n  commit from your original branch that is currently being replayed.\n\n> +These terms in Git all mean the same thing when dealing with a merge\n> +conflict:\n> +\n> +* \"common ancestor\", \"base\", and \"stage 1\"\n> +* \"ours\", \"us\", \"stage 2\", and `HEAD`\n> +* \"theirs\", \"them\", and \"stage 3\"\n\nI wouldn't say that \"stage N\" is equivalent to the respective other\nterms. These stages rather refer to the different versions of a specific\nfile as recorded in the index, they do not indicate a specific commit.\nIn contrast to that, all the other terms may also indicate a specific\nversion of a file, but may also refer to the commits.\n\nPatrick\n"},{"id":"553696","messageId":"ar0MZkCygtK4Qa31@pks.im","threadId":"66387","inReplyTo":"a1686a2d82ef9357ecff07c1247092d3dd5ecf95.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-09-30T13:19:34Z","receivedAt":"2026-09-30T13:19:43Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Sep 24, 2026 at 02:44:17PM +0000, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans <julia@jvns.ca>\n> \n> All of the info about merge conflicts has been moved to the new guide\n\nPedantic nit: missing punctuation.\n\nOther than that I agree with Ben, one part that we lose here is some\ncontext on what a merge conflict even is.\n\nPatrick\n"},{"id":"553747","messageId":"5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com","threadId":"66387","inReplyTo":"ar0MVRV5X8zgZfLy@pks.im","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-30T19:53:17Z","receivedAt":"2026-09-30T19:53:38Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use\n>\n> Should all of these be using linkgit:, like for example in\n> linkgit:git-merge[1]?\n\nMakes sense to me, will change.\n\n>> +The most common ways to handle a merge conflict are:\n>> +\n>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n>> +  below for details)\n>> +* Or stop the operation and return your branch to its original state\n>> +  with the appropriate `--abort` command, for example `git merge --abort`\n>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n>> +  for how to find the command to run.\n>\n> I wonder whether the explanation should be expanded a bit to briefly\n> explain how Git performs a 3-way merge in the first place. I feel like\n> it's quite important to understand what the three different sides of the\n> merge are to make sense of it.\n>\n> But I may be too far detached from the \"normal\" user, so this may only\n> cause more confusion for our users.\n\nI think it would cause more confusion. I did some experiments in explaining\nmerge conflicts using the concept of 3-way merge a couple of years\nago and it didn't go well.\n\nMy experience was that what users they found the most useful was\nlearning about the tools Git offers (like `git diff --check` and `diff3`),\nso that's why this document focuses on tools and formatting much\nmore than concepts.\n\nI think it would be cool to find a way to explain how 3-way merge works at in\nthis document in some later iteration though, maybe at the end. Definitely some\nfolks would find it interesting. I didn't understand 3-way merge myself until a\ncouple of years ago and it was fun for me to learn, but it didn't really help me\nuse Git effectively.\n\n(this is quickly becoming a bit of a novel, but it's often very counterintuitive\nhow some facts that seem \"fundamental\" about how Git works actually turn\nout to not be very important to understand in practice to use it effectively.\nIt's something I find tough to talk about on this mailing list because it's something\nI've only been able to learn empirically)\n\n>> +[[markers]]\n>> +MERGE CONFLICT MARKERS\n>> +----------------------\n>> +\n>> +Merge conflicts happen when both of the sides being merged edit the same\n>> +area of a file. When this happens, Git will update the conflicted file\n>\n> I wonder whether we want to use \"hunk\" instead of \"area\". It's jargon\n> again, but I have never heard anybody speak about an \"area\" before\n> myself.\n\nAh thanks, I think I took \"area\" from the `git-merge` man page.\n\nI looked up how I explained this previously and I used \"lines of code\",\nwhich I think communicates the same meaning without the jargon.\nI'll try that instead.\n\n>> +Note: During a `git merge`, `git commit` and `git merge --continue` do\n>> +the the same thing.\n>\n> s/the the/the/\n\nWill fix. \n\n>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n>> +For example, here's a merge conflict where both sides edited a list of\n>> +fruits in different ways:\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",\n>> +=======\n>> +    \"banana\",\n>> +>>>>>>> add-fruit\n> Hide quoted text\n>\n> A bit of a tangent, but sometimes I wonder whether we should make the\n> respective commits a bit easier to access. For example, we could put the\n> equivalent of `git rev-parse --reference <commit>` here for each of the\n> sides.\n\nPersonally I'm not sure if the commit ID would do much for me, but I feel\nlike it would help me if it were possible to include the commit message. \n\n> I tend to forget that by default, we only render ours/theirs in the\n> conflict. I always feel like that makes it way harder to resolve\n> conflicts as you don't have the context of what the code looked like\n> originally. So I have diff3 configured locally for ages.\n\nEvery time I show people diff3 someone tells me how happy they\nare to learn it :)\n\n>> +* There are many graphical \"merge tools\" for Git, which will normally\n>> +  show you the different versions of the code side by side.\n>> +  If you have a mergetool configured, `git mergetool` will launch it.\n>> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n>> +  the mergetools Git supports.\n>\n> There's also `git merge-tool --tool-help` to list all available drivers.\n\nOh, cool! It's fun that it autodetects which ones you have installed\non your system. I'll suggest that.\n\n>\n> [snip]\n>> +[[ours]]\n>> +\"OURS\" AND \"THEIRS\"\n>> +-------------------\n>> +\n>> +Git refers to the first part of a merge conflict (between `<<<<<<<`\n>> +and `=======`) as \"ours\" and the second part (between `=======` and\n>> +`>>>>>>>`) as \"theirs\".\n>> +\n>> +Normally, \"ours\" is the commit that was checked out before you started\n>> +the merge, and \"theirs\" is the other commit.\n>> +\n>> +But when the merge conflict was caused by a `git rebase`, it's the\n>> +opposite: \"theirs\" is the commit that was checked out before you started\n>> +the merge. This is because under the hood, `git rebase main` checks out\n>> +the `main` commit first before doing the merge operation.\n>\n> Hmm. This part is a bit confusing to me. \"ours\" is always the commit\n> that's currently checked out, and \"theirs\" is always the one that is\n> getting merged into the checked-out commit.\n>\n> How about a variant of the following instead?\n>\n>   In a conflict, the side between `<<<<<<<` and `=======` is \"ours\"\n>   and the side between `=======` and `>>>>>>>` is \"theirs\". \"Ours\" is\n>   always the side that `HEAD` points to while the merge happens; \"theirs\"\n>   is the commit being merged into it.\n>\n>   For `git merge <other>`, `HEAD` is your current branch, so \"ours\" is\n>   your branch and \"theirs\" is `<other>`.\n>\n>   For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and\n>   your commits are then replayed on top one at a time. So \"ours\" is the\n>   already-rebased history starting at `<upstream>`, and \"theirs\" is the\n>   commit from your original branch that is currently being replayed.\n\nThanks, your suggestion gives me some other ways to think about this.\n\nI think I'll try to write something shorter that is unambiguous, instead of trying\nto use more words to make it feel more intuitive. I don't think I actually know\nanyone who feels it's easy to understand the way merge conflicts are\npresented, and more explanation may not help.\n\nIt might be more useful here to encourage (again) folks to use one of the many\namazing tools available (in the \"tools\" section) to get more context.\n\n>> +These terms in Git all mean the same thing when dealing with a merge\n>> +conflict:\n>> +\n>> +* \"common ancestor\", \"base\", and \"stage 1\"\n>> +* \"ours\", \"us\", \"stage 2\", and `HEAD`\n>> +* \"theirs\", \"them\", and \"stage 3\"\n>\n> I wouldn't say that \"stage N\" is equivalent to the respective other\n> terms. These stages rather refer to the different versions of a specific\n> file as recorded in the index, they do not indicate a specific commit.\n> In contrast to that, all the other terms may also indicate a specific\n> version of a file, but may also refer to the commits.\n\nThanks, will try to figure out how to make it more accurate.\nWe could also refer to gitdatamodel if folks want to learn what the\nterm \"stage\" means too.\n\nThanks for the review!\n- Julia\n"},{"id":"553755","messageId":"xmqqqzia8ohv.fsf@gitster.g","threadId":"66387","inReplyTo":"5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-30T20:37:16Z","receivedAt":"2026-09-30T20:37:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n>>> +For example, here's a merge conflict where both sides edited a list of\n>>> +fruits in different ways:\n>>> +\n>>> +----\n>>> +FRUITS = [\n>>> +    \"apple\",\n>>> +<<<<<<< HEAD\n>>> +    \"cherry\",\n>>> +=======\n>>> +    \"banana\",\n>>> +>>>>>>> add-fruit\n>> Hide quoted text\n>>\n>> A bit of a tangent, but sometimes I wonder whether we should make the\n>> respective commits a bit easier to access. For example, we could put the\n>> equivalent of `git rev-parse --reference <commit>` here for each of the\n>> sides.\n>\n> Personally I'm not sure if the commit ID would do much for me, but I feel\n> like it would help me if it were possible to include the commit message. \n\nIt would also help the resolution, not just committing after you are\ndone.  It may not matter while picking between cherry and banana to\nshow your personal preference on fruits, but in a more involved\nconflicted merge, it may help to be able to view \"git show $commit\",\n\"git diff ...$commit\", and \"git diff $commit...\" where $commit is\nthe \"add-fruit\" side of the merge to understand what they wanted to\ndo, and what we have done while they weren't looking.\n\n>> I tend to forget that by default, we only render ours/theirs in the\n>> conflict. I always feel like that makes it way harder to resolve\n>> conflicts as you don't have the context of what the code looked like\n>> originally. So I have diff3 configured locally for ages.\n>\n> Every time I show people diff3 someone tells me how happy they\n> are to learn it :)\n\nYes, we should encourage \"merge.conflictstyle=diff3\" (I feel about\nthis strongly enough to think it should become the default).\nKnowing what the original was before one side wanted to say \"cherry\"\nwhile the other side wanted to say \"banana\" sometimes helps a great\ndeal to decide what to do with the conflict.\n"},{"id":"553804","messageId":"ar3sGzEknG2_Un_E@pks.im","threadId":"66387","inReplyTo":"xmqqqzia8ohv.fsf@gitster.g","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-01T05:14:03Z","receivedAt":"2026-10-01T05:14:10Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n> \n> >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n> >>> +For example, here's a merge conflict where both sides edited a list of\n> >>> +fruits in different ways:\n> >>> +\n> >>> +----\n> >>> +FRUITS = [\n> >>> +    \"apple\",\n> >>> +<<<<<<< HEAD\n> >>> +    \"cherry\",\n> >>> +=======\n> >>> +    \"banana\",\n> >>> +>>>>>>> add-fruit\n> >> Hide quoted text\n> >>\n> >> A bit of a tangent, but sometimes I wonder whether we should make the\n> >> respective commits a bit easier to access. For example, we could put the\n> >> equivalent of `git rev-parse --reference <commit>` here for each of the\n> >> sides.\n> >\n> > Personally I'm not sure if the commit ID would do much for me, but I feel\n> > like it would help me if it were possible to include the commit message. \n> \n> It would also help the resolution, not just committing after you are\n> done.  It may not matter while picking between cherry and banana to\n> show your personal preference on fruits, but in a more involved\n> conflicted merge, it may help to be able to view \"git show $commit\",\n> \"git diff ...$commit\", and \"git diff $commit...\" where $commit is\n> the \"add-fruit\" side of the merge to understand what they wanted to\n> do, and what we have done while they weren't looking.\n\nYup. Doesn't mean we cannot _also_ include the names that we have above.\nSo in the above example it could be for example:\n\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)\n\nThat format would have a bunch of advantages:\n\n  - We don't have to teach users about special refs like MERGE_HEAD to\n    let them figure out how to access each of the commits.\n\n  - It gives a bit more context about what each specific side does, at\n    least if you have good commit messages.\n\n  - It also gives a sense of timing because we include dates, and that\n    may help in some situations to figure out what's what.\n\nI'll create an issue on the GitLab side and ask someone in the team to\nmaybe give this a try.\n\n> >> I tend to forget that by default, we only render ours/theirs in the\n> >> conflict. I always feel like that makes it way harder to resolve\n> >> conflicts as you don't have the context of what the code looked like\n> >> originally. So I have diff3 configured locally for ages.\n> >\n> > Every time I show people diff3 someone tells me how happy they\n> > are to learn it :)\n> \n> Yes, we should encourage \"merge.conflictstyle=diff3\" (I feel about\n> this strongly enough to think it should become the default).\n> Knowing what the original was before one side wanted to say \"cherry\"\n> while the other side wanted to say \"banana\" sometimes helps a great\n> deal to decide what to do with the conflict.\n\nI very much agree that it should be the default.\n\nPatrick\n"},{"id":"553833","messageId":"86a7df9d-362a-4530-82db-44ef7500fd10@app.fastmail.com","threadId":"66387","inReplyTo":"ar3sGzEknG2_Un_E@pks.im","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-01T12:10:11Z","receivedAt":"2026-10-01T12:10:37Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)\n> +    \"cherry\",\n> +=======\n> +    \"banana\",\n> +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)\n>\n> That format would have a bunch of advantages:\n>\n>   - We don't have to teach users about special refs like MERGE_HEAD to\n>     let them figure out how to access each of the commits.\n>\n>   - It gives a bit more context about what each specific side does, at\n>     least if you have good commit messages.\n>\n>   - It also gives a sense of timing because we include dates, and that\n>     may help in some situations to figure out what's what.\n\nThis is so cool, I love the idea of including the dates and the commit\nmessages!!! I think this would be very helpful for the reasons you say. \n\nThough re \"We don't have to teach users about special refs\nlike MERGE_HEAD\": I think that users today could run`git show HEAD`\nor `git show add-fruit` to see the commits on each side? I've never\nused MERGE_HEAD though so maybe I'm misunderstanding what\nit does. I think adding the commit ID makes it clearer too.\n\nI just ran downstairs to show my partner this example at 8am\nbecause I was so excited about it :) (he liked it too)\n"},{"id":"553985","messageId":"4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com","threadId":"66387","inReplyTo":"2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-02T17:01:20Z","receivedAt":"2026-10-02T17:01:41Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote:\n> On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:\n>> Hi Julia,\n>>\n>> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget\n>> <gitgitgadget@gmail.com> wrote:\n>>>\n>>> From: Julia Evans <julia@jvns.ca>\n>>>\n>>> All of the info about merge conflicts has been moved to the new guide\n>>\n>>> Among the changes made to the common ancestor's version,\n>>> -non-overlapping ones (that is, you changed an area of the file while the\n>>> -other side left that area intact, or vice versa) are incorporated in the\n>>> -final result verbatim.  When both sides made changes to the same area,\n>>> -however, Git cannot randomly pick one side over the other, and asks you to\n>>> -resolve it by leaving what both sides did to that area.\n\n>> I think these are both valuable pieces of information we have lost in\n>> the new guide (unless I misremember just having read patch 1 :).\n>>\n>> The first explains a bit more about what a conflict *is*. Maybe that's\n>> old-hat nowadays, but I think it could be nice to keep a statement\n>> about why conflicts exist.\n>\n> Will think about this!\n\nAfter talking this through with my collaborator Marie, we wrote a new\n\"what is a merge conflict?\" section which I'll include in the v2.\n\nLike I mentioned before elsewhere it takes a super light approach to\nintroducing the 3-way merge. (there is intentionally no mention\nof \"since they diverged from the common ancestor\" etc)\n\n    WHAT IS A MERGE CONFLICT?\n    -------------------------\n\n    When Git merges two commits together, it looks at the changes that\n    each side has made and combines those changes. For example, if one side\n    edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n    `hello.py`, then it can easily combine them.\n\n    But if both sides edited overlapping lines of the same file (for example\n    one side edited lines 1-5 and the other edited lines 3-6), Git will\n    not try to guess how to combine those changes. This is called a \"merge\n    conflict\".\n\n    When this happens, Git shows you both sides' edits and asks you to pick\n    how to resolve them. It:\n\n    * Stages all of the files which were successfully merged\n    * For the files with conflicts, it leaves them unstaged, puts both\n      sides' edits in the file, and leaves <<markers, merge conflict markers>>\n      that you need to resolve.\n"},{"id":"553990","messageId":"91396552-f86b-47d7-9805-8f6056c2ed66@app.fastmail.com","threadId":"66387","inReplyTo":"CALnO6CA_=OsznkQ4iT0vBMWf3L=bmVKMBdk1MTHQdaKEcKwn4g@mail.gmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-02T17:39:44Z","receivedAt":"2026-10-02T17:40:08Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks for the review!\n\n>>  * I wrote that git commit does the same thing as git merge --continue\n>>    during a git merge , but I'm not sure if that's always true.\n>\n> See also discussion in\n> https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t\n\nWow, that's a very interesting read. I'm more informed than I was before\nI read it but also at the same time more confused :). It makes me think\nthat \"git commit does the same thing as git merge --continue\" is maybe\nnot true but also I don't know what the difference might be.\n\nI've put an item on my TODO list to remove \n`git commit does the same thing as git merge --continue`\" and to try to\nreplace it with a more vague sentence that I guess says you can use\neither command without being so specific on whether they are exactly\nthe same.\n\n>> Also if/when the git rebase --squash changes land, then we'd need\n>>    to add git history to this list.\n>\n> I imagine you meant history squash? I also thought that history had\n> punted on how to deal with conflicts (rejecting any operation which\n> creates them) for now, since we don't have 1st-class conflicts à la\n> Jujutsu.\n\nGood to know! Removed this from my v2 cover letter draft.\n"},{"id":"553993","messageId":"xmqqh5j4vvor.fsf@gitster.g","threadId":"66387","inReplyTo":"4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-02T17:50:12Z","receivedAt":"2026-10-02T17:50:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Like I mentioned before elsewhere it takes a super light approach to\n> introducing the 3-way merge. (there is intentionally no mention\n> of \"since they diverged from the common ancestor\" etc)\n>\n>     WHAT IS A MERGE CONFLICT?\n>     -------------------------\n>\n>     When Git merges two commits together, it looks at the changes that\n>     each side has made and combines those changes. For example, if one side\n>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n>     `hello.py`, then it can easily combine them.\n\nSome immediate reactions.\n\n - Is it obvious that the reason why it can \"easily combine\" them,\n   or would it help to be more explicit (i.e., \"as there is no\n   overlap\")?\n\n - The second \"of `hello.py`\" forced me to go back and look at the\n   first one again to make sure we are talking about the same file.\n   I would imagine if the latter were \"lines 20-25 of the same file\",\n   it would have read better at least to me.\n\n>     But if both sides edited overlapping lines of the same file (for example\n>     one side edited lines 1-5 and the other edited lines 3-6), Git will\n>     not try to guess how to combine those changes. This is called a \"merge\n>     conflict\".\n\n - \"cannot guess\" would be more direct than \"will not try to guess\".\n\n>     When this happens, Git shows you both sides' edits and asks you to pick\n>     how to resolve them. It:\n>\n>     * Stages all of the files which were successfully merged\n\n - \"merged without conflicts\" would be more direct than \"successfully merged\".\n\n>     * For the files with conflicts, it leaves them unstaged, puts both\n>       sides' edits in the file, and leaves <<markers, merge conflict markers>>\n>       that you need to resolve.\n\n - \"unstaged\" sounds as if somebody ran \"git rm --cached\" on the\n   paths, but that is not what you want to tell your readers.\n\n - \"it leaves them unstaged\" -> \"it remembers them as conflicted\",\n   perhaps?  This hints that Git has a mechanism to remember the\n   conflicted paths even after you removed the conflict markers from\n   the file to your readers.\n\n\n"},{"id":"553994","messageId":"xmqqbj9cvvaa.fsf@gitster.g","threadId":"66387","inReplyTo":"xmqqqzia8ohv.fsf@gitster.g","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-02T17:58:53Z","receivedAt":"2026-10-02T17:58:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n>>>> +FRUITS = [\n>>>> +    \"apple\",\n>>>> +<<<<<<< HEAD\n>>>> +    \"cherry\",\n>>>> +=======\n>>>> +    \"banana\",\n>>>> +>>>>>>> add-fruit\n>\n>> Every time I show people diff3 someone tells me how happy they\n>> are to learn it :)\n>\n> Yes, we should encourage \"merge.conflictstyle=diff3\" (I feel about\n> this strongly enough to think it should become the default).\n> Knowing what the original was before one side wanted to say \"cherry\"\n> while the other side wanted to say \"banana\" sometimes helps a great\n> deal to decide what to do with the conflict.\n\nBefore I forget, here is a good illustration to tell why diff3 style\nis often essential to correct conflict resolution that we can tell\nnew users.  You may want to throw it in to your new manual pages.\n\nIf the conflict looks like this\n\n        FRUITS = [       \n            \"apple\",     \n        <<<<<<< HEAD     \n            \"cherry\",    \n\t|||||||\n        =======          \n            \"banana\",    \n        >>>>>>> add-fruit\n\nthen we can tell that in the beginning there was only 'apple', and\none side wanted to add 'cherry', while the other side wanted to add\n'banana'.  It is likely that we would make both sides happy by\nadding both of them.\n\nBut on the other hand, if the conflict looks like this\n\n        FRUITS = [       \n            \"apple\",     \n        <<<<<<< HEAD     \n            \"cherry\",    \n\t|||||||\n\t    \"banana\",\n\t    \"cherry\",\n        =======          \n            \"banana\",    \n        >>>>>>> add-fruit\n\nwe can tell that before two sides started editing, we had 'apple',\n'banana', and 'cherry'.  While both wanted to keep 'apple', one side\ndid not want 'banana', and the other side did not want 'cherry'.  It\nis plausible that we can please both of them by removing these two.\n\nWith just two-sides, the user who is trying to resolve the conflict\ncannot tell the difference.\n"},{"id":"553999","messageId":"7861e492-6fa4-4768-afdd-65cd346b85be@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqh5j4vvor.fsf@gitster.g","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-02T18:53:19Z","receivedAt":"2026-10-02T18:53:40Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">>     WHAT IS A MERGE CONFLICT?\n>>     -------------------------\n>>\n>>     When Git merges two commits together, it looks at the changes that\n>>     each side has made and combines those changes. For example, if one side\n>>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n>>     `hello.py`, then it can easily combine them.\n>\n> Some immediate reactions.\n\nThanks, incorporated a few of these (\"it marks them as conflicted\",\n\"since there's no overlap\", \"the same file\")\n\n>>     But if both sides edited overlapping lines of the same file (for example\n>>     one side edited lines 1-5 and the other edited lines 3-6), Git will\n>>     not try to guess how to combine those changes. This is called a \"merge\n>>     conflict\".\n>\n>  - \"cannot guess\" would be more direct than \"will not try to guess\".\n\nThe way I think about it as a user is that Git takes an intentionally conservative\napproach and I appreciate the conservatism. Compared to a more aggressive\nsyntax-aware merge system like `mergiraf` which has done merges I don't\nagree with.\n"},{"id":"554013","messageId":"xmqqjynzvl4w.fsf@gitster.g","threadId":"66387","inReplyTo":"7861e492-6fa4-4768-afdd-65cd346b85be@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-02T21:38:07Z","receivedAt":"2026-10-02T21:38:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>>  - \"cannot guess\" would be more direct than \"will not try to guess\".\n>\n> The way I think about it as a user is that Git takes an intentionally conservative\n> approach and I appreciate the conservatism. Compared to a more aggressive\n> syntax-aware merge system like `mergiraf` which has done merges I don't\n> agree with.\n\nYour disagreement with their result suggests that they guessed when\nthey could not do so reliably.  I agree that our approach is more\nconservative, but we can call it being more honest.\n\n;-).\n"},{"id":"554040","messageId":"CALnO6CDoMTtyPJyOiXVPSZvFGHgGkFT-u_Qk1km+XYn9BR0OHg@mail.gmail.com","threadId":"66387","inReplyTo":"4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-03T02:25:13Z","receivedAt":"2026-10-03T02:25:25Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Fri, Oct 2, 2026 at 1:01 PM Julia Evans <julia@jvns.ca> wrote:\n>\n>\n>\n> On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote:\n> > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:\n> >> Hi Julia,\n> >>\n> >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget\n> >> <gitgitgadget@gmail.com> wrote:\n> >>>\n> >>> From: Julia Evans <julia@jvns.ca>\n> >>>\n> >>> All of the info about merge conflicts has been moved to the new guide\n> >>\n> >>> Among the changes made to the common ancestor's version,\n> >>> -non-overlapping ones (that is, you changed an area of the file while the\n> >>> -other side left that area intact, or vice versa) are incorporated in the\n> >>> -final result verbatim.  When both sides made changes to the same area,\n> >>> -however, Git cannot randomly pick one side over the other, and asks you to\n> >>> -resolve it by leaving what both sides did to that area.\n>\n> >> I think these are both valuable pieces of information we have lost in\n> >> the new guide (unless I misremember just having read patch 1 :).\n> >>\n> >> The first explains a bit more about what a conflict *is*. Maybe that's\n> >> old-hat nowadays, but I think it could be nice to keep a statement\n> >> about why conflicts exist.\n> >\n> > Will think about this!\n>\n> After talking this through with my collaborator Marie, we wrote a new\n> \"what is a merge conflict?\" section which I'll include in the v2.\n>\n> Like I mentioned before elsewhere it takes a super light approach to\n> introducing the 3-way merge. (there is intentionally no mention\n> of \"since they diverged from the common ancestor\" etc)\n>\n>     WHAT IS A MERGE CONFLICT?\n>     -------------------------\n>\n>     When Git merges two commits together, it looks at the changes that\n>     each side has made and combines those changes. For example, if one side\n>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n>     `hello.py`, then it can easily combine them.\n>\n>     But if both sides edited overlapping lines of the same file (for example\n>     one side edited lines 1-5 and the other edited lines 3-6), Git will\n>     not try to guess how to combine those changes. This is called a \"merge\n>     conflict\".\n>\n>     When this happens, Git shows you both sides' edits and asks you to pick\n>     how to resolve them. It:\n>\n>     * Stages all of the files which were successfully merged\n>     * For the files with conflicts, it leaves them unstaged, puts both\n>       sides' edits in the file, and leaves <<markers, merge conflict markers>>\n>       that you need to resolve.\n>\n\nI quite like this. I'm sure it oversimplifies somewhere, but at least\nI personally cannot immediately see where (or how it does any harm to)\n;)\n\nThanks!\n\nPS Unlike Junio---perhaps due to my lack of older Git history and\nterminology, despite using Git since 2016?---I would never have read\n\"unstaged\" as *deleted* from the index. Just changed and not updated\nin the index (i.e., not \"git add\"-ed).\n\n-- \nD. Ben Knoble\n"},{"id":"554041","messageId":"CALnO6CC+h1y=Fu438nm4cd0K-dfPVYq9MqX_+k8fxBU60ot8KA@mail.gmail.com","threadId":"66387","inReplyTo":"91396552-f86b-47d7-9805-8f6056c2ed66@app.fastmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-03T02:29:05Z","receivedAt":"2026-10-03T02:29:17Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Fri, Oct 2, 2026 at 1:40 PM Julia Evans <julia@jvns.ca> wrote:\n>\n> Thanks for the review!\n>\n> >>  * I wrote that git commit does the same thing as git merge --continue\n> >>    during a git merge , but I'm not sure if that's always true.\n> >\n> > See also discussion in\n> > https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t\n>\n> Wow, that's a very interesting read. I'm more informed than I was before\n> I read it but also at the same time more confused :). It makes me think\n> that \"git commit does the same thing as git merge --continue\" is maybe\n> not true but also I don't know what the difference might be.\n>\n> I've put an item on my TODO list to remove\n> `git commit does the same thing as git merge --continue`\" and to try to\n> replace it with a more vague sentence that I guess says you can use\n> either command without being so specific on whether they are exactly\n> the same.\n\nFor now I would say the subtleties in that conversation really make me\nlean towards the following:\n\n- \"git <thing> --continue\" is, for most users in most cases, the right\nthing to do. It's what \"git status\" recommends and will practically\nnever do anything surprising (?).\n- However, it may not always be exactly what you *want*---and you'll\nusually know when you want to go \"outside\" the normal sequencer and\ncommit directly (because you'll have understood some nuanced details\nabout what can happen).\n\nFor merge it may be the case that they're the same, I suppose (I'm\ngenuinely not sure), but I would prefer to simplify folks' paths by\nrecommending one of the few uniform interfaces we have :)\n"},{"id":"554042","messageId":"xmqqik3jtob2.fsf@gitster.g","threadId":"66387","inReplyTo":"CALnO6CDoMTtyPJyOiXVPSZvFGHgGkFT-u_Qk1km+XYn9BR0OHg@mail.gmail.com","subject":"Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-03T04:12:33Z","receivedAt":"2026-10-03T04:12:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" <ben.knoble@gmail.com> writes:\n\n> PS Unlike Junio---perhaps due to my lack of older Git history and\n> terminology, despite using Git since 2016?---I would never have read\n> \"unstaged\" as *deleted* from the index. Just changed and not updated\n> in the index (i.e., not \"git add\"-ed).\n\nI agree such an interpretation is certainly possible.\n\nThe verb \"to unstage\" would be the opposite of \"to stage\", but it is\nambiguous what kind of oppositeness you want to express.  This is\nunlike \"to stage\" whose possible interpretation is fairly narrow.\nYou register the contents that you consider desirable for the path\nusing various means.  On the other hand, \"to unstage\" is undoing the\nresult of your earlier act \"to stage\", but it may mean reverting to\nwhat is recorded in HEAD (i.e., \"git reset HEAD -- path\"), undoing\nthe fact that you added a path to the index (i.e., \"git rm --cached\n-- path\").  Neither interpretation is what you want when talking\nabout what a conflicted merge does to remember the three stages for\na conflicted path in the index.\n\nHence my suggestion to avoid using the verb.\n\n"},{"id":"554202","messageId":"e593f3ca-4a03-45a7-b0cc-6295a3a4939f@app.fastmail.com","threadId":"66387","inReplyTo":"5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-05T16:54:03Z","receivedAt":"2026-10-05T16:54:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n>> [snip]\n>>> +[[ours]]\n>>> +\"OURS\" AND \"THEIRS\"\n>>> +-------------------\n>>> +\n>>> +Git refers to the first part of a merge conflict (between `<<<<<<<`\n>>> +and `=======`) as \"ours\" and the second part (between `=======` and\n>>> +`>>>>>>>`) as \"theirs\".\n>>> +\n>>> +Normally, \"ours\" is the commit that was checked out before you started\n>>> +the merge, and \"theirs\" is the other commit.\n>>> +\n>>> +But when the merge conflict was caused by a `git rebase`, it's the\n>>> +opposite: \"theirs\" is the commit that was checked out before you started\n>>> +the merge. This is because under the hood, `git rebase main` checks out\n>>> +the `main` commit first before doing the merge operation.\n>>\n>> Hmm. This part is a bit confusing to me. \"ours\" is always the commit\n>> that's currently checked out, and \"theirs\" is always the one that is\n>> getting merged into the checked-out commit.\n>>\n>> How about a variant of the following instead?\n>>\n>>   In a conflict, the side between `<<<<<<<` and `=======` is \"ours\"\n>>   and the side between `=======` and `>>>>>>>` is \"theirs\". \"Ours\" is\n>>   always the side that `HEAD` points to while the merge happens; \"theirs\"\n>>   is the commit being merged into it.\n>>\n>>   For `git merge <other>`, `HEAD` is your current branch, so \"ours\" is\n>>   your branch and \"theirs\" is `<other>`.\n>>\n>>   For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and\n>>   your commits are then replayed on top one at a time. So \"ours\" is the\n>>   already-rebased history starting at `<upstream>`, and \"theirs\" is the\n>>   commit from your original branch that is currently being replayed.\n>\n> Thanks, your suggestion gives me some other ways to think about this.\n>\n> I think I'll try to write something shorter that is unambiguous, \n> instead of trying\n> to use more words to make it feel more intuitive. I don't think I \n> actually know\n> anyone who feels it's easy to understand the way merge conflicts are\n> presented, and more explanation may not help.\n>\n> It might be more useful here to encourage (again) folks to use one of the many\n> amazing tools available (in the \"tools\" section) to get more context.\n>\n>>> +These terms in Git all mean the same thing when dealing with a merge\n>>> +conflict:\n>>> +\n>>> +* \"common ancestor\", \"base\", and \"stage 1\"\n>>> +* \"ours\", \"us\", \"stage 2\", and `HEAD`\n>>> +* \"theirs\", \"them\", and \"stage 3\"\n>>\n>> I wouldn't say that \"stage N\" is equivalent to the respective other\n>> terms. These stages rather refer to the different versions of a specific\n>> file as recorded in the index, they do not indicate a specific commit.\n>> In contrast to that, all the other terms may also indicate a specific\n>> version of a file, but may also refer to the commits.\n>\n> Thanks, will try to figure out how to make it more accurate.\n> We could also refer to gitdatamodel if folks want to learn what the\n> term \"stage\" means too.\n\nMarie and I worked on the OURS AND THEIRS section today and I think it's clearer\nnow but also longer (instead of shorter which was my dream). We added an attempt\nat humor at the end to hopefully help things a bit.\n\n\t\"OURS\" AND \"THEIRS\"\n\t-------------------\n\n\tSometimes during a merge conflict, Git will use the terms \"ours\" and\n\t\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n\ta file was `deleted by us`.\n\n\t\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n\t`HEAD` commit, and \"theirs\" is the other side being merged.\n\n\tThe first part of a merge conflict (between `<<<<<<<` and `=======`) is\n\tfrom the \"ours\" side, and the second part (between `=======` and\n\t`>>>>>>>`) is from the \"theirs\" side.\n\n\t----\n\tFRUITS = [\n\t    \"apple\",\n\t<<<<<<< HEAD\n\t    \"cherry\",                      <- ours\n\t=======\n\t    \"banana\",                      <- theirs\n\t>>>>>>> add-fruit\n\t    \"mango\",\n\t    \"orange\",\n\t]\n\t----\n\n\tDuring a rebase, it can seem \"upside down\" because the \"ours\" commit is\n\tfrom the branch you're rebasing on (for instance `main` in `git rebase\n\tmain`).\n\n\tThese terms in Git all mean the same thing when dealing with a merge\n\tconflict:\n\n\t* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n\t* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n\t* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n\n\tIf you're confused about what something like \"deleted by us\" means, it's\n\toften easiest to use some of the tools from\n\t<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n\tFinding the commit that deleted the file and seeing why is usually more\n\thelpful than trying to abstractly reason through what \"us\" means.\n\n"},{"id":"554203","messageId":"xmqqik3gjc5j.fsf@gitster.g","threadId":"66387","inReplyTo":"e593f3ca-4a03-45a7-b0cc-6295a3a4939f@app.fastmail.com","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-05T17:22:00Z","receivedAt":"2026-10-05T17:22:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Marie and I worked on the OURS AND THEIRS section today and I think it's clearer\n> now but also longer (instead of shorter which was my dream). We added an attempt\n> at humor at the end to hopefully help things a bit.\n>\n> \t\"OURS\" AND \"THEIRS\"\n> \t-------------------\n>\n> \tSometimes during a merge conflict, Git will use the terms \"ours\" and\n> \t\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n> \ta file was `deleted by us`.\n>\n> \t\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n> \t`HEAD` commit, and \"theirs\" is the other side being merged.\n>\n> \tThe first part of a merge conflict (between `<<<<<<<` and `=======`) is\n> \tfrom the \"ours\" side, and the second part (between `=======` and\n> \t`>>>>>>>`) is from the \"theirs\" side.\n>\n> \t----\n> \tFRUITS = [\n> \t    \"apple\",\n> \t<<<<<<< HEAD\n> \t    \"cherry\",                      <- ours\n> \t=======\n> \t    \"banana\",                      <- theirs\n> \t>>>>>>> add-fruit\n> \t    \"mango\",\n> \t    \"orange\",\n> \t]\n> \t----\n>\n> \tDuring a rebase, it can seem \"upside down\" because the \"ours\" commit is\n> \tfrom the branch you're rebasing on (for instance `main` in `git rebase\n> \tmain`).\n>\n> \tThese terms in Git all mean the same thing when dealing with a merge\n> \tconflict:\n>\n> \t* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n> \t* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n> \t* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n>\n> \tIf you're confused about what something like \"deleted by us\" means, it's\n> \toften easiest to use some of the tools from\n> \t<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n> \tFinding the commit that deleted the file and seeing why is usually more\n> \thelpful than trying to abstractly reason through what \"us\" means.\n\nMay I ask what is in scope for this effort?\n\nWe previously discussed updating the conflict markers (the 'HEAD'\nand 'add-fruit' labels in the example above).  Doing so would\nrequire code changes, which goes beyond mere documentation updates.\nBut if a minor code change like that makes the documentation much\neasier to understand, I think we should consider doing so.\n\nAlong the same line, if git status stopped saying \"deleted by us\"\nand instead used a different phrase, would that help reduce the\n\"upside down\" confusion [*]?  Is it acceptable to bend the code\na little if it helps the documentation?\n\n\n[Footnote]\n\n * I suspect that the \"upside down\" feeling is not really about the\n   terms \"ours\" and \"theirs\" themselves.  Rather, it comes from how\n   one conceptualizes what 'rebase' does compared to 'merge'.\n   During a rebase, we temporarily pretend that we are working on\n   the upstream branch and replay our local changes on top of it.\n   Once the user adopts this mindset, displaying the upstream state\n   first (the point from which we start building the consolidated\n   history) followed by the local state (what was done differently\n   by the local side) becomes consistent with how 'merge' displays\n   conflicts (where we start from our local state and merge the\n   incoming changes).\n\n"},{"id":"554211","messageId":"623cdf71-8076-4967-aff1-3ebeb57d1e3a@app.fastmail.com","threadId":"66387","inReplyTo":"CALnO6CC+h1y=Fu438nm4cd0K-dfPVYq9MqX_+k8fxBU60ot8KA@mail.gmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-05T18:49:56Z","receivedAt":"2026-10-05T18:49:56Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Oct 2, 2026, at 10:29 PM, D. Ben Knoble wrote:\n> On Fri, Oct 2, 2026 at 1:40 PM Julia Evans <julia@jvns.ca> wrote:\n>>\n>> Thanks for the review!\n>>\n>> >>  * I wrote that git commit does the same thing as git merge --continue\n>> >>    during a git merge , but I'm not sure if that's always true.\n>> >\n>> > See also discussion in\n>> > https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t\n>>\n>> Wow, that's a very interesting read. I'm more informed than I was before\n>> I read it but also at the same time more confused :). It makes me think\n>> that \"git commit does the same thing as git merge --continue\" is maybe\n>> not true but also I don't know what the difference might be.\n>>\n>> I've put an item on my TODO list to remove\n>> `git commit does the same thing as git merge --continue`\" and to try to\n>> replace it with a more vague sentence that I guess says you can use\n>> either command without being so specific on whether they are exactly\n>> the same.\n>\n> For now I would say the subtleties in that conversation really make me\n> lean towards the following:\n>\n> - \"git <thing> --continue\" is, for most users in most cases, the right\n> thing to do. It's what \"git status\" recommends and will practically\n> never do anything surprising (?).\n\nI was actually surprised to discover that `git status` does not recommend\n`git merge --continue`: it recommends `git commit`.\nMaybe we should change that though?\n\nI agree it makes sense to be consistent with what `git status` recommends.\n\n> - However, it may not always be exactly what you *want*---and you'll\n> usually know when you want to go \"outside\" the normal sequencer and\n> commit directly (because you'll have understood some nuanced details\n> about what can happen).\n>\n> For merge it may be the case that they're the same, I suppose (I'm\n> genuinely not sure), but I would prefer to simplify folks' paths by\n> recommending one of the few uniform interfaces we have :)\n\nThe only other thing that gives me pause about recommending folks\n`git merge --continue` too strongly is that as we know Git users are slow to\nchange their habits, and we don't want to confuse anyone. If someone is\ncurrently using `git commit` I want to know that they can keep doing\nit the same way with no worries.\n\nMaybe if we change `git status` to recommend `git merge --continue`,\nand we think there are no real advantages to using `git commit` instead\nof `git merge --continue`, then we could say something like this:\n\n  NOTE: `git commit` is an older alternative to `git merge --continue`.\n  You can use either one after resolving a `git merge`.\n\n"},{"id":"554213","messageId":"e2ef9cf9-a87b-4374-bedd-8f7ab1114961@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqik3gjc5j.fsf@gitster.g","subject":"Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-05T19:11:21Z","receivedAt":"2026-10-05T19:11:21Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":">> \tDuring a rebase, it can seem \"upside down\" because the \"ours\" commit is\n>> \tfrom the branch you're rebasing on (for instance `main` in `git rebase\n>> \tmain`).\n>>\n>> \tThese terms in Git all mean the same thing when dealing with a merge\n>> \tconflict:\n>>\n>> \t* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n>> \t* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n>> \t* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n>>\n>> \tIf you're confused about what something like \"deleted by us\" means, it's\n>> \toften easiest to use some of the tools from\n>> \t<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n>> \tFinding the commit that deleted the file and seeing why is usually more\n>> \thelpful than trying to abstractly reason through what \"us\" means.\n>\n> May I ask what is in scope for this effort?\n>\n> We previously discussed updating the conflict markers (the 'HEAD'\n> and 'add-fruit' labels in the example above).  Doing so would\n> require code changes, which goes beyond mere documentation updates.\n> But if a minor code change like that makes the documentation much\n> easier to understand, I think we should consider doing so.\n>\n> Along the same line, if git status stopped saying \"deleted by us\"\n> and instead used a different phrase, would that help reduce the\n> \"upside down\" confusion [*]?  Is it acceptable to bend the code\n> a little if it helps the documentation?\n\nI agree that would make sense. I have some changes to advice\n(on other areas) in local branches on my machine already :)\n\nI think of it as sort of \"documentation driven development\" (write the\ndocumentation, and if it feels upsetting what the documentation is\nsaying, then try to change the code so we're happier with the docs!)\n\nI don't have a clear idea for how to improve the way `git status`\npresents merge conflicts to make it less confusing right now though.\n\nBrainstorming a bit, here's some commentary on this `git status` output:\n\n\tOn branch main\n\tYour branch and 'origin/main' have diverged,\n\tand have 2 and 1 different commits each, respectively.\n\t  (use \"git pull\" if you want to integrate the remote branch with yours)\n\n\tYou have unmerged paths.\n\t  (fix conflicts and run \"git commit\")\n\t  (use \"git merge --abort\" to abort the merge)\n\n\tUnmerged paths:\n\t  (use \"git add <file>...\" to mark resolution)\n\t        both modified:   fruits.py\n\n\tno changes added to commit (use \"git add\" and/or \"git commit -a\")\n\n1.  `(use \"git pull\" if you want to integrate the remote branch with yours)`\n   is not helpful advice here, it's not even allowed to run `git pull`\n   in the middle of a merge conflict.\n2. `git add` is sort of not helpful here, all of the unmerged files currently\n  have conflict markers, so the next step is definitely not to run `git add`,\n  it's to edit one of the unmerged files. But perhaps it's unrealistic to\n  be running the equivalent of `git diff --check` in `git status` just to\n  help users out.\n3. Not sure if \"unmerged\" is the best term here, maybe \"conflicted\"?\n4. It gives the advice to use `git add` twice which is weird. \n5. One part of the advice refers to the process of fixing conflicts as\n  \"fix conflicts\" but the other part calls it \"mark resolution\". Should\n  probably be consistent there.\n\nBut as you can see those comments are all over the place, some of them\nare just wording changes, some of them would involve adding a bunch of\nconditional logic to the advice system that might not be realistic,\nI don't know.\n\n> [Footnote]\n>\n>  * I suspect that the \"upside down\" feeling is not really about the\n>    terms \"ours\" and \"theirs\" themselves.  Rather, it comes from how\n>    one conceptualizes what 'rebase' does compared to 'merge'.\n>    During a rebase, we temporarily pretend that we are working on\n>    the upstream branch and replay our local changes on top of it.\n>    Once the user adopts this mindset, displaying the upstream state\n>    first (the point from which we start building the consolidated\n>    history) followed by the local state (what was done differently\n>    by the local side) becomes consistent with how 'merge' displays\n>    conflicts (where we start from our local state and merge the\n>    incoming changes).\n\nI will say that I know all of these facts but it has never helped\nme to remember \"ours\" and \"theirs\" :). I'm pretty resistant in general\nto telling people they need to adopt the \"right mindset\", IMO\nit's normal for people to have different points of view.\n\nWhen explaining Git I heard a lot of \"yes I know all that but I just\ndon't like to think about it that way\" and it really helped me\nto learn to respect when folks said that and try to see it from\ntheir point of view.\n\n"},{"id":"554305","messageId":"CALnO6CAG-z8B2zXj+QEvZNb-Ufiq=qgyPR5VvQShyH1H_+bgNA@mail.gmail.com","threadId":"66387","inReplyTo":"623cdf71-8076-4967-aff1-3ebeb57d1e3a@app.fastmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-06T16:53:26Z","receivedAt":"2026-10-06T16:53:26Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Oct 5, 2026 at 2:50 PM Julia Evans <julia@jvns.ca> wrote:\n> >\n> > For now I would say the subtleties in that conversation really make me\n> > lean towards the following:\n> >\n> > - \"git <thing> --continue\" is, for most users in most cases, the right\n> > thing to do. It's what \"git status\" recommends and will practically\n> > never do anything surprising (?).\n>\n> I was actually surprised to discover that `git status` does not recommend\n> `git merge --continue`: it recommends `git commit`.\n\nWow, yeah! I'm surprised, too. (See\nwt-status.c:show_merge_in_progress(), and compare with other related\nfunctions.)\n\n> Maybe we should change that though?\n\nI think so, at least.\n\n> I agree it makes sense to be consistent with what `git status` recommends.\n\nFor sure.\n\n> > - However, it may not always be exactly what you *want*---and you'll\n> > usually know when you want to go \"outside\" the normal sequencer and\n> > commit directly (because you'll have understood some nuanced details\n> > about what can happen).\n> >\n> > For merge it may be the case that they're the same, I suppose (I'm\n> > genuinely not sure), but I would prefer to simplify folks' paths by\n> > recommending one of the few uniform interfaces we have :)\n>\n> The only other thing that gives me pause about recommending folks\n> `git merge --continue` too strongly is that as we know Git users are slow to\n> change their habits, and we don't want to confuse anyone. If someone is\n> currently using `git commit` I want to know that they can keep doing\n> it the same way with no worries.\n>\n> Maybe if we change `git status` to recommend `git merge --continue`,\n> and we think there are no real advantages to using `git commit` instead\n> of `git merge --continue`, then we could say something like this:\n>\n>   NOTE: `git commit` is an older alternative to `git merge --continue`.\n>   You can use either one after resolving a `git merge`.\n\nThat sounds like a reasonable plan. Another plan that occurs to me is\nto go forward with the \"commit\" version (for merges; other commands\nshould use the sequencer versions that status recommends) and update\nthis doc later if we do change status to recommend \"merge --continue\".\n\nI'd love to hear from others on either changing status output to\nrecommend \"merge --continue\" or admitting that, for merges, \"commit\"\nis the same thing.\n\n-- \nD. Ben Knoble\n\n"},{"id":"554307","messageId":"CALnO6CBBL6f-HTVtHOf2TrgYV3SCTLU3Jw8amJ6MTM+DHQ+5TQ@mail.gmail.com","threadId":"66387","inReplyTo":"CALnO6CAG-z8B2zXj+QEvZNb-Ufiq=qgyPR5VvQShyH1H_+bgNA@mail.gmail.com","subject":"Re: [PATCH 0/7] [doc] Add new page on merge conflicts","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-06T17:09:59Z","receivedAt":"2026-10-06T17:09:59Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Oct 6, 2026 at 12:53 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:\n>\n> I'd love to hear from others on either changing status output to\n> recommend \"merge --continue\" or admitting that, for merges, \"commit\"\n> is the same thing.\n\nI see now there's a patch in-flight (downside of reading mail oldest\nto newest). I'll expect to discuss this particular point there,\nthanks!\n\n-- \nD. Ben Knoble\n\n"},{"id":"554423","messageId":"xmqqse2h5hql.fsf@gitster.g","threadId":"66387","inReplyTo":"4505fdc9a6dec37296952107c90947e43f39bae4.1790261062.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T21:21:54Z","receivedAt":"2026-10-07T21:21:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc\n> From: Julia Evans <julia@jvns.ca>\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  .gitattributes | 1 +\n>  1 file changed, 1 insertion(+)\n>\n> diff --git a/.gitattributes b/.gitattributes\n> index 26490ad60a..0a0fc950b1 100644\n> --- a/.gitattributes\n> +++ b/.gitattributes\n> @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n>  /t/oid-info/* text eol=lf\n>  /Documentation/git-merge.adoc conflict-marker-size=32\n>  /Documentation/git-merge-file.adoc conflict-marker-size=32\n> +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n>  /Documentation/gitk.adoc conflict-marker-size=32\n>  /Documentation/user-manual.adoc conflict-marker-size=32\n>  /t/t????-*.sh conflict-marker-size=32\n\nThe title of this patch seems to show a fundamental misunderstanding\nof what these custom conflict marker settings mean.  I believe the\nplan is to squash this into the step that introduces the new file;\nwhen that happens, the patch title will disappear and we will not\nhave to worry about it, but regardless.\n\nSetting a custom 'conflict-marker-size' is not about ignoring\nanything.  It ensures that payload lines that happen to look like\nconflict markers are not mistaken for them.  Machinery like rerere\nparses conflicted files, and you do not want it to mistake a run of\nseven '<' characters at the beginning of a line you deliberately\nwrote as the start of a conflict block.  You prevent such mistakes\nby specifying that the conflict delimiter used during conflicts will\nbe N (!= 7) characters long, instead of the regular seven.\n\nBy the way, some of the points above might be worth teaching in the\nmaterial covering merge conflicts (i.e., this series).  I do not\nthink many people write manuals on Git with examples of what a\nconflict block looks like ;-), but a run of seven '<', '=', '|', or\n'>' characters may appear in real payloads that users need to use,\nin contexts completely unrelated to ours.\n\nSetting 'conflict-marker-size' to a length that their payload is\nunlikely to use is a useful technique to be aware of.\n\nThanks.\n\n"},{"id":"554585","messageId":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH v2 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:07Z","receivedAt":"2026-10-09T12:00:07Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Handling merge conflicts is difficult, and currently Git's guidance on merge\nconflicts isn't giving users the information they need to navigate the\nprocess. As usual, the process I used to write this was to collect comments\nfrom Git users on the existing documentation, and then address those issues.\nI listed the specific issues we're aiming to solve in the first commit\nmessage in the series.\n\nThis patch series introduces a new manual page, gitmergeconflicts, which\nexplains the process of explaining a merge conflict with examples. It also\nlinks to that new page from the commands which can cause merge conflicts,\ninstead of trying to reexplain the process every time.\n\nChanged in v2:\n\n * [x] Explain what a merge conflict is (thanks to Junio & Ben)\n * [x] rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n   comments)\n * [x] add git log --merge (thanks to Ben)\n * [x] Leave most of the content of git cherry-pick as-is, to make this\n   patch set smaller (thanks to Junio)\n * [x] remove the SYNOPSIS since hopefully that won't be required anymore by\n   the time this is merged\n * [x] Fix a typo in git revert (s/reverted conflict/reverted commit/)\n * [x] 's/the the/the/' (thanks to Patrick)\n * [x] s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n * [x] squash the commit fixing the linter error (thanks to Junio)\n * [x] list reviewers in Reviewed-by\n\nSome things that we discussed but stayed the same:\n\n * \"git commit does the same thing as git merge --continue\" seems to be true\n   so we can leave it\n * Don't involve git am and git apply in this.\n * Junio suggested another diff3 example but I feel like there are already a\n   lot of examples\n * We've still removed one mention of MERGE_HEAD in the git merge man page\n   without replacing it. It's mentioned in other places though.\n\nThanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\nand about 12 others who gave feedback on both the original git merge man\npage, as well as the proposed improvements.\n\nJulia Evans (6):\n  doc: add new gitmergeconflicts man page\n  doc: git-merge: link to new merge conflicts guide\n  doc: git-rebase: link to new merge conflicts guide\n  doc: git-revert: link to new merge conflicts guide\n  doc: git-cherry-pick: link to new merge conflicts guide\n  doc: git-pull: link to new merge conflicts guide\n\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/git-cherry-pick.adoc   |  11 +-\n Documentation/git-merge.adoc         | 125 +---------\n Documentation/git-pull.adoc          |   3 +-\n Documentation/git-rebase.adoc        |  13 +-\n Documentation/git-revert.adoc        |   5 +\n Documentation/gitmergeconflicts.adoc | 333 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 10 files changed, 362 insertions(+), 132 deletions(-)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2237\n\nRange-diff vs v1:\n\n 1:  ad4853dc36 ! 1:  ab0344f947 [doc] Add new gitmergeconflicts man page\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] Add new gitmergeconflicts man page\n     +    doc: add new gitmergeconflicts man page\n      \n          Introduce a new page, `gitmergeconflicts`, that explains the process of\n          handling a merge conflict in a way that addresses the following issues,\n     @@ Commit message\n          interface between similar commands.\n      \n          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n     +    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n     +    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     + ## .gitattributes ##\n     +@@ .gitattributes: CODE_OF_CONDUCT.md -whitespace\n     + /t/oid-info/* text eol=lf\n     + /Documentation/git-merge.adoc conflict-marker-size=32\n     + /Documentation/git-merge-file.adoc conflict-marker-size=32\n     ++/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n     + /Documentation/gitk.adoc conflict-marker-size=32\n     + /Documentation/user-manual.adoc conflict-marker-size=32\n     + /t/t????-*.sh conflict-marker-size=32\n     +\n       ## Documentation/Makefile ##\n      @@ Documentation/Makefile: MAN7_TXT += gitdiffcore.adoc\n       MAN7_TXT += giteveryday.adoc\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +----\n      +gitmergeconflicts - Guide to handling merge conflicts\n      +\n     -+\n     -+SYNOPSIS\n     -+--------\n     -+Guide to handling merge conflicts\n     -+\n     -+\n      +DESCRIPTION\n      +-----------\n      +\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n      +  for how to find the command to run.\n      +\n     ++WHAT IS A MERGE CONFLICT?\n     ++-------------------------\n     ++\n     ++When Git merges two commits together, it looks at the changes that\n     ++each side has made and combines those changes. For example, if one side\n     ++edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n     ++the same file, then it can easily combine them since there's no overlap.\n     ++\n     ++But if both sides edited overlapping lines of the same file (for example\n     ++one side edited lines 1-5 and the other edited lines 3-6), Git will\n     ++not try to guess how to combine those changes. This is called a \"merge\n     ++conflict\".\n     ++\n     ++When this happens, Git shows you both sides' edits and asks you to pick\n     ++how to resolve them. It:\n     ++\n     ++* Stages all of the files which were successfully merged\n     ++* For the files with conflicts, it marks them as conflicted, puts both\n     ++  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n     ++  that you need to resolve.\n      +\n      +[[markers]]\n      +MERGE CONFLICT MARKERS\n      +----------------------\n      +\n     -+Merge conflicts happen when both of the sides being merged edit the same\n     -+area of a file. When this happens, Git will update the conflicted file\n     ++When there's a merge conflict, Git will update the conflicted file\n      +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n      +For example, here's a merge conflict where both sides edited a list of\n      +fruits in different ways:\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +   below for how to find the command to run.\n      ++\n      +Note: During a `git merge`, `git commit` and `git merge --continue` do\n     -+the the same thing.\n     ++the same thing.\n      +\n      +\n      +[[example]]\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +* You can set the configuration option `merge.conflictstyle=diff3`.\n      +  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n      +\n     ++* `git log --merge -p <filename>`  will list all commits which\n     ++  caused the merge conflict for `<filename>`, and the diff\n     ++  of how they changed the file.\n     ++\n      +* Look at the original files.  `git show :1:filename` shows the\n      +  common ancestor, `git show :2:filename` shows the \"ours\"\n      +  version, and `git show :3:filename` shows the \"theirs\"\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +\"OURS\" AND \"THEIRS\"\n      +-------------------\n      +\n     -+Git refers to the first part of a merge conflict (between `<<<<<<<`\n     -+and `=======`) as \"ours\" and the second part (between `=======` and\n     -+`>>>>>>>`) as \"theirs\".\n     ++Sometimes during a merge conflict, Git will use the terms \"ours\" and\n     ++\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n     ++a file was `deleted by us`.\n      +\n     -+Normally, \"ours\" is the commit that was checked out before you started\n     -+the merge, and \"theirs\" is the other commit.\n     ++\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n     ++`HEAD` commit, and \"theirs\" is the other side being merged.\n      +\n     -+But when the merge conflict was caused by a `git rebase`, it's the\n     -+opposite: \"theirs\" is the commit that was checked out before you started\n     -+the merge. This is because under the hood, `git rebase main` checks out\n     -+the `main` commit first before doing the merge operation.\n     ++The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n     ++from the \"ours\" side, and the second part (between `=======` and\n     ++`>>>>>>>`) is from the \"theirs\" side.\n     ++\n     ++----\n     ++FRUITS = [\n     ++    \"apple\",\n     ++<<<<<<< HEAD\n     ++    \"cherry\",                      <- ours\n     ++=======\n     ++    \"banana\",                      <- theirs\n     ++>>>>>>> add-fruit\n     ++    \"mango\",\n     ++    \"orange\",\n     ++]\n     ++----\n     ++\n     ++During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n     ++from the branch you're rebasing on (for instance `main` in `git rebase\n     ++main`).\n      +\n      +These terms in Git all mean the same thing when dealing with a merge\n      +conflict:\n      +\n     -+* \"common ancestor\", \"base\", and \"stage 1\"\n     -+* \"ours\", \"us\", \"stage 2\", and `HEAD`\n     -+* \"theirs\", \"them\", and \"stage 3\"\n     ++* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n     ++* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n     ++* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n     ++\n     ++If you're confused about what something like \"deleted by us\" means, it's\n     ++often easiest to use some of the tools from\n     ++<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n     ++Finding the commit that deleted the file and seeing why is usually more\n     ++helpful than trying to abstractly reason through what \"us\" means.\n      +\n      +[[automerge]]\n     -+Example of using `AUTO_MERGE`\n     ++EXAMPLE OF USING `AUTO_MERGE`\n      +-----------------------------\n      +\n      +`git diff AUTO_MERGE` will show what changes you've made so far to\n      +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n      +merge. It contains the result of running the merge algorithm.\n      +\n     -+For example, if we resolved the conflict the way we did in the\n     -+<<example,example above>>, the diff would look like this:\n     ++For example, if we resolved the conflict by adding both \"banana\" and\n     ++\"cherry\" in order, the diff would look like this:\n      +\n      +----\n      + FRUITS = [\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      ++    \"cherry\",\n      +     \"mango\",\n      +     \"orange\",\n     -+]\n     ++ ]\n      +----\n      +\n      +[NOTE]\n     @@ Documentation/meson.build: manpages = {\n         'gitnamespaces.adoc' : 7,\n         'gitremote-helpers.adoc' : 7,\n         'gitrevisions.adoc' : 7,\n     +\n     + ## command-list.txt ##\n     +@@ command-list.txt: githooks                                userinterfaces\n     + gitignore                               userinterfaces\n     + gitk                                    mainporcelain\n     + gitmailmap                              userinterfaces\n     ++gitmergeconflicts                       guide\n     + gitmodules                              userinterfaces\n     + gitnamespaces                           guide\n     + gitprotocol-capabilities                developerinterfaces\n 2:  a1686a2d82 ! 2:  d5241eb901 [doc] git-merge: link to new merge conflicts guide\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] git-merge: link to new merge conflicts guide\n     +    doc: git-merge: link to new merge conflicts guide\n      \n          All of the info about merge conflicts has been moved to the new guide\n      \n 3:  128d69e482 ! 3:  72b1207045 [doc] git-rebase: link to new merge conflicts guide\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] git-rebase: link to new merge conflicts guide\n     +    doc: git-rebase: link to new merge conflicts guide\n      \n          Remove some of the detail about how to handle a merge conflict, since\n          it's explained in detail in the new guide, and there probably isn't\n 4:  ab459231e0 ! 4:  cfa0a8254a [doc] git-revert: link to new merge conflicts guide\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] git-revert: link to new merge conflicts guide\n     +    doc: git-revert: link to new merge conflicts guide\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/git-revert.adoc: both will discard uncommitted changes in your wor\n       See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n       between the three commands.\n       \n     -+If there have been new commits since the reverted conflict, there may\n     ++If there have been new commits since the reverted commit, there may\n      +be a merge conflict. See linkgit:gitmergeconflicts[7]\n      +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n      +\n 5:  03a6b43b58 ! 5:  62b70e9a02 [doc] git-cherry-pick: link to new merge conflicts guide\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] git-cherry-pick: link to new merge conflicts guide\n     +    doc: git-cherry-pick: link to new merge conflicts guide\n      \n          Remove the discussion of merge conflicts and replace it with a link to\n          the guide.\n     @@ Documentation/git-cherry-pick.adoc: Given one or more existing commits, apply th\n       \n      -When it is not obvious how to apply a change, the following\n      -happens:\n     --\n     --1. The current branch and `HEAD` pointer stay at the last commit\n     --   successfully made.\n     --2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that\n     --   introduced the change that is difficult to apply, unless the\n     --   `--no-commit` option was given.\n     --3. Paths in which the change applied cleanly are updated both\n     --   in the index file and in your working tree.\n     --4. For conflicting paths, the index file records up to three\n     --   versions, as described in the \"TRUE MERGE\" section of\n     --   linkgit:git-merge[1].  The working tree files will include\n     --   a description of the conflict bracketed by the usual\n     --   conflict markers `<<<<<<<` and `>>>>>>>`.\n     --5. No other modifications are made.\n     --\n     --See linkgit:git-merge[1] for some hints on resolving such\n     --conflicts.\n      +When it is not obvious how to apply a change, there may\n      +be a merge conflict. See linkgit:gitmergeconflicts[7]\n      +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n     ++\n     ++When a merge conflict happens:\n       \n     + 1. The current branch and `HEAD` pointer stay at the last commit\n     +    successfully made.\n     +@@ Documentation/git-cherry-pick.adoc: happens:\n     +    conflict markers `<<<<<<<` and `>>>>>>>`.\n     + 5. No other modifications are made.\n     + \n     +-See linkgit:git-merge[1] for some hints on resolving such\n     +-conflicts.\n     +-\n       OPTIONS\n       -------\n     + <commit>...::\n      @@ Documentation/git-cherry-pick.adoc: $ git cherry-pick -Xpatience topic^  <4>\n       SEE ALSO\n       --------\n 6:  d3904f0ca7 ! 6:  ac77db6762 [doc] git-pull: link to new merge conflicts guide\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] git-pull: link to new merge conflicts guide\n     +    doc: git-pull: link to new merge conflicts guide\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n 7:  4505fdc9a6 < -:  ---------- [doc] ignore conflict markers in gitmergeconflicts.adoc\n\n-- \ngitgitgadget\n\n"},{"id":"554586","messageId":"ab0344f947c252b1b7c8bb386586b8641223ba38.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:08Z","receivedAt":"2026-10-09T12:00:08Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nIntroduce a new page, `gitmergeconflicts`, that explains the process of\nhandling a merge conflict in a way that addresses the following issues,\nwhich came from feedback from Git users on the current explanation of\nmerge conflicts in the `git merge` man page:\n\n- The process for resolving a merge conflict is only explained in the\n  `git merge` man page, even though there are several other commands\n  which can result in conflicts\n- Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n  the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n  be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n  Similarly, it says \"The part before the `=======` is typically your\n  side...\", but doesn't explain what \"typically\" means.\n- It introduces the merge format using an analogy to RCS, which very few\n  Git users have ever used\n- In \"The only clean-ups you need are to reset the index file to the\n  `HEAD` commit to reverse 2. and to clean up working tree changes made\n  by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n  to mean\n- It uses a cultural reference (\"Conflict resolution is hard; let's go\n  shopping.\") which is confusing or unfamiliar to some people. I think it\n  would be clearer for users to use a code example instead.\n- It doesn't explain the difference between diff3 and zdiff3\n- It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n\nAlso document the unified `--abort`, `--continue` workflow in one\nplace, since it's a really nice example of a place Git has a consistent\ninterface between similar commands.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nReviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\nReviewed-by: Patrick Steinhardt <ps@pks.im>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/gitmergeconflicts.adoc | 333 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 5 files changed, 337 insertions(+)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\ndiff --git a/.gitattributes b/.gitattributes\nindex 26490ad60a..0a0fc950b1 100644\n--- a/.gitattributes\n+++ b/.gitattributes\n@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n /t/oid-info/* text eol=lf\n /Documentation/git-merge.adoc conflict-marker-size=32\n /Documentation/git-merge-file.adoc conflict-marker-size=32\n+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n /Documentation/gitk.adoc conflict-marker-size=32\n /Documentation/user-manual.adoc conflict-marker-size=32\n /t/t????-*.sh conflict-marker-size=32\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..bc49641dda 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\n MAN7_TXT += gitglossary.adoc\n+MAN7_TXT += gitmergeconflicts.adoc\n MAN7_TXT += gitpacking.adoc\n MAN7_TXT += gitnamespaces.adoc\n MAN7_TXT += gitremote-helpers.adoc\ndiff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\nnew file mode 100644\nindex 0000000000..5b0ba1a1de\n--- /dev/null\n+++ b/Documentation/gitmergeconflicts.adoc\n@@ -0,0 +1,333 @@\n+gitmergeconflicts(7)\n+====================\n+\n+NAME\n+----\n+gitmergeconflicts - Guide to handling merge conflicts\n+\n+DESCRIPTION\n+-----------\n+\n+Merge conflicts can happen during a `git merge`, `git rebase`, `git\n+cherry-pick`, `git pull`, or `git revert`. All of those commands use\n+the same merge algorithm, and the process for resolving a merge conflict\n+is always very similar.\n+\n+The most common ways to handle a merge conflict are:\n+\n+* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n+  below for details)\n+* Or stop the operation and return your branch to its original state\n+  with the appropriate `--abort` command, for example `git merge --abort`\n+  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n+  for how to find the command to run.\n+\n+WHAT IS A MERGE CONFLICT?\n+-------------------------\n+\n+When Git merges two commits together, it looks at the changes that\n+each side has made and combines those changes. For example, if one side\n+edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n+the same file, then it can easily combine them since there's no overlap.\n+\n+But if both sides edited overlapping lines of the same file (for example\n+one side edited lines 1-5 and the other edited lines 3-6), Git will\n+not try to guess how to combine those changes. This is called a \"merge\n+conflict\".\n+\n+When this happens, Git shows you both sides' edits and asks you to pick\n+how to resolve them. It:\n+\n+* Stages all of the files which were successfully merged\n+* For the files with conflicts, it marks them as conflicted, puts both\n+  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n+  that you need to resolve.\n+\n+[[markers]]\n+MERGE CONFLICT MARKERS\n+----------------------\n+\n+When there's a merge conflict, Git will update the conflicted file\n+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n+For example, here's a merge conflict where both sides edited a list of\n+fruits in different ways:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+The code from one side of the merge conflict is between `<<<<<<<` and\n+`=======`, and the code for the other side is between `=======` and\n+`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n+of which side is which.\n+\n+\n+[[resolve]]\n+HOW TO RESOLVE A MERGE CONFLICT\n+-------------------------------\n+\n+The process for resolving a merge conflict is:\n+\n+1. Run `git status` to get a list of files with merge conflicts\n+2. For each one, find the conflict markers\n+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n+   fix the conflict\n+3. Run `git add FILENAME` for each file to mark the conflict as resolved\n+4. Run the appropriate `--continue` command to continue the operation\n+   that was interrupted by the conflict, for example `git merge --continue`\n+   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n+   below for how to find the command to run.\n++\n+Note: During a `git merge`, `git commit` and `git merge --continue` do\n+the same thing.\n+\n+\n+[[example]]\n+EXAMPLE OF RESOLVING A MERGE CONFLICT\n+-------------------------------------\n+\n+If you see this in your code during a merge conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+Then you might edit that part of the code like this,\n+which includes the fruits from both sides of the conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"banana\",\n+    \"cherry\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[tools]]\n+TOOLS FOR HANDLING MERGE CONFLICTS\n+----------------------------------\n+\n+Here are some ways to get extra context while handling a merge conflict:\n+\n+* There are many graphical \"merge tools\" for Git, which will normally\n+  show you the different versions of the code side by side.\n+  If you have a mergetool configured, `git mergetool` will launch it.\n+  See also `merge.tool` in linkgit:git-config[1] for a list of\n+  the mergetools Git supports.\n+\n+* You can set the configuration option `merge.conflictstyle=diff3`.\n+  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n+\n+* `git log --merge -p <filename>`  will list all commits which\n+  caused the merge conflict for `<filename>`, and the diff\n+  of how they changed the file.\n+\n+* Look at the original files.  `git show :1:filename` shows the\n+  common ancestor, `git show :2:filename` shows the \"ours\"\n+  version, and `git show :3:filename` shows the \"theirs\"\n+  version.\n+\n+Here are some ways to track your progress while handling a conflict:\n+\n+* Use `git status` to get a list of files with conflicts\n+\n+* Use `git diff --check` to make sure you haven't left any merge\n+  conflict markers in a file by accident. It will print \"leftover\n+  conflict marker\" if it finds any.\n+\n+* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n+  resolve the conflicts.\n+\n+[[git_status]]\n+EXAMPLE: GIT STATUS OUTPUT\n+--------------------------\n+\n+When you're in a merge conflict, you can find out what commands to run\n+to handle the conflict by running `git status`.\n+\n+For example, this `git status` output tells you that:\n+\n+* `git rebase --abort` will safely bring your branch back to its\n+  original state\n+* you should run `git rebase --continue` when you're done resolving all\n+  the conflicts\n+* there's one file left with conflicts in it: `fruits.py`\n+\n+----\n+$ git status\n+You are currently rebasing branch 'main' on '58a9fcc'.\n+  (fix conflicts and then run \"git rebase --continue\")\n+  (use \"git rebase --skip\" to skip this patch)\n+  (use \"git rebase --abort\" to check out the original branch)\n+\n+Unmerged paths:\n+  (use \"git restore --staged <file>...\" to unstage)\n+  (use \"git add <file>...\" to mark resolution)\n+        both modified:   fruits.py\n+----\n+\n+\n+[[diff3]]\n+DIFF3 AND ZDIFF3\n+----------------\n+\n+By default, Git doesn't include the original code when formatting\n+a merge conflict. To include the original code, you can set the\n+configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n+This extra context can make it much easier to understand what's\n+happening in a merge conflict.\n+\n+Here's an example of what a merge conflict would look like when using\n+`diff3`. It shows, in order, the \"ours\" side of the conflict, the\n+original code (`\"mangoooo\"`), and the \"theirs\" side of the\n+conflict. With this view, you can see that both sides fixed the spelling\n+mistake in \"mango\", and each added one fruit to the list.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+||||||| 1c22e48\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+Here's the same example using `zdiff3`. `zdiff3` takes lines that are\n+shared between both sides (the `\"mango\"` line) and moves them outside\n+the conflicted area. This makes the conflicted area shorter, but the\n+downside is that it's impossible to tell if `\"mango\"` was part of the\n+original list of fruits or not.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+||||||| 1c22e48\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[ours]]\n+\"OURS\" AND \"THEIRS\"\n+-------------------\n+\n+Sometimes during a merge conflict, Git will use the terms \"ours\" and\n+\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n+a file was `deleted by us`.\n+\n+\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n+`HEAD` commit, and \"theirs\" is the other side being merged.\n+\n+The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n+from the \"ours\" side, and the second part (between `=======` and\n+`>>>>>>>`) is from the \"theirs\" side.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",                      <- ours\n+=======\n+    \"banana\",                      <- theirs\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n+from the branch you're rebasing on (for instance `main` in `git rebase\n+main`).\n+\n+These terms in Git all mean the same thing when dealing with a merge\n+conflict:\n+\n+* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n+* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n+* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n+\n+If you're confused about what something like \"deleted by us\" means, it's\n+often easiest to use some of the tools from\n+<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n+Finding the commit that deleted the file and seeing why is usually more\n+helpful than trying to abstractly reason through what \"us\" means.\n+\n+[[automerge]]\n+EXAMPLE OF USING `AUTO_MERGE`\n+-----------------------------\n+\n+`git diff AUTO_MERGE` will show what changes you've made so far to\n+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n+merge. It contains the result of running the merge algorithm.\n+\n+For example, if we resolved the conflict by adding both \"banana\" and\n+\"cherry\" in order, the diff would look like this:\n+\n+----\n+ FRUITS = [\n+     \"apple\",\n+-<<<<<<< HEAD\n+-    \"cherry\",\n+-=======\n+     \"banana\",\n+->>>>>>> add-fruit\n++    \"cherry\",\n+     \"mango\",\n+     \"orange\",\n+ ]\n+----\n+\n+[NOTE]\n+`AUTO_MERGE` is only set if you're using the default Git merge algorithm.\n+\n+\n+SEE ALSO\n+--------\n+\n+linkgit:git-revert[1]\n+linkgit:git-merge[1]\n+linkgit:git-rebase[1]\n+linkgit:git-cherry-pick[1]\n+linkgit:git-pull[1]\n+linkgit:git-diff[1]\n+\n+GIT\n+---\n+\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f4854f802d..51647957e0 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -202,6 +202,7 @@ manpages = {\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n   'gitpacking.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n   'gitremote-helpers.adoc' : 7,\n   'gitrevisions.adoc' : 7,\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..f6e49c3c85 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -232,6 +232,7 @@ githooks                                userinterfaces\n gitignore                               userinterfaces\n gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n+gitmergeconflicts                       guide\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n gitprotocol-capabilities                developerinterfaces\n-- \ngitgitgadget\n\n\n"},{"id":"554587","messageId":"d5241eb901a2cc405bdebedc30d7e8c359898ba4.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 2/6] doc: git-merge: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:09Z","receivedAt":"2026-10-09T12:00:09Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAll of the info about merge conflicts has been moved to the new guide\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-merge.adoc | 125 +----------------------------------\n 1 file changed, 3 insertions(+), 122 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex a055384ad6..5b7b41cd10 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation,\n A merge stops if there's a conflict that cannot be resolved\n automatically or if `--no-commit` was provided when initiating the\n merge. At that point you can run `git merge --abort` or `git merge\n---continue`.\n+--continue`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n `git merge --abort` will abort the merge process and try to reconstruct\n the pre-merge state. However, if there were uncommitted changes when the\n@@ -231,127 +232,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-HOW CONFLICTS ARE PRESENTED\n----------------------------\n-\n-During a merge, the working tree files are updated to reflect the result\n-of the merge.  Among the changes made to the common ancestor's version,\n-non-overlapping ones (that is, you changed an area of the file while the\n-other side left that area intact, or vice versa) are incorporated in the\n-final result verbatim.  When both sides made changes to the same area,\n-however, Git cannot randomly pick one side over the other, and asks you to\n-resolve it by leaving what both sides did to that area.\n-\n-By default, Git uses the same style as the one used by the \"merge\" program\n-from the RCS suite to present such a conflicted hunk, like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-The area where a pair of conflicting changes happened is marked with markers\n-+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n-is typically your side, and the part afterwards is typically their side.\n-\n-The default format does not show what the original said in the conflicting\n-area.  You cannot tell how many lines are deleted and replaced with\n-Barbie's remark on your side.  The only thing you can tell is that your\n-side wants to say it is hard and you'd prefer to go shopping, while the\n-other side wants to claim it is easy.\n-\n-An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n-style, the above conflict may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-<<<<<<< yours:sample.txt\n-or cleanly resolved because both sides changed the same way.\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-or cleanly resolved because both sides changed the same way.\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-while in `zdiff3` style, it may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n-another +|||||||+ marker that is followed by the original text.  You can\n-tell that the original just stated a fact, and your side simply gave in to\n-that statement and gave up, while the other side tried to have a more\n-positive attitude.  You can sometimes come up with a better resolution by\n-viewing the original.\n-\n-\n-HOW TO RESOLVE CONFLICTS\n-------------------------\n-\n-After seeing a conflict, you can do two things:\n-\n- * Decide not to merge.  The only clean-ups you need are to reset\n-   the index file to the `HEAD` commit to reverse 2. and to clean\n-   up working tree changes made by 2. and 3.; `git merge --abort`\n-   can be used for this.\n-\n- * Resolve the conflicts.  Git will mark the conflicts in\n-   the working tree.  Edit the files into shape and\n-   `git add` them to the index.  Use `git commit` or\n-   `git merge --continue` to seal the deal. The latter command\n-   checks whether there is a (interrupted) merge in progress\n-   before calling `git commit`.\n-\n-You can work through the conflict with a number of tools:\n-\n- * Use a mergetool.  `git mergetool` to launch a graphical\n-   mergetool which will work through the merge with you.\n-\n- * Look at the diffs.  `git diff` will show a three-way diff,\n-   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n-   versions. `git diff AUTO_MERGE` will show what changes you've\n-   made so far to resolve textual conflicts.\n-\n- * Look at the diffs from each branch. `git log --merge -p <path>`\n-   will show diffs first for the `HEAD` version and then the\n-   `MERGE_HEAD` version.\n-\n- * Look at the originals.  `git show :1:filename` shows the\n-   common ancestor, `git show :2:filename` shows the `HEAD`\n-   version, and `git show :3:filename` shows the `MERGE_HEAD`\n-   version.\n-\n-\n EXAMPLES\n --------\n \n@@ -406,6 +286,7 @@ linkgit:git-reset[1],\n linkgit:git-diff[1], linkgit:git-ls-files[1],\n linkgit:git-add[1], linkgit:git-rm[1],\n linkgit:git-mergetool[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554588","messageId":"72b12070455aaf659eab049571451d1369a1d804.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 3/6] doc: git-rebase: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:10Z","receivedAt":"2026-10-09T12:00:10Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove some of the detail about how to handle a merge conflict, since\nit's explained in detail in the new guide, and there probably isn't\nenough detail anyway.\n\nLeave the steps since rebase is special and has a `--skip` option which\nthe other commands which cause merge conflicts don't have.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-rebase.adoc | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..da70aff498 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the\n first problematic commit and leave conflict markers. If this happens, you can do\n one of these things:\n \n-1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)\n-   and make edits to resolve the conflict. For each file you edit, you need to\n-   tell Git that the conflict has been resolved. You can mark the conflict as\n-   resolved with  `git add <filename>`. After resolving all of the conflicts,\n+1. Resolve the conflict. After resolving all of the conflicts,\n    you can continue the rebasing process with\n \n    git rebase --continue\n@@ -62,6 +59,9 @@ one of these things:\n \n    git rebase --skip\n \n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a full guide to handling merge conflicts.\n+\n If you don't specify an `<upstream>` to rebase onto, the upstream configured in\n `branch.<name>.remote` and `branch.<name>.merge` options will be used (see\n linkgit:git-config[1] for details) and the `--fork-point` option is\n@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[]\n include::config/rebase.adoc[]\n include::config/sequencer.adoc[]\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitmergeconflicts[7]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \ngitgitgadget\n\n\n"},{"id":"554589","messageId":"cfa0a8254ad88aa954af9cc3c4151993e07fe91c.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 4/6] doc: git-revert: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:11Z","receivedAt":"2026-10-09T12:00:11Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-revert.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e63..1edf98b9aa 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n+If there have been new commits since the reverted commit, there may\n+be a merge conflict. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n+\n OPTIONS\n -------\n <commit>...::\n@@ -162,6 +166,7 @@ include::config/revert.adoc[]\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554590","messageId":"62b70e9a02dfc9c5b5c980b71bb0507fa20cc0b9.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:12Z","receivedAt":"2026-10-09T12:00:12Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove the discussion of merge conflicts and replace it with a link to\nthe guide.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-cherry-pick.adoc | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex f4cd8b9db7..1834167287 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -19,8 +19,11 @@ Given one or more existing commits, apply the change each one\n introduces, recording a new commit for each.  This requires your\n working tree to be clean (no modifications from the HEAD commit).\n \n-When it is not obvious how to apply a change, the following\n-happens:\n+When it is not obvious how to apply a change, there may\n+be a merge conflict. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n+\n+When a merge conflict happens:\n \n 1. The current branch and `HEAD` pointer stay at the last commit\n    successfully made.\n@@ -36,9 +39,6 @@ happens:\n    conflict markers `<<<<<<<` and `>>>>>>>`.\n 5. No other modifications are made.\n \n-See linkgit:git-merge[1] for some hints on resolving such\n-conflicts.\n-\n OPTIONS\n -------\n <commit>...::\n@@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n SEE ALSO\n --------\n linkgit:git-revert[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554591","messageId":"ac77db6762c55eff9b6883eba98bfde3694aef24.1791547213.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"[PATCH v2 6/6] doc: git-pull: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-09T12:00:13Z","receivedAt":"2026-10-09T12:00:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-pull.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 88f4fd3926..73f6d460bb 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n \n If there's a merge conflict during the merge or rebase that you don't\n want to handle, you can safely abort it with `git merge --abort` or\n-`git rebase --abort`.\n+`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"554592","messageId":"d0797b01-14ce-4ead-bdd6-84d7bf7c0aac@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqse2h5hql.fsf@gitster.g","subject":"Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-09T12:06:24Z","receivedAt":"2026-10-09T12:06:24Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Oct 7, 2026, at 5:21 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc\n>> From: Julia Evans <julia@jvns.ca>\n>>\n>> Signed-off-by: Julia Evans <julia@jvns.ca>\n>> ---\n>>  .gitattributes | 1 +\n>>  1 file changed, 1 insertion(+)\n>>\n>> diff --git a/.gitattributes b/.gitattributes\n>> index 26490ad60a..0a0fc950b1 100644\n>> --- a/.gitattributes\n>> +++ b/.gitattributes\n>> @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n>>  /t/oid-info/* text eol=lf\n>>  /Documentation/git-merge.adoc conflict-marker-size=32\n>>  /Documentation/git-merge-file.adoc conflict-marker-size=32\n>> +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n>>  /Documentation/gitk.adoc conflict-marker-size=32\n>>  /Documentation/user-manual.adoc conflict-marker-size=32\n>>  /t/t????-*.sh conflict-marker-size=32\n\n> I believe the\n> plan is to squash this into the step that introduces the new file;\n> when that happens, the patch title will disappear and we will not\n> have to worry about it\n\nYes, I squashed it in the new version. I don't share your opinions\nabout how the title of this patch was worded but it's such a minor\npoint that I don't think it's worth discussing.\n\n> By the way, some of the points above might be worth teaching in the\n> material covering merge conflicts (i.e., this series).  I do not\n> think many people write manuals on Git with examples of what a\n> conflict block looks like ;-), but a run of seven '<', '=', '|', or\n> '>' characters may appear in real payloads that users need to use,\n> in contexts completely unrelated to ours.\n>\n> Setting 'conflict-marker-size' to a length that their payload is\n> unlikely to use is a useful technique to be aware of.\n\nI do not think that would be useful to explain in this series.\n(since as you say Git's situation is unusual and it's not a good\npractice to explain things that we don't think are relevant\n \"just in case\"). If users ask for it to be covered in the future\nwe can add it then.\n\n"},{"id":"554619","messageId":"xmqqse2evq2k.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T15:41:55Z","receivedAt":"2026-10-09T15:41:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>  * [x] list reviewers in Reviewed-by\n\nWe may have a bit of misunderstanding in the process regarding this.\n\n. `Reviewed-by:`, unlike the other trailers, can only be offered by the\n  reviewers themselves when they are completely satisfied with the\n  patch after a detailed analysis.\n\nis how SubmittingPatches describes it.\n\nReviewingGuidelines.adoc tells reviewers\n\n  If you are happy with the state of the patch series, explicitly\n  indicate your approval (typically with a reply to the latest\n  version's cover letter). Optionally, you can let the author know\n  that they can add a \"Reviewed-by: <you>\" trailer if they resubmit\n  the reviewed patch verbatim in a later iteration of the series.\n\nFor example, you added Ben and Patrick to the trailer of patch #1.\n\n> Range-diff vs v1:\n>\n>  1:  ad4853dc36 ! 1:  ab0344f947 [doc] Add new gitmergeconflicts man page\n>      @@ Metadata\n>       Author: Julia Evans <julia@jvns.ca>\n>       \n>        ## Commit message ##\n>      -    [doc] Add new gitmergeconflicts man page\n>      +    doc: add new gitmergeconflicts man page\n> ...\n>           Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>      +    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>      +    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n>           Signed-off-by: Julia Evans <julia@jvns.ca>\n\nGoing back to the review thread of the previous round of this patch,\nhttps://lore.kernel.org/git/ar3sGzEknG2_Un_E@pks.im/\n\n2026-09-24 14:44 ` [PATCH 1/7] [doc] Add new gitmergeconflicts man page Julia Evans via GitGitGadget\n2026-09-24 20:36   ` Junio C Hamano\n2026-09-24 22:04     ` Junio C Hamano\n2026-09-30 13:19   ` Patrick Steinhardt\n2026-09-30 19:53     ` Julia Evans\n2026-09-30 20:37       ` Junio C Hamano\n2026-10-01  5:14         ` Patrick Steinhardt [this message]\n2026-10-01 12:10           ` Julia Evans\n2026-10-02 17:58         ` Junio C Hamano\n2026-10-05 16:54       ` Julia Evans\n2026-10-05 17:22         ` Junio C Hamano\n2026-10-05 19:11           ` Julia Evans\n\nThere are many messages that reply to the cover letter of the same\niteration by Ben that gave a lot of good input, and I know Patrick\nalso helped during the discussion to improve the document.  I do not\nthink neither of them said anything about reviewed-by.\n\nWe do want to credit the reviewers of previous rounds for their\ninput that contributed to improvements in the latest round.  But the\nway to do so is by mentioning them on \"Helped-by:\" you add.\n\nThanks.\n\n"},{"id":"554621","messageId":"2a721921-2865-4cc4-8cd2-01eae74f27a5@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqse2evq2k.fsf@gitster.g","subject":"Re: [PATCH v2 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-09T15:53:43Z","receivedAt":"2026-10-09T15:53:43Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Oct 9, 2026, at 11:41 AM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>>  * [x] list reviewers in Reviewed-by\n>\n> We may have a bit of misunderstanding in the process regarding this.\n>\n> . `Reviewed-by:`, unlike the other trailers, can only be offered by the\n>   reviewers themselves when they are completely satisfied with the\n>   patch after a detailed analysis.\n>\n> is how SubmittingPatches describes it.\n\nThanks, put this in my todo list to fix in the next round.\nI'll use Helped-by instead.\n\n"},{"id":"554624","messageId":"xmqqik3arc2d.fsf@gitster.g","threadId":"66387","inReplyTo":"ab0344f947c252b1b7c8bb386586b8641223ba38.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T17:58:02Z","receivedAt":"2026-10-09T17:58:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Introduce a new page, `gitmergeconflicts`, that explains the process of\n> handling a merge conflict in a way that addresses the following issues,\n> which came from feedback from Git users on the current explanation of\n> merge conflicts in the `git merge` man page:\n\nGood goal.\n\n> - The process for resolving a merge conflict is only explained in the\n>   `git merge` man page, even though there are several other commands\n>   which can result in conflicts\n> - Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n>   the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n>   be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n>   Similarly, it says \"The part before the `=======` is typically your\n>   side...\", but doesn't explain what \"typically\" means.\n> - It introduces the merge format using an analogy to RCS, which very few\n>   Git users have ever used\n> - In \"The only clean-ups you need are to reset the index file to the\n>   `HEAD` commit to reverse 2. and to clean up working tree changes made\n>   by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n>   to mean\n> - It uses a cultural reference (\"Conflict resolution is hard; let's go\n>   shopping.\") which is confusing or unfamiliar to some people. I think it\n>   would be clearer for users to use a code example instead.\n> - It doesn't explain the difference between diff3 and zdiff3\n> - It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n\nIt is a bit hard to evaluate this list, as we do not see any of the\nabove problems excised from the existing documents in this step.\nBut at least we can verify that the new text presented in this patch\ndoes not fall into the same trap as above, so I'll keep that in mind\nwhile reviewing this step.\n\n> Also document the unified `--abort`, `--continue` workflow in one\n> place, since it's a really nice example of a place Git has a consistent\n> interface between similar commands.\n\nGreat.\n\n> Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n> Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n> Reviewed-by: Patrick Steinhardt <ps@pks.im>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n\nWe want a sign-off by the coauthor, too.\n\n> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n> new file mode 100644\n> index 0000000000..5b0ba1a1de\n> --- /dev/null\n> +++ b/Documentation/gitmergeconflicts.adoc\n> @@ -0,0 +1,333 @@\n> +gitmergeconflicts(7)\n> +====================\n> +\n> +NAME\n> +----\n> +gitmergeconflicts - Guide to handling merge conflicts\n> +\n> +DESCRIPTION\n> +-----------\n> +\n> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n> +cherry-pick`, `git pull`, or `git revert`. All of those commands use\n> +the same merge algorithm, and the process for resolving a merge conflict\n> +is always very similar.\n\nIs it deliberate to omit 'am -3' and 'checkout -m', perhaps in order\ntolimit ourselves to most common ways to help new people by keeping\nthe description to the absolute minimum?\n\nOr were they just overlooked?\n\nIn any case, the first paragraph clearly stating that conflicts\nhappen with operations other than 'merge' is a very welcome change.\nOn this list, we often say \"mergy operations can cause conflicts\",\nwith the understanding that readers know what mergy operations are\nand \"conflicts\" alone can convey the state you call \"merge\nconflicts\" in this document.  But in a document for end-users, using\na longer term \"merge conflicts\" instead of \"conflicts\" and avoiding\n\"mergy operations\" like you did above may be a better direction to\ngo.\n\n> +The most common ways to handle a merge conflict are:\n\nA natural paraphrase of the above is \"A merge conflict is typically\nhandled by these ways\", but I thought the current readers are\npuzzled by \"typically your side\" that does not say when is typical.\n\n> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n> +  below for details)\n> +* Or stop the operation and return your branch to its original state\n> +  with the appropriate `--abort` command, for example `git merge --abort`\n> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n> +  for how to find the command to run.\n\nBoth are good options and I do not think of a middle way.  Perhaps\nwe do not have to say that these are \"the most common\" and instead\nsay \"You handle a merge conflict by doing either of these two\"?\n\nSaying \"return your branch to\" is a bit misleading for two reasons.\nConflicts presented to the users are primarily visible in their\nworking tree files and the index.  A single commit operations like\n'merge', 'pull', and 'revert' does not touch your branch if they hit\na conflict, and 'rebase' works on a detached HEAD, and stops without\ntouching your branch when it sees a conflict.\n\nIf I were writing this, with the goal of avoiding the issues the\ncurrent text has you listed in the proposed log message, I would\nprobably say something like this:\n\n * Or give up and return to the original state with ...\n\n> +WHAT IS A MERGE CONFLICT?\n> +-------------------------\n> +\n> +When Git merges two commits together, it looks at the changes that\n> +each side has made and combines those changes. For example, if one side\n> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n> +the same file, then it can easily combine them since there's no overlap.\n\nMany of the operations, even \"git merge\", is not about merging \"two\ncommits\" together, but I do not think of a good way to explain it,\nso I accept that phrasing as a helpful white lie.  I mention this\nbecause somebody else may be able to come up with a better phrasing\nthat I (or authors of this iteration) couldn't think of.\n\n> +But if both sides edited overlapping lines of the same file (for example\n> +one side edited lines 1-5 and the other edited lines 3-6), Git will\n> +not try to guess how to combine those changes. This is called a \"merge\n> +conflict\".\n> +\n> +When this happens, Git shows you both sides' edits and asks you to pick\n> +how to resolve them. It:\n> +\n> +* Stages all of the files which were successfully merged\n> +* For the files with conflicts, it marks them as conflicted, puts both\n> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n> +  that you need to resolve.\n\nBy the way, I think we should briefly mention what sematnic merge\nconflicts are, and that Git does not detect them and that this\nmanual page does not tell readers how to deal with them.\n    \n    Note that non-overlapping changes from two sides may leave the\n    result in an inconsistent state.  With the edit to lines 1-5,\n    one side may have changed the name of a function, while with the\n    edit to lines 20-25, the other side may have added a new call to\n    the function by its original name.  This type of inconsistencies\n    are called semantic conflicts, Git has no way knowing that a\n    merge introduced semantic conflicts, and ends up producing a\n    broken result without merge conflicts.  This document does not\n    cover what to do with semantic conflicts.\n\nThat is overly long, but perhaps you can condense it down to the\nessense and shrink down to 1/3 of the size.\n\n> +[[markers]]\n> +MERGE CONFLICT MARKERS\n> +----------------------\n> +\n> +When there's a merge conflict, Git will update the conflicted file\n> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n\nI notice that when you introduce `diff3` below, you silently add\n`|||||||` to the mix without explaining what it is.\n\n    `|||||||` may also be used as merge conflict markers (explained\n    later).\n\nor something along the line here may help.  Or explain what it is in\n`diff3` section.  Either would work.  Adding without explanation\nwould not.\n\n> +For example, here's a merge conflict where both sides edited a list of\n> +fruits in different ways:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +=======\n> +    \"banana\",\n> +>>>>>>> add-fruit\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +The code from one side of the merge conflict is between `<<<<<<<` and\n> +`=======`, and the code for the other side is between `=======` and\n> +`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n> +of which side is which.\n\nIf we said \"one side wanted to have 'apple, cherry, mango, orange',\nwhile the other side wanted 'apply, banana, mango, orange', in the\nFRUITS array\", would it help the understanding?  Or is it too\nobvious?\n\n> +[[resolve]]\n> +HOW TO RESOLVE A MERGE CONFLICT\n> +-------------------------------\n> +\n> +The process for resolving a merge conflict is:\n> +\n> +1. Run `git status` to get a list of files with merge conflicts\n> +2. For each one, find the conflict markers\n> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n> +   fix the conflict\n> +3. Run `git add FILENAME` for each file to mark the conflict as resolved\n> +4. Run the appropriate `--continue` command to continue the operation\n> +   that was interrupted by the conflict, for example `git merge --continue`\n> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n> +   below for how to find the command to run.\n> ++\n> +Note: During a `git merge`, `git commit` and `git merge --continue` do\n> +the same thing.\n> +\n> +\n> +[[example]]\n> +EXAMPLE OF RESOLVING A MERGE CONFLICT\n> +-------------------------------------\n> +\n> +If you see this in your code during a merge conflict:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +    \"mango\",\n> +=======\n> +    \"banana\",\n> +    \"mango\",\n> +>>>>>>> add-fruit\n> +    \"orange\",\n> +]\n> +----\n\nIt would make your readers puzzled why the example is subtly\ndifferent from the earlier one that showed \"mango\" as not touched by\neither side.  I see this lays the groundwork for later demonstration\nof `diff3`, so having both sides explicitly want \"mango\" is a good\nexample.  Perhaps update the first example to be the same as this\none, which would reduce the mental burden by readers?\n\n> +\n> +Then you might edit that part of the code like this,\n> +which includes the fruits from both sides of the conflict:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +    \"banana\",\n> +    \"cherry\",\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n\nOK.\n\n> +[[tools]]\n> +TOOLS FOR HANDLING MERGE CONFLICTS\n> +----------------------------------\n> +\n> +Here are some ways to get extra context while handling a merge conflict:\n> +\n> +* There are many graphical \"merge tools\" for Git, which will normally\n> +  show you the different versions of the code side by side.\n> +  If you have a mergetool configured, `git mergetool` will launch it.\n> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n> +  the mergetools Git supports.\n> +\n> +* You can set the configuration option `merge.conflictstyle=diff3`.\n> +  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n\nThese are called 'configuration variables' throughout the manual\npages.  Be consistent and replace \"configuration option\" with\n\"configuration variable\", perhaps?\n\n> +* `git log --merge -p <filename>`  will list all commits which\n> +  caused the merge conflict for `<filename>`, and the diff\n> +  of how they changed the file.\n\nMaybe worth mentioning that `--left-right` often helps when you are\nnot super familiar with the histories being merged.\n\n> +* Look at the original files.  `git show :1:filename` shows the\n> +  common ancestor, `git show :2:filename` shows the \"ours\"\n> +  version, and `git show :3:filename` shows the \"theirs\"\n> +  version.\n\nMaybe it will help to say we will explain \"ours\" and \"theirs\" later\nin this document.\n\n> +Here are some ways to track your progress while handling a conflict:\n> +\n> +* Use `git status` to get a list of files with conflicts\n> +\n> +* Use `git diff --check` to make sure you haven't left any merge\n> +  conflict markers in a file by accident. It will print \"leftover\n> +  conflict marker\" if it finds any.\n\nGood.  This also complains about whitespace errors, by the way, but\nthe last sentence here would be sufficient to help the readers to\ntell them apart.\n\n> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n> +  resolve the conflicts.\n\nDoes a \"See below\" here help readers who haven't learned what\nAUTO_MERGE is?  If you can describe what AUTO_MERGE records (in\nother words, what you are comparing your progress against) in a\nsentence of two here, that would alleviate the need to assure them\nthat we have more in-depth coverage on this topic elsewhere.\n\n> +[[git_status]]\n> +EXAMPLE: GIT STATUS OUTPUT\n> +--------------------------\n> +\n> +When you're in a merge conflict, you can find out what commands to run\n> +to handle the conflict by running `git status`.\n> +\n> +For example, this `git status` output tells you that:\n> +\n> +* `git rebase --abort` will safely bring your branch back to its\n> +  original state\n> +* you should run `git rebase --continue` when you're done resolving all\n> +  the conflicts\n> +* there's one file left with conflicts in it: `fruits.py`\n\nThere may be users, after seeing the last point, left puzzled why\nfruits.py is still listed after they edited the file like instructed\nin an earlier example but haven't marked the resolution.\n\n    `fruits.py` is not marked as its conflicts resolved yet.\n\nor something?\n\n> +----\n> +$ git status\n> +You are currently rebasing branch 'main' on '58a9fcc'.\n> +  (fix conflicts and then run \"git rebase --continue\")\n> +  (use \"git rebase --skip\" to skip this patch)\n> +  (use \"git rebase --abort\" to check out the original branch)\n> +\n> +Unmerged paths:\n> +  (use \"git restore --staged <file>...\" to unstage)\n> +  (use \"git add <file>...\" to mark resolution)\n> +        both modified:   fruits.py\n> +----\n\nThe approach to give explanations first and then an example the\nexplanation explains next is refreshing to me.  As long as the\nexplanations are short enough, this may work better than the usual\norder to say \"you'd see something like this. let us explain ...\".\n\n> +[[diff3]]\n> +DIFF3 AND ZDIFF3\n> +----------------\n> +\n> +By default, Git doesn't include the original code when formatting\n> +a merge conflict. To include the original code, you can set the\n> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n> +This extra context can make it much easier to understand what's\n> +happening in a merge conflict.\n\nI think most on the list considers `zdiff3` a failed experiment that\nreduces usefulness of `diff3`.  Do we want to recommend it?\n\nIs it obvious to readers what \"original\" we are talking about?  We\nare not talking about the state we started the mergy operation from.\nWe are talking about what the common ancestor had before two sides\nstarted working on the text to cause the divergence that conflicted.\n\nOne way I can think of to resolve this is to back to \"What is a\nmerge conflict?\" section and introduce \"original\" right there.  I'll\nSHOUT my additions below:\n\n    When Git merges two commits together, it looks at the changes\n    that each side has made SINCE THE TWO SIDES DIVERGED and\n    combines those changes.  WE OFTEN CALL THIS STATE THEY DIVERGED\n    FROM THE \"ORIGINAL\".  For example, if one side edited lines 1-5\n    of `hello.py` and the other side edited lines 20-25 of the same\n    file, then it can easily combine them since there's no overlap.\n\nIf you later use \"common\" or \"common ancestor\", you can explain they\nare \"original\" we defined in the above paragraph.\n\nOr ...\n\n> +Here's an example of what a merge conflict would look like when using\n> +`diff3`. It shows, in order, the \"ours\" side of the conflict, the\n> +original code (`\"mangoooo\"`), and the \"theirs\" side of the\n> +conflict. With this view, you can see that both sides fixed the spelling\n> +mistake in \"mango\", and each added one fruit to the list.\n\n... perhaps you avoid \"common ancestor\" altogether, with the\nintention to deprecate it, and introduce \"original\", like in the\nabove paragraph?  That is fine too.  Once we establish what to call\n\"common, ours, theirs\", we should add them to glossary-contents, as\nI do not think we describe any of the ones we currently use there.\n\nAs I already mentioned, just like you said <<< === encloses your\nside and === >>> encloses their side in 2-way conflict display,\nwe need to say <<< ||| encloses yours and ||| === encloses common\nin diff3 output.  How theirs is shown remains the same.  Here is my\nattempt to do so with least disruption to the flow of the text.\n\n    Here is an example of what the same conflict might look with\n    `diff3`.  It uses a new separator `|||||||` before `=======`,\n    and shows, in order the \"ours\" side ...\n\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +    \"mango\",\n> +||||||| 1c22e48\n> +    \"mangoooo\",\n> +=======\n> +    \"banana\",\n> +    \"mango\",\n> +>>>>>>> add-fruit\n> +    \"orange\",\n> +]\n> +----\n> +\n> +Here's the same example using `zdiff3`. `zdiff3` takes lines that are\n> +shared between both sides (the `\"mango\"` line) and moves them outside\n> +the conflicted area. This makes the conflicted area shorter, but the\n> +downside is that it's impossible to tell if `\"mango\"` was part of the\n> +original list of fruits or not.\n\nYes, exactly.  That is why I think we shouldn't promote it, but\nwrite it off as a failed experiment, and just tell them not to use\nit in this document, without giving an example.\n\nIf the original were \"apple, banana, cherry, mangoooo, orange\", and\nours and theirs were the same as the above example, then a desirable\nconflict resolution would be \"apple, mango, orange\", because both\nsides knew the original had banana and cherry, and each side\nrejected one of them each.  It would be a good demonstration of why\n`diff3` is a better format than `(rcs)merge`, so if we were to spend\nlines on an example, I'd rather see it here, instead of zdiff3 example.\n\nBy the way, is it just me who finds those \"Here's\", \"there's\"\ncontractions disturbing in an official manual?  I've seen many of\nthem while reviewing this to be annoyed enough and had to blurt it\nout X-<.\n\n> +[[ours]]\n> +\"OURS\" AND \"THEIRS\"\n> +-------------------\n> +\n> +Sometimes during a merge conflict, Git will use the terms \"ours\" and\n> +\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n> +a file was `deleted by us`.\n\nOK.\n\n> +\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n> +`HEAD` commit, and \"theirs\" is the other side being merged.\n\nNow, \"commits\" is again a white lie.  The story becomes more\ncomplicated when we talk about cherry-pick and revert, but if we\nprimarily stick to what happens in 'merge' (which is what I've seen\nso far in this document), then it shouldn't add any extra difficulty\nto understand by saying \"ours and theirs are history of changes\nleading to the two commits since they diverged from the original\" to\nadd clarity.\n\n> +The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n> +from the \"ours\" side, and the second part (between `=======` and\n> +`>>>>>>>`) is from the \"theirs\" side.\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",                      <- ours\n> +=======\n> +    \"banana\",                      <- theirs\n> +>>>>>>> add-fruit\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n> +from the branch you're rebasing on (for instance `main` in `git rebase\n> +main`).\n> +\n> +These terms in Git all mean the same thing when dealing with a merge\n> +conflict:\n> +\n> +* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n> +* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n> +* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n> +\n> +If you're confused about what something like \"deleted by us\" means, it's\n> +often easiest to use some of the tools from\n> +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n> +Finding the commit that deleted the file and seeing why is usually more\n> +helpful than trying to abstractly reason through what \"us\" means.\n> +\n> +[[automerge]]\n> +EXAMPLE OF USING `AUTO_MERGE`\n> +-----------------------------\n> +\n> +`git diff AUTO_MERGE` will show what changes you've made so far to\n> +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n> +merge. It contains the result of running the merge algorithm.\n\nThe first sentence gave me \"Huh?  You haven't explained what\nAUTO_MERGE is yet\".  It may be just me, but I would have expected\npresentation order to be more like:\n\n    When merge conflicts happen, the result of merge algorithm,\n    together with conflict markers, is recorded in AUTO_MERGE.  As\n    you resolve conflicts, you can compare your working tree files\n    against it with `git diff AUTO_MERGE` to see your progress.\n\n> +For example, if we resolved the conflict by adding both \"banana\" and\n> +\"cherry\" in order, the diff would look like this:\n> +\n> +----\n> + FRUITS = [\n> +     \"apple\",\n> +-<<<<<<< HEAD\n> +-    \"cherry\",\n> +-=======\n> +     \"banana\",\n> +->>>>>>> add-fruit\n> ++    \"cherry\",\n> +     \"mango\",\n> +     \"orange\",\n> + ]\n> +----\n\nThanks.\n\n\nI was puzzled by this\n\n> - In \"The only clean-ups you need are to reset the index file to the\n>   `HEAD` commit to reverse 2. and to clean up working tree changes made\n>   by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n>   to mean\n\nand did some digging.\n\nThe text comes from ffb1a4bed5 (Documentation: Describe merge\noperation a bit better., 2005-11-28) that had \"When there are\nconflicts, these things happen. 1. HEAD does not move, 2. Cleanly\nmerged paths are updated in the index 3. Conflicts are recorded in\nhigher stage index entries and working tree files show conflict\nmarkers, 4. No other changes are done\" well before the mysterious\nreference to 2. and 3.\n\nWhen ebef7e5049 (Documentation: simplify How Merge Works,\n2010-01-23) tried to simplify the description, the list of \"these\nthings happen\" were removed/rewritten, and yet instructions on how\nto reset are left behind, still referring to 2. and 3.\n\nWe probably want a separate patch for Documentation/git-merge.adoc\nto rectify this 16 year old mistake.\n\n"},{"id":"554627","messageId":"xmqq8q46rb0t.fsf@gitster.g","threadId":"66387","inReplyTo":"d5241eb901a2cc405bdebedc30d7e8c359898ba4.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/6] doc: git-merge: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:20:34Z","receivedAt":"2026-10-09T18:20:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> All of the info about merge conflicts has been moved to the new guide\n\nIn the body text end the sentence with a full stop.\n\nAnd I just went though the \"new guide\" with fine toothed comb, I am\nvery much qualified to judge if the above claim is correct.  Let's\nsee.\n\n> @@ -231,127 +232,6 @@ git merge v1.2.3^0\n>  git merge --ff-only v1.2.3\n>  ----\n>  \n> -HOW CONFLICTS ARE PRESENTED\n> ----------------------------\n> -\n> -During a merge, the working tree files are updated to reflect the result\n> -of the merge.  Among the changes made to the common ancestor's version,\n> -non-overlapping ones (that is, you changed an area of the file while the\n> -other side left that area intact, or vice versa) are incorporated in the\n> -final result verbatim.  When both sides made changes to the same area,\n> -however, Git cannot randomly pick one side over the other, and asks you to\n> -resolve it by leaving what both sides did to that area.\n\nOK.  We said working tree files are updated.  We made a weak\nreference to \"common ancestor\" but with my suggested updates I think\nwe sufficiently cover this.  \"Git cannot ... and asks you ...\" had a\nnice nuance that we may not have captured in the new document (we\nstop at \"will not try to guess\" and say \"asks you to pick\" in a\nseaprate paragraph, which feels a bit detached than the original\nhere [***]).\n\n> -By default, Git uses the same style as the one used by the \"merge\" program\n> -from the RCS suite to present such a conflicted hunk, like this:\n> -\n> -------------\n> -Here are lines that are either unchanged from the common\n> -ancestor, or cleanly resolved because only one side changed,\n> -or cleanly resolved because both sides changed the same way.\n> -<<<<<<< yours:sample.txt\n> -Conflict resolution is hard;\n> -let's go shopping.\n> -=======\n> -Git makes conflict resolution easy.\n> ->>>>>>> theirs:sample.txt\n> -And here is another line that is cleanly resolved or unmodified.\n> -------------\n> -\n> -The area where a pair of conflicting changes happened is marked with markers\n> -+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n> -is typically your side, and the part afterwards is typically their side.\n> -\n> -The default format does not show what the original said in the conflicting\n> -area.  You cannot tell how many lines are deleted and replaced with\n> -Barbie's remark on your side.  The only thing you can tell is that your\n> -side wants to say it is hard and you'd prefer to go shopping, while the\n> -other side wants to claim it is easy.\n\nWe covered all of the above, except for the reference to RCS which\nwe explicitly wanted to lose.  Good.\n\n> -An alternative style can be used by setting the `merge.conflictStyle`\n> ...\n> -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n> -another +|||||||+ marker that is followed by the original text.\n\nThis is what we were missing in the new guide, which I tried to\nrectify without looking at this exact text.  In any shape it should\nbe preserved somehow [***].\n\n> - You can\n> -tell that the original just stated a fact, and your side simply gave in to\n> -that statement and gave up, while the other side tried to have a more\n> -positive attitude.  You can sometimes come up with a better resolution by\n> -viewing the original.\n\nWe covered this with \"fruits from both sides\" example, and I think\nthe explanation there is shorter and simpler to understand.\n\n> -HOW TO RESOLVE CONFLICTS\n> -------------------------\n> -\n> -After seeing a conflict, you can do two things:\n> -\n> - * Decide not to merge.  The only clean-ups you need are to reset\n> -   the index file to the `HEAD` commit to reverse 2. and to clean\n> -   up working tree changes made by 2. and 3.; `git merge --abort`\n> -   can be used for this.\n> -\n> - * Resolve the conflicts.  Git will mark the conflicts in\n> -   the working tree.  Edit the files into shape and\n> -   `git add` them to the index.  Use `git commit` or\n> -   `git merge --continue` to seal the deal. The latter command\n> -   checks whether there is a (interrupted) merge in progress\n> -   before calling `git commit`.\n\nThe new text tried to have a wiggle room with \"most common\", but\nnothing is lost from the above if we tweak it with my suggested\n\"there are only two\" [***].\n\n> -You can work through the conflict with a number of tools:\n> -\n> - * Use a mergetool.  `git mergetool` to launch a graphical\n> -   mergetool which will work through the merge with you.\n> -\n> - * Look at the diffs.  `git diff` will show a three-way diff,\n> -   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n> -   versions. `git diff AUTO_MERGE` will show what changes you've\n> -   made so far to resolve textual conflicts.\n> -\n> - * Look at the diffs from each branch. `git log --merge -p <path>`\n> -   will show diffs first for the `HEAD` version and then the\n> -   `MERGE_HEAD` version.\n> -\n> - * Look at the originals.  `git show :1:filename` shows the\n> -   common ancestor, `git show :2:filename` shows the `HEAD`\n> -   version, and `git show :3:filename` shows the `MERGE_HEAD`\n> -   version.\n\nWe covered this in \"Tools for handling\" section.  This version\ngroups AUTO_MERGE together with other tools, which may have its\nadvantages and disadvantages.  The latter two bullet points in the\nabove list is about static view, so is three-way O A B diff.  Use of\nmergetool and 'diff AUTO_MERGE\" are more dynamic \"how far have you\ncome\" view.  So separating the \"git diff\" that shows three-way\ncomparison and \"git diff AUTO_MERGE\" in the new document sounds like\nan improvement (even though 'mergetool' blurs the boundary between\n\"how the conflict looked like\" and \"what your eventual conflict you\nare working toward may look like\", though [***]).\n\nOverall, I fully agree with these removals.  We may want to take a\nfew points (marked with [***]) we learned during this review back to\nthe new document from here, though.\n\nThanks.\n\n"},{"id":"554628","messageId":"xmqq33ueraxq.fsf@gitster.g","threadId":"66387","inReplyTo":"72b12070455aaf659eab049571451d1369a1d804.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/6] doc: git-rebase: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:22:25Z","receivedAt":"2026-10-09T18:22:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Remove some of the detail about how to handle a merge conflict, since\n> it's explained in detail in the new guide, and there probably isn't\n> enough detail anyway.\n>\n> Leave the steps since rebase is special and has a `--skip` option which\n> the other commands which cause merge conflicts don't have.\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-rebase.adoc | 13 +++++++++----\n>  1 file changed, 9 insertions(+), 4 deletions(-)\n\nGreat.  There is nothing I would miss from these removed lines.  All\nare already described better in the new document, with or without\nsuggestions I made during reviews of [1/6] and [2/6].\n\n\n"},{"id":"554629","messageId":"xmqqwlrqpwae.fsf@gitster.g","threadId":"66387","inReplyTo":"cfa0a8254ad88aa954af9cc3c4151993e07fe91c.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/6] doc: git-revert: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:24:09Z","receivedAt":"2026-10-09T18:24:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-revert.adoc | 5 +++++\n>  1 file changed, 5 insertions(+)\n>\n> diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\n> index ffba365e63..1edf98b9aa 100644\n> --- a/Documentation/git-revert.adoc\n> +++ b/Documentation/git-revert.adoc\n> @@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n>  See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n>  between the three commands.\n>  \n> +If there have been new commits since the reverted commit, there may\n> +be a merge conflict. See linkgit:gitmergeconflicts[7]\n> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n> +\n\nThis is a strange thing to say.  Is it worth special casing the\nrevert of the tip commit that much?  \"Reverting a commit may resolt\nin a merge conflict\" should be sufficient, I would think.\n\n\n\n>  OPTIONS\n>  -------\n>  <commit>...::\n> @@ -162,6 +166,7 @@ include::config/revert.adoc[]\n>  SEE ALSO\n>  --------\n>  linkgit:git-cherry-pick[1]\n> +linkgit:gitmergeconflicts[7]\n>  \n>  GIT\n>  ---\n\n"},{"id":"554630","messageId":"xmqqse2epw6x.fsf@gitster.g","threadId":"66387","inReplyTo":"62b70e9a02dfc9c5b5c980b71bb0507fa20cc0b9.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:26:14Z","receivedAt":"2026-10-09T18:26:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> -When it is not obvious how to apply a change, the following\n> -happens:\n> +When it is not obvious how to apply a change, there may\n> +be a merge conflict. See linkgit:gitmergeconflicts[7]\n> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n\n\"Obvious to whom\" was the first thing that came to my mind, even\nthough the blame largely lies on the original.  Can't we get rid of\nthe above pragraph altogether, and \"See new one\" at the end where\nyou replaced \"See git-merge\" reference below?\n\n> +When a merge conflict happens:\n>  \n>  1. The current branch and `HEAD` pointer stay at the last commit\n>     successfully made.\n> @@ -36,9 +39,6 @@ happens:\n>     conflict markers `<<<<<<<` and `>>>>>>>`.\n>  5. No other modifications are made.\n>  \n> -See linkgit:git-merge[1] for some hints on resolving such\n> -conflicts.\n> -\n>  OPTIONS\n>  -------\n>  <commit>...::\n> @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n>  SEE ALSO\n>  --------\n>  linkgit:git-revert[1]\n> +linkgit:gitmergeconflicts[7]\n>  \n>  GIT\n>  ---\n\n"},{"id":"554631","messageId":"xmqqo6d2pw4i.fsf@gitster.g","threadId":"66387","inReplyTo":"ac77db6762c55eff9b6883eba98bfde3694aef24.1791547213.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 6/6] doc: git-pull: link to new merge conflicts guide","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:27:41Z","receivedAt":"2026-10-09T18:27:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>  Documentation/git-pull.adoc | 3 ++-\n>  1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\n> index 88f4fd3926..73f6d460bb 100644\n> --- a/Documentation/git-pull.adoc\n> +++ b/Documentation/git-pull.adoc\n> @@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n>  \n>  If there's a merge conflict during the merge or rebase that you don't\n>  want to handle, you can safely abort it with `git merge --abort` or\n> -`git rebase --abort`.\n> +`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n>  \n>  OPTIONS\n>  -------\n\nVery good.\n\n"},{"id":"554632","messageId":"xmqqik3apvpo.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.v2.git.1791547213.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T18:36:35Z","receivedAt":"2026-10-09T18:36:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Julia Evans (6):\n>   doc: add new gitmergeconflicts man page\n>   doc: git-merge: link to new merge conflicts guide\n>   doc: git-rebase: link to new merge conflicts guide\n>   doc: git-revert: link to new merge conflicts guide\n>   doc: git-cherry-pick: link to new merge conflicts guide\n>   doc: git-pull: link to new merge conflicts guide\n\nI've sent detailed reviews on #1 and commented on others.\n\nYou add my Reviewed-by: on [2/6], [3/6], and [6/6] if your new\niteration uses them as-is.  My suggestions to [4/6] and [5/6] are\nboth straight-forward, so if you choose to take them literally,\nyou can add my Reviewed-by: on them, too.\n\nThanks.\n\n"},{"id":"554635","messageId":"b40960d8-3033-4458-973a-67fc41e02b77@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqik3arc2d.fsf@gitster.g","subject":"Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-09T18:53:58Z","receivedAt":"2026-10-09T18:53:58Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Thanks for the review, I'm especially excited about the idea to remove zdiff3. \n\n>> Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>> Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>> Reviewed-by: Patrick Steinhardt <ps@pks.im>\n>> Signed-off-by: Julia Evans <julia@jvns.ca>\n>\n> We want a sign-off by the coauthor, too.\n\nWill do.\n\n>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n>> new file mode 100644\n>> index 0000000000..5b0ba1a1de\n>> --- /dev/null\n>> +++ b/Documentation/gitmergeconflicts.adoc\n>> @@ -0,0 +1,333 @@\n>> +gitmergeconflicts(7)\n>> +====================\n>> +\n>> +NAME\n>> +----\n>> +gitmergeconflicts - Guide to handling merge conflicts\n>> +\n>> +DESCRIPTION\n>> +-----------\n>> +\n>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use\n>> +the same merge algorithm, and the process for resolving a merge conflict\n>> +is always very similar.\n>\n> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order\n> to limit ourselves to most common ways to help new people by keeping\n> the description to the absolute minimum?\n\nIt's deliberate, we talked about that a bit in the discussion of the v1.\nCan add a note in the commit message.\n\n> In any case, the first paragraph clearly stating that conflicts\n> happen with operations other than 'merge' is a very welcome change.\n> On this list, we often say \"mergy operations can cause conflicts\",\n> with the understanding that readers know what mergy operations are\n> and \"conflicts\" alone can convey the state you call \"merge\n> conflicts\" in this document.  But in a document for end-users, using\n> a longer term \"merge conflicts\" instead of \"conflicts\" and avoiding\n> \"mergy operations\" like you did above may be a better direction to\n> go.\n>\n>> +The most common ways to handle a merge conflict are:\n>\n> A natural paraphrase of the above is \"A merge conflict is typically\n> handled by these ways\", but I thought the current readers are\n> puzzled by \"typically your side\" that does not say when is typical.\n>\n>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n>> +  below for details)\n>> +* Or stop the operation and return your branch to its original state\n>> +  with the appropriate `--abort` command, for example `git merge --abort`\n>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n>> +  for how to find the command to run.\n>\n> Both are good options and I do not think of a middle way.  Perhaps\n> we do not have to say that these are \"the most common\" and instead\n> say \"You handle a merge conflict by doing either of these two\"?\n\nI agree the \"the most common\" is kind of weaselly and I'd like to be more clear.\nThe reason I wrote \"typically\" is that during a rebase, there's an extra\n\"skip\" option, so it's not strictly true to say that there are just two options.\nNot sure if there's another option I'm not thinking of other than the\n\"skip\" in rebase.\n\n> Saying \"return your branch to\" is a bit misleading for two reasons.\n> Conflicts presented to the users are primarily visible in their\n> working tree files and the index.  A single commit operations like\n> 'merge', 'pull', and 'revert' does not touch your branch if they hit\n> a conflict, and 'rebase' works on a detached HEAD, and stops without\n> touching your branch when it sees a conflict.\n>\n> If I were writing this, with the goal of avoiding the issues the\n> current text has you listed in the proposed log message, I would\n> probably say something like this:\n>\n>  * Or give up and return to the original state with ...\n\nThat's reasonable, I think \"return to the original state\" would be fine.\nWill look at this.\n\n>\n>> +WHAT IS A MERGE CONFLICT?\n>> +-------------------------\n>> +\n>> +When Git merges two commits together, it looks at the changes that\n>> +each side has made and combines those changes. For example, if one side\n>> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n>> +the same file, then it can easily combine them since there's no overlap.\n>\n> Many of the operations, even \"git merge\", is not about merging \"two\n> commits\" together, but I do not think of a good way to explain it,\n> so I accept that phrasing as a helpful white lie.  I mention this\n> because somebody else may be able to come up with a better phrasing\n> that I (or authors of this iteration) couldn't think of.\n>\n>> +But if both sides edited overlapping lines of the same file (for example\n>> +one side edited lines 1-5 and the other edited lines 3-6), Git will\n>> +not try to guess how to combine those changes. This is called a \"merge\n>> +conflict\".\n>> +\n>> +When this happens, Git shows you both sides' edits and asks you to pick\n>> +how to resolve them. It:\n>> +\n>> +* Stages all of the files which were successfully merged\n>> +* For the files with conflicts, it marks them as conflicted, puts both\n>> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n>> +  that you need to resolve.\n>\n> By the way, I think we should briefly mention what sematnic merge\n> conflicts are, and that Git does not detect them and that this\n> manual page does not tell readers how to deal with them.\n>    \n>     Note that non-overlapping changes from two sides may leave the\n>     result in an inconsistent state.  With the edit to lines 1-5,\n>     one side may have changed the name of a function, while with the\n>     edit to lines 20-25, the other side may have added a new call to\n>     the function by its original name.  This type of inconsistencies\n>     are called semantic conflicts, Git has no way knowing that a\n>     merge introduced semantic conflicts, and ends up producing a\n>     broken result without merge conflicts.  This document does not\n>     cover what to do with semantic conflicts.\n>\n> That is overly long, but perhaps you can condense it down to the\n> essense and shrink down to 1/3 of the size.\n\nI was thinking about that too. Maybe we can briefly mention that git's\nmerges are not guaranteed to produce working code even when they\nsucceed and point to an example further down the page.\nAdded to my list of things to work on.\n\n>> +[[markers]]\n>> +MERGE CONFLICT MARKERS\n>> +----------------------\n>> +\n>> +When there's a merge conflict, Git will update the conflicted file\n>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n>\n> I notice that when you introduce `diff3` below, you silently add\n> `|||||||` to the mix without explaining what it is.\n>\n>     `|||||||` may also be used as merge conflict markers (explained\n>     later).\n>\n> or something along the line here may help.  Or explain what it is in\n> `diff3` section.  Either would work.  Adding without explanation\n> would not.\n\nI think explaining it in the diff3 section makes sense, will do.\n\n>> +For example, here's a merge conflict where both sides edited a list of\n>> +fruits in different ways:\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",\n>> +=======\n>> +    \"banana\",\n>> +>>>>>>> add-fruit\n>> +    \"mango\",\n>> +    \"orange\",\n>> +]\n>> +----\n>> +\n>> +The code from one side of the merge conflict is between `<<<<<<<` and\n>> +`=======`, and the code for the other side is between `=======` and\n>> +`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n>> +of which side is which.\n>\n> If we said \"one side wanted to have 'apple, cherry, mango, orange',\n> while the other side wanted 'apply, banana, mango, orange', in the\n> FRUITS array\", would it help the understanding?  Or is it too\n> obvious?\n\nI think it could make sense to add something here yes.\nAdded to my list.\n\n>> +[[example]]\n>> +EXAMPLE OF RESOLVING A MERGE CONFLICT\n>> +-------------------------------------\n>> +\n>> +If you see this in your code during a merge conflict:\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",\n>> +    \"mango\",\n>> +=======\n>> +    \"banana\",\n>> +    \"mango\",\n>> +>>>>>>> add-fruit\n>> +    \"orange\",\n>> +]\n>> +----\n>\n> It would make your readers puzzled why the example is subtly\n> different from the earlier one that showed \"mango\" as not touched by\n> either side.  I see this lays the groundwork for later demonstration\n> of `diff3`, so having both sides explicitly want \"mango\" is a good\n> example.  Perhaps update the first example to be the same as this\n> one, which would reduce the mental burden by readers?\n\nI very much agree it's important for the examples to match,\nwill work on that.  It's a bit tricky with diff3 like you say.\n\n>> +[[tools]]\n>> +TOOLS FOR HANDLING MERGE CONFLICTS\n>> +----------------------------------\n>> +\n>> +Here are some ways to get extra context while handling a merge conflict:\n>> +\n>> +* There are many graphical \"merge tools\" for Git, which will normally\n>> +  show you the different versions of the code side by side.\n>> +  If you have a mergetool configured, `git mergetool` will launch it.\n>> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n>> +  the mergetools Git supports.\n>> +\n>> +* You can set the configuration option `merge.conflictstyle=diff3`.\n>> +  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n>\n> These are called 'configuration variables' throughout the manual\n> pages.  Be consistent and replace \"configuration option\" with\n> \"configuration variable\", perhaps?\n\nThey seem to be both used interchangeably already:\n\n```\n$ grep 'configuration variable' *.adoc | wc -l\n     256\n$ grep 'configuration option' *.adoc | wc -l\n      46\n```\n\n`git-config.adoc` uses the term \"configuration option\" 2 times\nand \"configuration variable\" once. Is there supposed to be\nsome difference between these terms? As far as I can tell\nfrom brief history spelunking Git has used those terms\ninterchangeably for a long time. AFAIK \"configuration option\"\nis the term more often used outside Git.\n\n>> +* `git log --merge -p <filename>`  will list all commits which\n>> +  caused the merge conflict for `<filename>`, and the diff\n>> +  of how they changed the file.\n>\n> Maybe worth mentioning that `--left-right` often helps when you are\n> not super familiar with the histories being merged.\n\nI don't understand what this does or what it would be useful for so\nit's not possible for me to explain it  :). From my perspective\n\"ours\" and \"theirs\" are already confusing enough and introducing\n\"left\" and \"right\" seems like a lot. Is \"left\" the same as \"ours\"?\n\n>> +* Look at the original files.  `git show :1:filename` shows the\n>> +  common ancestor, `git show :2:filename` shows the \"ours\"\n>> +  version, and `git show :3:filename` shows the \"theirs\"\n>> +  version.\n>\n> Maybe it will help to say we will explain \"ours\" and \"theirs\" later\n> in this document.\n\nPlausible, added to my todo list to look at, thanks.\n\n>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n>> +  resolve the conflicts.\n>\n> Does a \"See below\" here help readers who haven't learned what\n> AUTO_MERGE is?  If you can describe what AUTO_MERGE records (in\n> other words, what you are comparing your progress against) in a\n> sentence of two here, that would alleviate the need to assure them\n> that we have more in-depth coverage on this topic elsewhere.\n\nI think this is okay the way it is.\n\n>> +[[git_status]]\n>> +EXAMPLE: GIT STATUS OUTPUT\n>> +--------------------------\n>> +\n>> +When you're in a merge conflict, you can find out what commands to run\n>> +to handle the conflict by running `git status`.\n>> +\n>> +For example, this `git status` output tells you that:\n>> +\n>> +* `git rebase --abort` will safely bring your branch back to its\n>> +  original state\n>> +* you should run `git rebase --continue` when you're done resolving all\n>> +  the conflicts\n>> +* there's one file left with conflicts in it: `fruits.py`\n>\n> There may be users, after seeing the last point, left puzzled why\n> fruits.py is still listed after they edited the file like instructed\n> in an earlier example but haven't marked the resolution.\n>\n>     `fruits.py` is not marked as its conflicts resolved yet.\n>\n> or something?\n\nThanks, agreed that \"there's one file left with conflicts in it: `fruits.py`\" isn't\nprecise enough. Will make it more accurate.\n\n>> +----\n>> +$ git status\n>> +You are currently rebasing branch 'main' on '58a9fcc'.\n>> +  (fix conflicts and then run \"git rebase --continue\")\n>> +  (use \"git rebase --skip\" to skip this patch)\n>> +  (use \"git rebase --abort\" to check out the original branch)\n>> +\n>> +Unmerged paths:\n>> +  (use \"git restore --staged <file>...\" to unstage)\n>> +  (use \"git add <file>...\" to mark resolution)\n>> +        both modified:   fruits.py\n>> +----\n>\n> The approach to give explanations first and then an example the\n> explanation explains next is refreshing to me.  As long as the\n> explanations are short enough, this may work better than the usual\n> order to say \"you'd see something like this. let us explain ...\".\n\nGlad to hear it!\n\n>> +[[diff3]]\n>> +DIFF3 AND ZDIFF3\n>> +----------------\n>> +\n>> +By default, Git doesn't include the original code when formatting\n>> +a merge conflict. To include the original code, you can set the\n>> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n>> +This extra context can make it much easier to understand what's\n>> +happening in a merge conflict.\n>\n> I think most on the list considers `zdiff3` a failed experiment that\n> reduces usefulness of `diff3`.  Do we want to recommend it?\n\nI'd be extremely happy to remove this if the list doesn't think zdiff3\nis useful. When I was writing this I was confused by zdiff3 and thought\ndiff3 made a lot more sense.\n\nMaybe we could add a note like this somewhere?\n\n   NOTE: zdiff3 was an experimental alternative to diff3 that makes\n   the merge conflict shorter by introducing more ambiguity.\n   It's still there for backwards compatibility but we don't recommend it.\n\n\n> By the way, is it just me who finds those \"Here's\", \"there's\"\n> contractions disturbing in an official manual?  I've seen many of\n> them while reviewing this to be annoyed enough and had to blurt it\n> out X-<.\n\nI find \"here is\" and \"there is\" to be distracting and overly formal,\ndifferent people are different I guess :)\n\n>> +\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n>> +`HEAD` commit, and \"theirs\" is the other side being merged.\n>\n> Now, \"commits\" is again a white lie.  The story becomes more\n> complicated when we talk about cherry-pick and revert, but if we\n> primarily stick to what happens in 'merge' (which is what I've seen\n> so far in this document), then it shouldn't add any extra difficulty\n> to understand by saying \"ours and theirs are history of changes\n> leading to the two commits since they diverged from the original\" to\n> add clarity.\n>\n>> +The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n>> +from the \"ours\" side, and the second part (between `=======` and\n>> +`>>>>>>>`) is from the \"theirs\" side.\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",                      <- ours\n>> +=======\n>> +    \"banana\",                      <- theirs\n>> +>>>>>>> add-fruit\n>> +    \"mango\",\n>> +    \"orange\",\n>> +]\n>> +----\n>> +\n>> +During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n>> +from the branch you're rebasing on (for instance `main` in `git rebase\n>> +main`).\n>> +\n>> +These terms in Git all mean the same thing when dealing with a merge\n>> +conflict:\n>> +\n>> +* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n>> +* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n>> +* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n>> +\n>> +If you're confused about what something like \"deleted by us\" means, it's\n>> +often easiest to use some of the tools from\n>> +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n>> +Finding the commit that deleted the file and seeing why is usually more\n>> +helpful than trying to abstractly reason through what \"us\" means.\n>> +\n>> +[[automerge]]\n>> +EXAMPLE OF USING `AUTO_MERGE`\n>> +-----------------------------\n>> +\n>> +`git diff AUTO_MERGE` will show what changes you've made so far to\n>> +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n>> +merge. It contains the result of running the merge algorithm.\n>\n> The first sentence gave me \"Huh?  You haven't explained what\n> AUTO_MERGE is yet\".  It may be just me, but I would have expected\n> presentation order to be more like:\n>\n>     When merge conflicts happen, the result of merge algorithm,\n>     together with conflict markers, is recorded in AUTO_MERGE.  As\n>     you resolve conflicts, you can compare your working tree files\n>     against it with `git diff AUTO_MERGE` to see your progress.\n\nCan take a look but I don't think it makes a big difference.\n\n>> +For example, if we resolved the conflict by adding both \"banana\" and\n>> +\"cherry\" in order, the diff would look like this:\n>> +\n>> +----\n>> + FRUITS = [\n>> +     \"apple\",\n>> +-<<<<<<< HEAD\n>> +-    \"cherry\",\n>> +-=======\n>> +     \"banana\",\n>> +->>>>>>> add-fruit\n>> ++    \"cherry\",\n>> +     \"mango\",\n>> +     \"orange\",\n>> + ]\n>> +----\n>\n> Thanks.\n>\n>\n> I was puzzled by this\n>\n>> - In \"The only clean-ups you need are to reset the index file to the\n>>   `HEAD` commit to reverse 2. and to clean up working tree changes made\n>>   by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n>>   to mean\n>\n> and did some digging.\n>\n> The text comes from ffb1a4bed5 (Documentation: Describe merge\n> operation a bit better., 2005-11-28) that had \"When there are\n> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly\n> merged paths are updated in the index 3. Conflicts are recorded in\n> higher stage index entries and working tree files show conflict\n> markers, 4. No other changes are done\" well before the mysterious\n> reference to 2. and 3.\n>\n> When ebef7e5049 (Documentation: simplify How Merge Works,\n> 2010-01-23) tried to simplify the description, the list of \"these\n> things happen\" were removed/rewritten, and yet instructions on how\n> to reset are left behind, still referring to 2. and 3.\n>\n> We probably want a separate patch for Documentation/git-merge.adoc\n> to rectify this 16 year old mistake.\n\nThanks for investigating!\n\n"},{"id":"554654","messageId":"c206ae13-a815-41fe-9cf9-95445b4f98e7@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqse2epw6x.fsf@gitster.g","subject":"Re: [PATCH v2 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-09T20:12:00Z","receivedAt":"2026-10-09T20:12:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Oct 9, 2026, at 2:26 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> -When it is not obvious how to apply a change, the following\n>> -happens:\n>> +When it is not obvious how to apply a change, there may\n>> +be a merge conflict. See linkgit:gitmergeconflicts[7]\n>> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n>\n> \"Obvious to whom\" was the first thing that came to my mind, even\n> though the blame largely lies on the original.  Can't we get rid of\n> the above pragraph altogether, and \"See new one\" at the end where\n> you replaced \"See git-merge\" reference below?\n\nSounds good to me. Same for the language around revert.\n\n>> +When a merge conflict happens:\n>>  \n>>  1. The current branch and `HEAD` pointer stay at the last commit\n>>     successfully made.\n>> @@ -36,9 +39,6 @@ happens:\n>>     conflict markers `<<<<<<<` and `>>>>>>>`.\n>>  5. No other modifications are made.\n>>  \n>> -See linkgit:git-merge[1] for some hints on resolving such\n>> -conflicts.\n>> -\n>>  OPTIONS\n>>  -------\n>>  <commit>...::\n>> @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n>>  SEE ALSO\n>>  --------\n>>  linkgit:git-revert[1]\n>> +linkgit:gitmergeconflicts[7]\n>>  \n>>  GIT\n>>  ---\n\n"},{"id":"554664","messageId":"xmqq4ieuleuq.fsf@gitster.g","threadId":"66387","inReplyTo":"b40960d8-3033-4458-973a-67fc41e02b77@app.fastmail.com","subject":"Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-09T21:54:21Z","receivedAt":"2026-10-09T21:54:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n>>> +  below for details)\n>>> +* Or stop the operation and return your branch to its original state\n>>> +  with the appropriate `--abort` command, for example `git merge --abort`\n>>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n>>> +  for how to find the command to run.\n>>\n>> Both are good options and I do not think of a middle way.  Perhaps\n>> we do not have to say that these are \"the most common\" and instead\n>> say \"You handle a merge conflict by doing either of these two\"?\n>\n> I agree the \"the most common\" is kind of weaselly and I'd like to be more clear.\n> The reason I wrote \"typically\" is that during a rebase, there's an extra\n> \"skip\" option, so it's not strictly true to say that there are just two options.\n> Not sure if there's another option I'm not thinking of other than the\n> \"skip\" in rebase.\n\nI do not think anything like \"rebase --skip\" in a multi-step\nintegration is what this document covers particularly well to begin\nwith.  Taking each conflicted step individually, with \"skip\", you\nare stopping the operation without resolving the conflict.\n\nPerhaps make it clear that in the above you are talking about what\nto do with each individual opportunity to give back conflict\nresolution to the command?  If you describe these two choices in the\ncontext of multi-step operation, each \"we stopped due to conflict\nand gave control back to you\" opportunity gives you these choices:\n\n * Give up, pretend this step did not exist, and continue.\n * Resolve the conflict, record it, and continue.\n\nIn addition, you have \"--abort\" to give up the whole thing.\nAnd a single step operation like \"git merge\" is a degenerated case\nof the above.  \"and continue\" part does not exist.\n\n> I was thinking about that too. Maybe we can briefly mention that git's\n> merges are not guaranteed to produce working code even when they\n> succeed and point to an example further down the page.\n> Added to my list of things to work on.\n\nIt's not limited to \"GIt's merges\" but applies in general.\n\n>>> +[[tools]]\n>>> +TOOLS FOR HANDLING MERGE CONFLICTS\n>>> +----------------------------------\n>>> +\n>>> +Here are some ways to get extra context while handling a merge conflict:\n>>> +\n>>> +* There are many graphical \"merge tools\" for Git, which will normally\n>>> +  show you the different versions of the code side by side.\n>>> +  If you have a mergetool configured, `git mergetool` will launch it.\n>>> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n>>> +  the mergetools Git supports.\n>>> +\n>>> +* You can set the configuration option `merge.conflictstyle=diff3`.\n>>> +  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n>>\n>> These are called 'configuration variables' throughout the manual\n>> pages.  Be consistent and replace \"configuration option\" with\n>> \"configuration variable\", perhaps?\n>\n> They seem to be both used interchangeably already:\n>\n> ```\n> $ grep 'configuration variable' *.adoc | wc -l\n>      256\n> $ grep 'configuration option' *.adoc | wc -l\n>       46\n> ```\n\nDo not make it worse.  The latter were mostly added people like you\nwho responds like the above; aim to be more consistent instead.\n\n>>> +* `git log --merge -p <filename>`  will list all commits which\n>>> +  caused the merge conflict for `<filename>`, and the diff\n>>> +  of how they changed the file.\n>>\n>> Maybe worth mentioning that `--left-right` often helps when you are\n>> not super familiar with the histories being merged.\n>\n> I don't understand what this does or what it would be useful for so\n> it's not possible for me to explain it  :). From my perspective\n> \"ours\" and \"theirs\" are already confusing enough and introducing\n> \"left\" and \"right\" seems like a lot. Is \"left\" the same as \"ours\"?\n\nIf you do not understand what it does, perhaps try it out?\n\n\"git log -p --merge\" is to break down the ours/theirs into\nindividual steps when changes on these sides were brought in in\nmultiple steps.  It shows individual changes per commit, but if you\nare not super familiar with these histories being merged, it is not\nobvious which commit came from which side.  And --left-right option\nis a way to help you tell which one came from which.\n\n>>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n>>> +  resolve the conflicts.\n>>\n>> Does a \"See below\" here help readers who haven't learned what\n>> AUTO_MERGE is?  If you can describe what AUTO_MERGE records (in\n>> other words, what you are comparing your progress against) in a\n>> sentence of two here, that would alleviate the need to assure them\n>> that we have more in-depth coverage on this topic elsewhere.\n>\n> I think this is okay the way it is.\n\nIs it because, unlike --left-right, you understand what it does?\nNot everybody shares what you know, you know ;-)\n\n * AUTO_MERGE records the initial merge result with conflict\n   markers.  `git diff AUTO_MERGE` can be used to show how much\n   progress you made to resolve these conflicts.\n\nperhaps.\n\n> Maybe we could add a note like this somewhere?\n>\n>    NOTE: zdiff3 was an experimental alternative to diff3 that makes\n>    the merge conflict shorter by introducing more ambiguity.\n>    It's still there for backwards compatibility but we don't recommend it.\n\nDrop \"experimental\" and I am 100% behind that statement ;-).\n\n>> By the way, is it just me who finds those \"Here's\", \"there's\"\n>> contractions disturbing in an official manual?  I've seen many of\n>> them while reviewing this to be annoyed enough and had to blurt it\n>> out X-<.\n>\n> I find \"here is\" and \"there is\" to be distracting and overly formal,\n> different people are different I guess :)\n\nI would prefer to be consistent in a single documentation set, though.\n\n>> The text comes from ffb1a4bed5 (Documentation: Describe merge\n>> operation a bit better., 2005-11-28) that had \"When there are\n>> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly\n>> merged paths are updated in the index 3. Conflicts are recorded in\n>> higher stage index entries and working tree files show conflict\n>> markers, 4. No other changes are done\" well before the mysterious\n>> reference to 2. and 3.\n>>\n>> When ebef7e5049 (Documentation: simplify How Merge Works,\n>> 2010-01-23) tried to simplify the description, the list of \"these\n>> things happen\" were removed/rewritten, and yet instructions on how\n>> to reset are left behind, still referring to 2. and 3.\n>>\n>> We probably want a separate patch for Documentation/git-merge.adoc\n>> to rectify this 16 year old mistake.\n>\n> Thanks for investigating!\n\nHeh, you already did the separate patch, which is [2/6], which I am\nhappy with.\n\n"},{"id":"554665","messageId":"E227CF3E-65FA-447E-936B-BF23DE5A2649@gmail.com","threadId":"66387","inReplyTo":"xmqqse2evq2k.fsf@gitster.g","subject":"Re: [PATCH v2 0/6] [doc] Add new page on merge conflicts","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-09T22:10:05Z","receivedAt":"2026-10-09T22:10:05Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 9 oct. 2026 à 11:41, Junio C Hamano <gitster@pobox.com> a écrit :\n> \n> > ﻿\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n> For example, you added Ben and Patrick to the trailer of patch #1.\n> \n>> Range-diff vs v1:\n>> \n>> 1:  ad4853dc36 ! 1:  ab0344f947 [doc] Add new gitmergeconflicts man page\n>>     @@ Metadata\n>>      Author: Julia Evans <julia@jvns.ca>\n>> \n>>       ## Commit message ##\n>>     -    [doc] Add new gitmergeconflicts man page\n>>     +    doc: add new gitmergeconflicts man page\n>> ...\n>>          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>>     +    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>>     +    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n>>          Signed-off-by: Julia Evans <julia@jvns.ca>\n\nPS I think I just use my non-suffixed email on this project; \nsee our .mailmap :)\n"},{"id":"554673","messageId":"87tsmucoqu.fsf@gitster.g","threadId":"66387","inReplyTo":"b40960d8-3033-4458-973a-67fc41e02b77@app.fastmail.com","subject":"Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-10T01:45:29Z","receivedAt":"2026-10-10T01:45:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\nComments on a few more points.\n\n>> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order\n>> to limit ourselves to most common ways to help new people by keeping\n>> the description to the absolute minimum?\n>\n> It's deliberate, we talked about that a bit in the discussion of the v1.\n> Can add a note in the commit message.\n\nBeing a part of _the_ technical manual on Git, I would like to see\nus aim for completeness, and where we don't leave a note that the\ndescription is not complete.  In this case,  between\n\n    Merge conflicts can happen during a `git merge`, `git rebase`, `git\n    cherry-pick`, `git pull`, `git am -3`, `git checkout -m`, `git\n    stash pop`, or `git revert`.\n\nthat aims for completeness and\n\n    Merge conflicts can happen during a `git merge`, `git rebase`, `git\n    cherry-pick`, `git pull`, or `git revert`, and other operations.\n\nthat admits the list is not complete, I have slight preference to\nthe first one.\n\n>> By the way, is it just me who finds those \"Here's\", \"there's\"\n>> contractions disturbing in an official manual?  I've seen many of\n>> them while reviewing this to be annoyed enough and had to blurt it\n>> out X-<.\n>\n> I find \"here is\" and \"there is\" to be distracting and overly formal,\n> different people are different I guess :)\n\nBut I wouldn't want you to be \"different\" here.  This is not your\ndiary or personal note.  This being a part of the technical manual,\nI would prefer to see the same formalness applied everywhere.\n\n"},{"id":"554762","messageId":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH v3 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:09Z","receivedAt":"2026-10-12T14:53:09Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Handling merge conflicts is difficult, and currently Git's guidance on merge\nconflicts isn't giving users the information they need to navigate the\nprocess. As usual, the process I used to write this was to collect comments\nfrom Git users on the existing documentation, and then address those issues.\nI listed the specific issues we're aiming to solve in the first commit\nmessage in the series.\n\nThis patch series introduces a new manual page, gitmergeconflicts, which\nexplains the process of explaining a merge conflict with examples. It also\nlinks to that new page from the commands which can cause merge conflicts,\ninstead of trying to reexplain the process every time.\n\nChanged in v2:\n\n * Explain what a merge conflict is (thanks to Junio & Ben)\n * rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n   comments)\n * add git log --merge (thanks to Ben)\n * Leave most of the content of git cherry-pick as-is, to make this patch\n   set smaller (thanks to Junio)\n * remove the SYNOPSIS since hopefully that won't be required anymore by the\n   time this is merged\n * Fix a typo in git revert (s/reverted conflict/reverted commit/)\n * 's/the the/the/' (thanks to Patrick)\n * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n * squash the commit fixing the linter error (thanks to Junio)\n * list reviewers in Reviewed-by\n\nChanged in v3:\n\nThanks to all the comments from Junio.\n\n * Add signoff from Marie\n * In \"For example, here's a merge conflict where both sides edited a list\n   of\", add a little more detail about how to interpret the merge conflict\n * When we introduce a merge mention \"semantic merge conflicts\"\n * Say \"... and any other command that does a merge\" when listing commands\n   that can cause merge conflicts.\n * Reviewed-by is not the right thing, use Helped-by\n * Adjust phrasing in git revert and git cherry-pick man pages\n * Reference the \"ours\" section in \"git show :2:filename shows the \"ours\"\"\n * \"there's one file left with conflicts in it: fruits.py\" isn't precise\n   enough, instead say \"the conflicts in fruits.py haven't been marked as\n   resolved\"\n * Delete the explanation of zdiff3 and add a brief warning instead. Don't\n   be too prescriptive, we should tell people what the issue is (ambiguity)\n   instead of trying to impose our opinion.\n * Explain ||||||| when we add diff3\n * Fix example in \"EXAMPLE OF RESOLVING A MERGE CONFLICT\" to make it\n   consistent with the other examples\n * Replace \"configuration option\" with \"configuration variable\"\n * Mention --skip instead of saying \"the most common ways\", which is\n   ambiguous\n * Add a pointer to the extended AUTO_MERGE sentence\n\nsome non-changes in v3:\n\n * didn't add any extra Reviewed-by\n * \"return your branch to its original state\": left the same because during\n   a multistep cherry-pick the branch does need to be returned to its\n   original state\n * leave the explanation of AUTO_MERGE the same since Marie says it's more\n   clear this way\n * leave contractions alone for now\n * don't say semantic merge applies to all merges since I think that will be\n   clear to readers\n * the wording of \"When Git merges two commits together\" is a bit weird but\n   we don't have a better idea right now\n * don't explain --left-right. Can be very easily added in the future if we\n   think it's important.\n\nThanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\nand about 12 others who gave feedback on both the original git merge man\npage, as well as the proposed improvements.\n\nJulia Evans (6):\n  doc: add new gitmergeconflicts man page\n  doc: git-merge: link to new merge conflicts guide\n  doc: git-rebase: link to new merge conflicts guide\n  doc: git-revert: link to new merge conflicts guide\n  doc: git-cherry-pick: link to new merge conflicts guide\n  doc: git-pull: link to new merge conflicts guide\n\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/git-cherry-pick.adoc   |   8 +-\n Documentation/git-merge.adoc         | 125 +---------\n Documentation/git-pull.adoc          |   3 +-\n Documentation/git-rebase.adoc        |  13 +-\n Documentation/git-revert.adoc        |   5 +\n Documentation/gitmergeconflicts.adoc | 330 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 10 files changed, 357 insertions(+), 131 deletions(-)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/2237\n\nRange-diff vs v2:\n\n 1:  ab0344f947 ! 1:  7aa0ae7ec3 doc: add new gitmergeconflicts man page\n     @@ Commit message\n          place, since it's a really nice example of a place Git has a consistent\n          interface between similar commands.\n      \n     +    Only discuss merge, rebase, cherry-pick, and revert for now even though\n     +    there are other ways that merge conflicts can happen because it's\n     +    awkward to talk about `am`, `apply`, and `checkout -m`.\n     +\n          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n     -    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n     -    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n     +    Helped-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n     +    Helped-by: Patrick Steinhardt <ps@pks.im>\n     +    Signed-off-by: Julia Evans <julia@jvns.ca>\n     +    Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## .gitattributes ##\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +-----------\n      +\n      +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n     -+cherry-pick`, `git pull`, or `git revert`. All of those commands use\n     -+the same merge algorithm, and the process for resolving a merge conflict\n     -+is always very similar.\n     ++cherry-pick`, `git pull`, `git revert`, or any other command that does\n     ++a merge. All of those commands use the same merge algorithm, and the\n     ++process for resolving a merge conflict is always very similar.\n      +\n     -+The most common ways to handle a merge conflict are:\n     ++There are 3 ways to handle a merge conflict:\n      +\n      +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n      +  below for details)\n     -+* Or stop the operation and return your branch to its original state\n     ++* Stop the operation and return your branch to its original state\n      +  with the appropriate `--abort` command, for example `git merge --abort`\n      +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n      +  for how to find the command to run.\n     ++* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n     ++  commit with the appropriate `--skip` command\n      +\n      +WHAT IS A MERGE CONFLICT?\n      +-------------------------\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n      +  that you need to resolve.\n      +\n     ++[NOTE]\n     ++================================\n     ++Even if Git successfully merges both sides with no conflicts, it's\n     ++possible to end up with code that doesn't work. For example, this can\n     ++happen if one side renames a function, and the other side adds a call to\n     ++the old function. This is called a \"semantic merge conflict\".\n     ++================================\n     ++\n      +[[markers]]\n      +MERGE CONFLICT MARKERS\n      +----------------------\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +When there's a merge conflict, Git will update the conflicted file\n      +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n      +For example, here's a merge conflict where both sides edited a list of\n     -+fruits in different ways:\n     ++fruits in different ways -- one side added \"cherry\" and the other side\n     ++added \"banana\":\n      +\n      +----\n      +FRUITS = [\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +    \"apple\",\n      +<<<<<<< HEAD\n      +    \"cherry\",\n     -+    \"mango\",\n      +=======\n      +    \"banana\",\n     -+    \"mango\",\n      +>>>>>>> add-fruit\n     ++    \"mango\",\n      +    \"orange\",\n      +]\n      +----\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  See also `merge.tool` in linkgit:git-config[1] for a list of\n      +  the mergetools Git supports.\n      +\n     -+* You can set the configuration option `merge.conflictstyle=diff3`.\n     -+  See <<diff3,DIFF3 AND ZDIFF3>> below for more.\n     ++* You can set the configuration variable `merge.conflictstyle=diff3`.\n     ++  See <<diff3,DIFF3>> below for more.\n      +\n      +* `git log --merge -p <filename>`  will list all commits which\n      +  caused the merge conflict for `<filename>`, and the diff\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +* Look at the original files.  `git show :1:filename` shows the\n      +  common ancestor, `git show :2:filename` shows the \"ours\"\n      +  version, and `git show :3:filename` shows the \"theirs\"\n     -+  version.\n     ++  version. See <<ours,\"OURS\" AND \"THEIRS\">> below for more on\n     ++  \"ours\" and \"theirs\".\n      +\n      +Here are some ways to track your progress while handling a conflict:\n      +\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +\n      +* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n      +  resolve the conflicts.\n     ++  See <<automerge,EXAMPLE OF USING `AUTO_MERGE`>> below for more.\n      +\n      +[[git_status]]\n      +EXAMPLE: GIT STATUS OUTPUT\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  original state\n      +* you should run `git rebase --continue` when you're done resolving all\n      +  the conflicts\n     -+* there's one file left with conflicts in it: `fruits.py`\n     ++* the conflicts in `fruits.py` haven't been marked as resolved\n      +\n      +----\n      +$ git status\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +\n      +\n      +[[diff3]]\n     -+DIFF3 AND ZDIFF3\n     -+----------------\n     ++DIFF3\n     ++-----\n      +\n      +By default, Git doesn't include the original code when formatting\n      +a merge conflict. To include the original code, you can set the\n     -+configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.\n     ++configuration option `merge.conflictstyle` to `diff3`.\n      +This extra context can make it much easier to understand what's\n      +happening in a merge conflict.\n      +\n      +Here's an example of what a merge conflict would look like when using\n     -+`diff3`. It shows, in order, the \"ours\" side of the conflict, the\n     -+original code (`\"mangoooo\"`), and the \"theirs\" side of the\n     -+conflict. With this view, you can see that both sides fixed the spelling\n     ++`diff3`. There's an extra section (between `|||||||` and `=======`)\n     ++with the original code.\n     ++\n     ++With this view, you can see that both sides fixed a spelling\n      +mistake in \"mango\", and each added one fruit to the list.\n      +\n      +----\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +]\n      +----\n      +\n     -+Here's the same example using `zdiff3`. `zdiff3` takes lines that are\n     -+shared between both sides (the `\"mango\"` line) and moves them outside\n     -+the conflicted area. This makes the conflicted area shorter, but the\n     -+downside is that it's impossible to tell if `\"mango\"` was part of the\n     -+original list of fruits or not.\n     -+\n     -+----\n     -+FRUITS = [\n     -+    \"apple\",\n     -+<<<<<<< HEAD\n     -+    \"cherry\",\n     -+||||||| 1c22e48\n     -+    \"mangoooo\",\n     -+=======\n     -+    \"banana\",\n     -+>>>>>>> add-fruit\n     -+    \"mango\",\n     -+    \"orange\",\n     -+]\n     -+----\n     -+\n     ++[NOTE]\n     ++================================\n     ++`zdiff3` is an alternative to `diff3` that makes the merge conflict\n     ++shorter by making it more ambiguous.\n     ++================================\n      +\n      +[[ours]]\n      +\"OURS\" AND \"THEIRS\"\n 2:  d5241eb901 = 2:  8bdbd64ca3 doc: git-merge: link to new merge conflicts guide\n 3:  72b1207045 = 3:  34ba85fcad doc: git-rebase: link to new merge conflicts guide\n 4:  cfa0a8254a ! 4:  85e117b070 doc: git-revert: link to new merge conflicts guide\n     @@ Documentation/git-revert.adoc: both will discard uncommitted changes in your wor\n       See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n       between the three commands.\n       \n     -+If there have been new commits since the reverted commit, there may\n     -+be a merge conflict. See linkgit:gitmergeconflicts[7]\n     -+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n     ++Reverting a commit may result in a merge conflict.\n     ++See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n     ++for a guide to handling merge conflicts.\n      +\n       OPTIONS\n       -------\n 5:  62b70e9a02 ! 5:  f99c99f955 doc: git-cherry-pick: link to new merge conflicts guide\n     @@ Documentation/git-cherry-pick.adoc: Given one or more existing commits, apply th\n       \n      -When it is not obvious how to apply a change, the following\n      -happens:\n     -+When it is not obvious how to apply a change, there may\n     -+be a merge conflict. See linkgit:gitmergeconflicts[7]\n     -+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n     -+\n      +When a merge conflict happens:\n       \n       1. The current branch and `HEAD` pointer stay at the last commit\n     @@ Documentation/git-cherry-pick.adoc: happens:\n       \n      -See linkgit:git-merge[1] for some hints on resolving such\n      -conflicts.\n     --\n     ++See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n     ++for a guide to handling merge conflicts.\n     + \n       OPTIONS\n       -------\n     - <commit>...::\n      @@ Documentation/git-cherry-pick.adoc: $ git cherry-pick -Xpatience topic^  <4>\n       SEE ALSO\n       --------\n 6:  ac77db6762 = 6:  7831b77178 doc: git-pull: link to new merge conflicts guide\n\n-- \ngitgitgadget\n\n"},{"id":"554763","messageId":"7aa0ae7ec3c1d02aa1533c27fa40f4815c03ba6e.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:10Z","receivedAt":"2026-10-12T14:53:10Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nIntroduce a new page, `gitmergeconflicts`, that explains the process of\nhandling a merge conflict in a way that addresses the following issues,\nwhich came from feedback from Git users on the current explanation of\nmerge conflicts in the `git merge` man page:\n\n- The process for resolving a merge conflict is only explained in the\n  `git merge` man page, even though there are several other commands\n  which can result in conflicts\n- Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n  the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n  be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n  Similarly, it says \"The part before the `=======` is typically your\n  side...\", but doesn't explain what \"typically\" means.\n- It introduces the merge format using an analogy to RCS, which very few\n  Git users have ever used\n- In \"The only clean-ups you need are to reset the index file to the\n  `HEAD` commit to reverse 2. and to clean up working tree changes made\n  by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n  to mean\n- It uses a cultural reference (\"Conflict resolution is hard; let's go\n  shopping.\") which is confusing or unfamiliar to some people. I think it\n  would be clearer for users to use a code example instead.\n- It doesn't explain the difference between diff3 and zdiff3\n- It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n\nAlso document the unified `--abort`, `--continue` workflow in one\nplace, since it's a really nice example of a place Git has a consistent\ninterface between similar commands.\n\nOnly discuss merge, rebase, cherry-pick, and revert for now even though\nthere are other ways that merge conflicts can happen because it's\nawkward to talk about `am`, `apply`, and `checkout -m`.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nHelped-by: D. Ben Knoble <ben.knoble+github@gmail.com>\nHelped-by: Patrick Steinhardt <ps@pks.im>\nSigned-off-by: Julia Evans <julia@jvns.ca>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/gitmergeconflicts.adoc | 330 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 5 files changed, 334 insertions(+)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\ndiff --git a/.gitattributes b/.gitattributes\nindex 26490ad60a..0a0fc950b1 100644\n--- a/.gitattributes\n+++ b/.gitattributes\n@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n /t/oid-info/* text eol=lf\n /Documentation/git-merge.adoc conflict-marker-size=32\n /Documentation/git-merge-file.adoc conflict-marker-size=32\n+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n /Documentation/gitk.adoc conflict-marker-size=32\n /Documentation/user-manual.adoc conflict-marker-size=32\n /t/t????-*.sh conflict-marker-size=32\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..bc49641dda 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\n MAN7_TXT += gitglossary.adoc\n+MAN7_TXT += gitmergeconflicts.adoc\n MAN7_TXT += gitpacking.adoc\n MAN7_TXT += gitnamespaces.adoc\n MAN7_TXT += gitremote-helpers.adoc\ndiff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\nnew file mode 100644\nindex 0000000000..3c6eaaddf8\n--- /dev/null\n+++ b/Documentation/gitmergeconflicts.adoc\n@@ -0,0 +1,330 @@\n+gitmergeconflicts(7)\n+====================\n+\n+NAME\n+----\n+gitmergeconflicts - Guide to handling merge conflicts\n+\n+DESCRIPTION\n+-----------\n+\n+Merge conflicts can happen during a `git merge`, `git rebase`, `git\n+cherry-pick`, `git pull`, `git revert`, or any other command that does\n+a merge. All of those commands use the same merge algorithm, and the\n+process for resolving a merge conflict is always very similar.\n+\n+There are 3 ways to handle a merge conflict:\n+\n+* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n+  below for details)\n+* Stop the operation and return your branch to its original state\n+  with the appropriate `--abort` command, for example `git merge --abort`\n+  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n+  for how to find the command to run.\n+* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n+  commit with the appropriate `--skip` command\n+\n+WHAT IS A MERGE CONFLICT?\n+-------------------------\n+\n+When Git merges two commits together, it looks at the changes that\n+each side has made and combines those changes. For example, if one side\n+edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n+the same file, then it can easily combine them since there's no overlap.\n+\n+But if both sides edited overlapping lines of the same file (for example\n+one side edited lines 1-5 and the other edited lines 3-6), Git will\n+not try to guess how to combine those changes. This is called a \"merge\n+conflict\".\n+\n+When this happens, Git shows you both sides' edits and asks you to pick\n+how to resolve them. It:\n+\n+* Stages all of the files which were successfully merged\n+* For the files with conflicts, it marks them as conflicted, puts both\n+  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n+  that you need to resolve.\n+\n+[NOTE]\n+================================\n+Even if Git successfully merges both sides with no conflicts, it's\n+possible to end up with code that doesn't work. For example, this can\n+happen if one side renames a function, and the other side adds a call to\n+the old function. This is called a \"semantic merge conflict\".\n+================================\n+\n+[[markers]]\n+MERGE CONFLICT MARKERS\n+----------------------\n+\n+When there's a merge conflict, Git will update the conflicted file\n+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n+For example, here's a merge conflict where both sides edited a list of\n+fruits in different ways -- one side added \"cherry\" and the other side\n+added \"banana\":\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+The code from one side of the merge conflict is between `<<<<<<<` and\n+`=======`, and the code for the other side is between `=======` and\n+`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n+of which side is which.\n+\n+\n+[[resolve]]\n+HOW TO RESOLVE A MERGE CONFLICT\n+-------------------------------\n+\n+The process for resolving a merge conflict is:\n+\n+1. Run `git status` to get a list of files with merge conflicts\n+2. For each one, find the conflict markers\n+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n+   fix the conflict\n+3. Run `git add FILENAME` for each file to mark the conflict as resolved\n+4. Run the appropriate `--continue` command to continue the operation\n+   that was interrupted by the conflict, for example `git merge --continue`\n+   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n+   below for how to find the command to run.\n++\n+Note: During a `git merge`, `git commit` and `git merge --continue` do\n+the same thing.\n+\n+\n+[[example]]\n+EXAMPLE OF RESOLVING A MERGE CONFLICT\n+-------------------------------------\n+\n+If you see this in your code during a merge conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+Then you might edit that part of the code like this,\n+which includes the fruits from both sides of the conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"banana\",\n+    \"cherry\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[tools]]\n+TOOLS FOR HANDLING MERGE CONFLICTS\n+----------------------------------\n+\n+Here are some ways to get extra context while handling a merge conflict:\n+\n+* There are many graphical \"merge tools\" for Git, which will normally\n+  show you the different versions of the code side by side.\n+  If you have a mergetool configured, `git mergetool` will launch it.\n+  See also `merge.tool` in linkgit:git-config[1] for a list of\n+  the mergetools Git supports.\n+\n+* You can set the configuration variable `merge.conflictstyle=diff3`.\n+  See <<diff3,DIFF3>> below for more.\n+\n+* `git log --merge -p <filename>`  will list all commits which\n+  caused the merge conflict for `<filename>`, and the diff\n+  of how they changed the file.\n+\n+* Look at the original files.  `git show :1:filename` shows the\n+  common ancestor, `git show :2:filename` shows the \"ours\"\n+  version, and `git show :3:filename` shows the \"theirs\"\n+  version. See <<ours,\"OURS\" AND \"THEIRS\">> below for more on\n+  \"ours\" and \"theirs\".\n+\n+Here are some ways to track your progress while handling a conflict:\n+\n+* Use `git status` to get a list of files with conflicts\n+\n+* Use `git diff --check` to make sure you haven't left any merge\n+  conflict markers in a file by accident. It will print \"leftover\n+  conflict marker\" if it finds any.\n+\n+* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n+  resolve the conflicts.\n+  See <<automerge,EXAMPLE OF USING `AUTO_MERGE`>> below for more.\n+\n+[[git_status]]\n+EXAMPLE: GIT STATUS OUTPUT\n+--------------------------\n+\n+When you're in a merge conflict, you can find out what commands to run\n+to handle the conflict by running `git status`.\n+\n+For example, this `git status` output tells you that:\n+\n+* `git rebase --abort` will safely bring your branch back to its\n+  original state\n+* you should run `git rebase --continue` when you're done resolving all\n+  the conflicts\n+* the conflicts in `fruits.py` haven't been marked as resolved\n+\n+----\n+$ git status\n+You are currently rebasing branch 'main' on '58a9fcc'.\n+  (fix conflicts and then run \"git rebase --continue\")\n+  (use \"git rebase --skip\" to skip this patch)\n+  (use \"git rebase --abort\" to check out the original branch)\n+\n+Unmerged paths:\n+  (use \"git restore --staged <file>...\" to unstage)\n+  (use \"git add <file>...\" to mark resolution)\n+        both modified:   fruits.py\n+----\n+\n+\n+[[diff3]]\n+DIFF3\n+-----\n+\n+By default, Git doesn't include the original code when formatting\n+a merge conflict. To include the original code, you can set the\n+configuration option `merge.conflictstyle` to `diff3`.\n+This extra context can make it much easier to understand what's\n+happening in a merge conflict.\n+\n+Here's an example of what a merge conflict would look like when using\n+`diff3`. There's an extra section (between `|||||||` and `=======`)\n+with the original code.\n+\n+With this view, you can see that both sides fixed a spelling\n+mistake in \"mango\", and each added one fruit to the list.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+||||||| 1c22e48\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+[NOTE]\n+================================\n+`zdiff3` is an alternative to `diff3` that makes the merge conflict\n+shorter by making it more ambiguous.\n+================================\n+\n+[[ours]]\n+\"OURS\" AND \"THEIRS\"\n+-------------------\n+\n+Sometimes during a merge conflict, Git will use the terms \"ours\" and\n+\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n+a file was `deleted by us`.\n+\n+\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n+`HEAD` commit, and \"theirs\" is the other side being merged.\n+\n+The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n+from the \"ours\" side, and the second part (between `=======` and\n+`>>>>>>>`) is from the \"theirs\" side.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",                      <- ours\n+=======\n+    \"banana\",                      <- theirs\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n+from the branch you're rebasing on (for instance `main` in `git rebase\n+main`).\n+\n+These terms in Git all mean the same thing when dealing with a merge\n+conflict:\n+\n+* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n+* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n+* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n+\n+If you're confused about what something like \"deleted by us\" means, it's\n+often easiest to use some of the tools from\n+<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n+Finding the commit that deleted the file and seeing why is usually more\n+helpful than trying to abstractly reason through what \"us\" means.\n+\n+[[automerge]]\n+EXAMPLE OF USING `AUTO_MERGE`\n+-----------------------------\n+\n+`git diff AUTO_MERGE` will show what changes you've made so far to\n+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n+merge. It contains the result of running the merge algorithm.\n+\n+For example, if we resolved the conflict by adding both \"banana\" and\n+\"cherry\" in order, the diff would look like this:\n+\n+----\n+ FRUITS = [\n+     \"apple\",\n+-<<<<<<< HEAD\n+-    \"cherry\",\n+-=======\n+     \"banana\",\n+->>>>>>> add-fruit\n++    \"cherry\",\n+     \"mango\",\n+     \"orange\",\n+ ]\n+----\n+\n+[NOTE]\n+`AUTO_MERGE` is only set if you're using the default Git merge algorithm.\n+\n+\n+SEE ALSO\n+--------\n+\n+linkgit:git-revert[1]\n+linkgit:git-merge[1]\n+linkgit:git-rebase[1]\n+linkgit:git-cherry-pick[1]\n+linkgit:git-pull[1]\n+linkgit:git-diff[1]\n+\n+GIT\n+---\n+\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f4854f802d..51647957e0 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -202,6 +202,7 @@ manpages = {\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n   'gitpacking.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n   'gitremote-helpers.adoc' : 7,\n   'gitrevisions.adoc' : 7,\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..f6e49c3c85 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -232,6 +232,7 @@ githooks                                userinterfaces\n gitignore                               userinterfaces\n gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n+gitmergeconflicts                       guide\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n gitprotocol-capabilities                developerinterfaces\n-- \ngitgitgadget\n\n\n"},{"id":"554764","messageId":"8bdbd64ca3532e03b90810d55c32330fa3df4872.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 2/6] doc: git-merge: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:11Z","receivedAt":"2026-10-12T14:53:11Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAll of the info about merge conflicts has been moved to the new guide\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-merge.adoc | 125 +----------------------------------\n 1 file changed, 3 insertions(+), 122 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex a055384ad6..5b7b41cd10 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation,\n A merge stops if there's a conflict that cannot be resolved\n automatically or if `--no-commit` was provided when initiating the\n merge. At that point you can run `git merge --abort` or `git merge\n---continue`.\n+--continue`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n `git merge --abort` will abort the merge process and try to reconstruct\n the pre-merge state. However, if there were uncommitted changes when the\n@@ -231,127 +232,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-HOW CONFLICTS ARE PRESENTED\n----------------------------\n-\n-During a merge, the working tree files are updated to reflect the result\n-of the merge.  Among the changes made to the common ancestor's version,\n-non-overlapping ones (that is, you changed an area of the file while the\n-other side left that area intact, or vice versa) are incorporated in the\n-final result verbatim.  When both sides made changes to the same area,\n-however, Git cannot randomly pick one side over the other, and asks you to\n-resolve it by leaving what both sides did to that area.\n-\n-By default, Git uses the same style as the one used by the \"merge\" program\n-from the RCS suite to present such a conflicted hunk, like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-The area where a pair of conflicting changes happened is marked with markers\n-+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n-is typically your side, and the part afterwards is typically their side.\n-\n-The default format does not show what the original said in the conflicting\n-area.  You cannot tell how many lines are deleted and replaced with\n-Barbie's remark on your side.  The only thing you can tell is that your\n-side wants to say it is hard and you'd prefer to go shopping, while the\n-other side wants to claim it is easy.\n-\n-An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n-style, the above conflict may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-<<<<<<< yours:sample.txt\n-or cleanly resolved because both sides changed the same way.\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-or cleanly resolved because both sides changed the same way.\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-while in `zdiff3` style, it may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n-another +|||||||+ marker that is followed by the original text.  You can\n-tell that the original just stated a fact, and your side simply gave in to\n-that statement and gave up, while the other side tried to have a more\n-positive attitude.  You can sometimes come up with a better resolution by\n-viewing the original.\n-\n-\n-HOW TO RESOLVE CONFLICTS\n-------------------------\n-\n-After seeing a conflict, you can do two things:\n-\n- * Decide not to merge.  The only clean-ups you need are to reset\n-   the index file to the `HEAD` commit to reverse 2. and to clean\n-   up working tree changes made by 2. and 3.; `git merge --abort`\n-   can be used for this.\n-\n- * Resolve the conflicts.  Git will mark the conflicts in\n-   the working tree.  Edit the files into shape and\n-   `git add` them to the index.  Use `git commit` or\n-   `git merge --continue` to seal the deal. The latter command\n-   checks whether there is a (interrupted) merge in progress\n-   before calling `git commit`.\n-\n-You can work through the conflict with a number of tools:\n-\n- * Use a mergetool.  `git mergetool` to launch a graphical\n-   mergetool which will work through the merge with you.\n-\n- * Look at the diffs.  `git diff` will show a three-way diff,\n-   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n-   versions. `git diff AUTO_MERGE` will show what changes you've\n-   made so far to resolve textual conflicts.\n-\n- * Look at the diffs from each branch. `git log --merge -p <path>`\n-   will show diffs first for the `HEAD` version and then the\n-   `MERGE_HEAD` version.\n-\n- * Look at the originals.  `git show :1:filename` shows the\n-   common ancestor, `git show :2:filename` shows the `HEAD`\n-   version, and `git show :3:filename` shows the `MERGE_HEAD`\n-   version.\n-\n-\n EXAMPLES\n --------\n \n@@ -406,6 +286,7 @@ linkgit:git-reset[1],\n linkgit:git-diff[1], linkgit:git-ls-files[1],\n linkgit:git-add[1], linkgit:git-rm[1],\n linkgit:git-mergetool[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554765","messageId":"34ba85fcad8744a8448a8862e1ea760b99d304c9.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 3/6] doc: git-rebase: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:12Z","receivedAt":"2026-10-12T14:53:12Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove some of the detail about how to handle a merge conflict, since\nit's explained in detail in the new guide, and there probably isn't\nenough detail anyway.\n\nLeave the steps since rebase is special and has a `--skip` option which\nthe other commands which cause merge conflicts don't have.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-rebase.adoc | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..da70aff498 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the\n first problematic commit and leave conflict markers. If this happens, you can do\n one of these things:\n \n-1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)\n-   and make edits to resolve the conflict. For each file you edit, you need to\n-   tell Git that the conflict has been resolved. You can mark the conflict as\n-   resolved with  `git add <filename>`. After resolving all of the conflicts,\n+1. Resolve the conflict. After resolving all of the conflicts,\n    you can continue the rebasing process with\n \n    git rebase --continue\n@@ -62,6 +59,9 @@ one of these things:\n \n    git rebase --skip\n \n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a full guide to handling merge conflicts.\n+\n If you don't specify an `<upstream>` to rebase onto, the upstream configured in\n `branch.<name>.remote` and `branch.<name>.merge` options will be used (see\n linkgit:git-config[1] for details) and the `--fork-point` option is\n@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[]\n include::config/rebase.adoc[]\n include::config/sequencer.adoc[]\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitmergeconflicts[7]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \ngitgitgadget\n\n\n"},{"id":"554766","messageId":"85e117b070f955e2fc828a76221ceedc64075f85.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 4/6] doc: git-revert: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:13Z","receivedAt":"2026-10-12T14:53:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-revert.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e63..bb0f859f66 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n+Reverting a commit may result in a merge conflict.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n+\n OPTIONS\n -------\n <commit>...::\n@@ -162,6 +166,7 @@ include::config/revert.adoc[]\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554767","messageId":"f99c99f955a101d1aa8c55c0689e3c1230e3d303.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:14Z","receivedAt":"2026-10-12T14:53:14Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove the discussion of merge conflicts and replace it with a link to\nthe guide.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-cherry-pick.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex f4cd8b9db7..069e434961 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -19,8 +19,7 @@ Given one or more existing commits, apply the change each one\n introduces, recording a new commit for each.  This requires your\n working tree to be clean (no modifications from the HEAD commit).\n \n-When it is not obvious how to apply a change, the following\n-happens:\n+When a merge conflict happens:\n \n 1. The current branch and `HEAD` pointer stay at the last commit\n    successfully made.\n@@ -36,8 +35,8 @@ happens:\n    conflict markers `<<<<<<<` and `>>>>>>>`.\n 5. No other modifications are made.\n \n-See linkgit:git-merge[1] for some hints on resolving such\n-conflicts.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n@@ -259,6 +258,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n SEE ALSO\n --------\n linkgit:git-revert[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"554768","messageId":"7831b77178cebae6bf62e9f48d9e863508686d14.1791816795.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"[PATCH v3 6/6] doc: git-pull: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-12T14:53:15Z","receivedAt":"2026-10-12T14:53:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-pull.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 88f4fd3926..73f6d460bb 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n \n If there's a merge conflict during the merge or rebase that you don't\n want to handle, you can safely abort it with `git merge --abort` or\n-`git rebase --abort`.\n+`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"554775","messageId":"CALnO6CAL7ogi5MDRJmzTqNjjG-S39rDn=GTx3nwM5ASz_kRZOg@mail.gmail.com","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/6] [doc] Add new page on merge conflicts","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-12T15:53:55Z","receivedAt":"2026-10-12T15:53:55Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Oct 12, 2026 at 10:53 AM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> Range-diff vs v2:\n>\n>  1:  ab0344f947 ! 1:  7aa0ae7ec3 doc: add new gitmergeconflicts man page\n>      @@ Commit message\n>           place, since it's a really nice example of a place Git has a consistent\n>           interface between similar commands.\n>\n>      +    Only discuss merge, rebase, cherry-pick, and revert for now even though\n>      +    there are other ways that merge conflicts can happen because it's\n>      +    awkward to talk about `am`, `apply`, and `checkout -m`.\n>      +\n>           Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>      -    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>      -    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n>      +    Helped-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n\nMaybe this got lost in the shuffle, but I do prefer to use\n<ben.knoble@gmail.com> for Git these days, thanks!\n\n>      +    Helped-by: Patrick Steinhardt <ps@pks.im>\n>      +    Signed-off-by: Julia Evans <julia@jvns.ca>\n>      +    Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>           Signed-off-by: Julia Evans <julia@jvns.ca>\n\nI don't *think* we need your sign-off twice here, but maybe you\nintended to communicate something by this ordering? I confess I'm not\nsure what it would be ':D\n\n-- \nD. Ben Knoble\n\n"},{"id":"554791","messageId":"xmqqwlrm7pii.fsf@gitster.g","threadId":"66387","inReplyTo":"7aa0ae7ec3c1d02aa1533c27fa40f4815c03ba6e.1791816795.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-12T18:16:53Z","receivedAt":"2026-10-12T18:16:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Introduce a new page, `gitmergeconflicts`, that explains the process of\n> handling a merge conflict in a way that addresses the following issues,\n> which came from feedback from Git users on the current explanation of\n> merge conflicts in the `git merge` man page:\n>\n> - The process for resolving a merge conflict is only explained in the\n> ...\n> - It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n\nIt looks a bit annoying that these sentences in the enumeration all\nlack their full stops.\n\n> Only discuss merge, rebase, cherry-pick, and revert for now even though\n> there are other ways that merge conflicts can happen because it's\n> awkward to talk about `am`, `apply`, and `checkout -m`.\n\nI do not know \"because it's awkward\" is a good justification,\nthough.  \"awkward\" why?\n\nIt might be tempting to omit some commands that are less common for\nnew users, but we are touching the main part of the technical manual\nthat are meant ot be used by everybody, so that is not a good reason\nto choose covering some but not others.\n\nI however agree that it is better to avoid appearing to be complete\nand leaving others (including future ones we add) with \"any other\ncommand that does a merge\" as this round of document gives.\n\n> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n> ...\n> +There are 3 ways to handle a merge conflict:\n> +\n> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n> +  below for details)\n> +* Stop the operation and return your branch to its original state\n> +  with the appropriate `--abort` command, for example `git merge --abort`\n> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n> +  for how to find the command to run.\n> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n> +  commit with the appropriate `--skip` command\n\nThe third entry is a nice addition.  multi-step anything are the\nsame, including revert, right?  I'd recommend updating it to\nsomething like \"if you are in a multi-step operation like `rebase`\"\nin the same spirit as the \"or any other command\" change you made at\nthe beginning of this file.\n\n> +[NOTE]\n> +================================\n> +Even if Git successfully merges both sides with no conflicts, it's\n> +possible to end up with code that doesn't work. For example, this can\n> +happen if one side renames a function, and the other side adds a call to\n> +the old function. This is called a \"semantic merge conflict\".\n> +================================\n\nOK.\n\n> +When there's a merge conflict, Git will update the conflicted file\n> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n> +For example, here's a merge conflict where both sides edited a list of\n> +fruits in different ways -- one side added \"cherry\" and the other side\n> +added \"banana\":\n\nYou added \"-- one side added ...\" at the end, which I think sends a\nwrong message.  With rcs-merge style conflict, you cannot simply\ntell, because it is ambiguous.  The original may have had both\nbanana and cherry, in which case the sample output shows the result\nof one side removing banana and the other side removing cherry.\n\nThe only thing you can say from the sample output below is in the\ncurrent state \"one side has cherry where the other side has banana,\nand everything else is the same\".  You cannot say more without\nseeing diff3 style conflict.\n\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +=======\n> +    \"banana\",\n> +>>>>>>> add-fruit\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +The code from one side of the merge conflict is between `<<<<<<<` and\n> +`=======`, and the code for the other side is between `=======` and\n> +`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n> +of which side is which.\n\n\n\n\n> +[[example]]\n> +EXAMPLE OF RESOLVING A MERGE CONFLICT\n> +-------------------------------------\n> +\n> +If you see this in your code during a merge conflict:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +=======\n> +    \"banana\",\n> +>>>>>>> add-fruit\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n> +\n> +Then you might edit that part of the code like this,\n> +which includes the fruits from both sides of the conflict:\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +    \"banana\",\n> +    \"cherry\",\n> +    \"mango\",\n> +    \"orange\",\n> +]\n> +----\n\nSo, this is one possible resolution.  We cannot tell if it is the\ncorrect one.\n\n> +[[tools]]\n> +TOOLS FOR HANDLING MERGE CONFLICTS\n> +----------------------------------\n> +\n> +Here are some ways to get extra context while handling a merge conflict:\n> ...\n\nThe incremental changes to this list looks good.\n\n> +[[diff3]]\n> +DIFF3\n> +-----\n> +\n> +By default, Git doesn't include the original code when formatting\n> +a merge conflict. To include the original code, you can set the\n> +configuration option `merge.conflictstyle` to `diff3`.\n> +This extra context can make it much easier to understand what's\n> +happening in a merge conflict.\n> +\n> +Here's an example of what a merge conflict would look like when using\n> +`diff3`. There's an extra section (between `|||||||` and `=======`)\n> +with the original code.\n> +\n> +With this view, you can see that both sides fixed a spelling\n> +mistake in \"mango\", and each added one fruit to the list.\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +    \"mango\",\n> +||||||| 1c22e48\n> +    \"mangoooo\",\n> +=======\n> +    \"banana\",\n> +    \"mango\",\n> +>>>>>>> add-fruit\n> +    \"orange\",\n> +]\n> +----\n\nTHis is a great example.  \n\nBut an even better example would be to give this:\n\n        FRUITS = [\n            \"apple\",\n        <<<<<<< HEAD\n            \"cherry\",\n            \"mango\",\n        ||||||| 1c22e48\n            \"banana\",\n            \"cherry\",\n            \"mangoooo\",\n        =======\n            \"banana\",\n            \"mango\",\n        >>>>>>> add-fruit\n            \"orange\",\n        ]\n\nand tell the readers that that the correct resolution is to have\n\"apply, mango, orange\", as each of cherry and banana was removed by\none side while the other side did not touch it.  Having cherry and\nbanana in the result is a tempting but not always correct conclusion\nunexperienced people would draw from the rcs-merge style output that\nis ambiguous, and here is a great place to teach it in this flow.\n\nEspecially because it would make it stand out that the point of\ndiff3's verboseness compared to the rcs-merge output is to\ndisambiguate two cases.  If you start from ABCmO and one side has\nABMO while the other side has ACMO, the right resolution would be\nAMO (the above case I added), but if your starting point were AmO\nand the two sides ends with ABMO and ACMO respectively, the right\nresolution would be ABCMO.  The rcs-merge output does not tell you\nwhich is more likely to be correct, diff3 disambiguates these two\ncases by being more verbose.\n\nAnd telling that value of diff3 is about disambiguating is valuable\nwhen ...\n\n> +[NOTE]\n> +================================\n> +`zdiff3` is an alternative to `diff3` that makes the merge conflict\n> +shorter by making it more ambiguous.\n> +================================\n\n... this note tells the readers that zdiff3 is a ambigous variant of\ndiff3, hinting its flaw.\n\n\n"},{"id":"554792","messageId":"xmqqse2a7pgo.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.v3.git.1791816795.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-12T18:17:59Z","receivedAt":"2026-10-12T18:17:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Changed in v2:\n>\n>  * Explain what a merge conflict is (thanks to Junio & Ben)\n>  * rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n>    comments)\n>  * add git log --merge (thanks to Ben)\n>  * Leave most of the content of git cherry-pick as-is, to make this patch\n>    set smaller (thanks to Junio)\n>  * remove the SYNOPSIS since hopefully that won't be required anymore by the\n>    time this is merged\n>  * Fix a typo in git revert (s/reverted conflict/reverted commit/)\n>  * 's/the the/the/' (thanks to Patrick)\n>  * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n>  * squash the commit fixing the linter error (thanks to Junio)\n>  * list reviewers in Reviewed-by\n\nI had some comments on diff3 in [1/6]; everything else looked good.\n\nThanks.\n\n"},{"id":"554793","messageId":"xmqqbj8y7okv.fsf@gitster.g","threadId":"66387","inReplyTo":"xmqqse2a7pgo.fsf@gitster.g","subject":"Re: [PATCH v3 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-12T18:37:04Z","receivedAt":"2026-10-12T18:37:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> I had some comments on diff3 in [1/6]; everything else looked good.\n\nHere is a restatement of my [1/6] review in a squashable patch form.\n\nThe second hunk arond l.77 replaces \"code\" with \"lines\", as not\neverybody using Git are writing program code, which is not what I\nmentioned earlier.  There are parts that talk about programs and\ncode, while other parts that talk about lines, so the mixture is\nalready there, but I think this part does not have to be specific\nto code, but just applicable to anything that is line oriented.\n\nThe main part of this change is the updated diff3 example.  It\nreveals that the situation was different from naive interpretation\nof an earlier (ambiguous) example showed.  This should help readers\nappreciate the extra information diff3 format supplies.\n\n Documentation/gitmergeconflicts.adoc | 30 ++++++++++++++++++++----------\n 1 file changed, 20 insertions(+), 10 deletions(-)\n\ndiff --git c/Documentation/gitmergeconflicts.adoc w/Documentation/gitmergeconflicts.adoc\nindex 3c6eaaddf8..eeeeac85c0 100644\n--- c/Documentation/gitmergeconflicts.adoc\n+++ w/Documentation/gitmergeconflicts.adoc\n@@ -60,8 +60,9 @@ MERGE CONFLICT MARKERS\n When there's a merge conflict, Git will update the conflicted file\n to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n For example, here's a merge conflict where both sides edited a list of\n-fruits in different ways -- one side added \"cherry\" and the other side\n-added \"banana\":\n+fruits in different ways, and ended up in different states.  One side\n+has \"banana\" but not \"cherry\", and the other side has \"cherry\", but\n+not \"banana\".\n \n ----\n FRUITS = [\n@@ -76,8 +77,8 @@ FRUITS = [\n ]\n ----\n \n-The code from one side of the merge conflict is between `<<<<<<<` and\n-`=======`, and the code for the other side is between `=======` and\n+The lines from one side of the merge conflict are between `<<<<<<<` and\n+`=======`, and the lines from the other side are between `=======` and\n `>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n of which side is which.\n \n@@ -121,8 +122,8 @@ FRUITS = [\n ]\n ----\n \n-Then you might edit that part of the code like this,\n-which includes the fruits from both sides of the conflict:\n+Then you might edit that part of the code like this, to take\n+all the fruits from both sides of the conflict:\n \n ----\n FRUITS = [\n@@ -208,15 +209,15 @@ DIFF3\n By default, Git doesn't include the original code when formatting\n a merge conflict. To include the original code, you can set the\n configuration option `merge.conflictstyle` to `diff3`.\n-This extra context can make it much easier to understand what's\n-happening in a merge conflict.\n+This extra context can make it easier to understand what's\n+happening in a merge conflict and avoid mismerges.\n \n Here's an example of what a merge conflict would look like when using\n `diff3`. There's an extra section (between `|||||||` and `=======`)\n with the original code.\n \n With this view, you can see that both sides fixed a spelling\n-mistake in \"mango\", and each added one fruit to the list.\n+mistake in \"mango\", and each removed one fruit from the list.\n \n ----\n FRUITS = [\n@@ -225,15 +226,24 @@ FRUITS = [\n     \"cherry\",\n     \"mango\",\n ||||||| 1c22e48\n+    \"banana\",\n+    \"cherry\",\n     \"mangoooo\",\n =======\n-    \"banana\",\n     \"mango\",\n >>>>>>> add-fruit\n     \"orange\",\n ]\n ----\n \n+In the default format, you would see this conflict as shown before,\n+i.e., \"one side has 'banana', the other side has 'cherry', everything\n+else is the same\".  But presented this way, we would realize that the\n+conflict resolution to keep \"banana\" and \"cherry\" we showed earlier\n+was incorrect.  Rather, we want to drop \"banana\", and \"cherry\" and\n+keep the \"mango\" with corrected spellings.  The `diff3` format is more\n+unambiguous by being more verbose.\n+\n [NOTE]\n ================================\n `zdiff3` is an alternative to `diff3` that makes the merge conflict\n\n"},{"id":"554810","messageId":"6dac0b01-3411-4999-b336-453efa8b5bcf@app.fastmail.com","threadId":"66387","inReplyTo":"CALnO6CAL7ogi5MDRJmzTqNjjG-S39rDn=GTx3nwM5ASz_kRZOg@mail.gmail.com","subject":"Re: [PATCH v3 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-12T20:44:13Z","receivedAt":"2026-10-12T20:44:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Mon, Oct 12, 2026, at 11:53 AM, D. Ben Knoble wrote:\n> On Mon, Oct 12, 2026 at 10:53 AM Julia Evans via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>>\n>> Range-diff vs v2:\n>>\n>>  1:  ab0344f947 ! 1:  7aa0ae7ec3 doc: add new gitmergeconflicts man page\n>>      @@ Commit message\n>>           place, since it's a really nice example of a place Git has a consistent\n>>           interface between similar commands.\n>>\n>>      +    Only discuss merge, rebase, cherry-pick, and revert for now even though\n>>      +    there are other ways that merge conflicts can happen because it's\n>>      +    awkward to talk about `am`, `apply`, and `checkout -m`.\n>>      +\n>>           Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>>      -    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>>      -    Reviewed-by: Patrick Steinhardt <ps@pks.im>\n>>      +    Helped-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n>\n> Maybe this got lost in the shuffle, but I do prefer to use\n> <ben.knoble@gmail.com> for Git these days, thanks!\n\nOops, I meant to fix that, thanks for pointing it out!\n\n>>      +    Helped-by: Patrick Steinhardt <ps@pks.im>\n>>      +    Signed-off-by: Julia Evans <julia@jvns.ca>\n>>      +    Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n>>           Signed-off-by: Julia Evans <julia@jvns.ca>\n>\n> I don't *think* we need your sign-off twice here, but maybe you\n> intended to communicate something by this ordering? I confess I'm not\n> sure what it would be ':D\n\nOops yes that was a copy paste error. Obviously I'm having a hard time\nwith my trailers as you can see :)\n\n"},{"id":"554842","messageId":"as4RAcQxknZXcBVd@pks.im","threadId":"66387","inReplyTo":"7aa0ae7ec3c1d02aa1533c27fa40f4815c03ba6e.1791816795.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-13T11:07:45Z","receivedAt":"2026-10-13T11:07:45Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:\n> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n> new file mode 100644\n> index 0000000000..3c6eaaddf8\n> --- /dev/null\n> +++ b/Documentation/gitmergeconflicts.adoc\n> @@ -0,0 +1,330 @@\n> +gitmergeconflicts(7)\n> +====================\n> +\n> +NAME\n> +----\n> +gitmergeconflicts - Guide to handling merge conflicts\n> +\n> +DESCRIPTION\n> +-----------\n> +\n> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n> +cherry-pick`, `git pull`, `git revert`, or any other command that does\n> +a merge. All of those commands use the same merge algorithm, and the\n> +process for resolving a merge conflict is always very similar.\n> +\n> +There are 3 ways to handle a merge conflict:\n> +\n> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n> +  below for details)\n> +* Stop the operation and return your branch to its original state\n> +  with the appropriate `--abort` command, for example `git merge --abort`\n> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n> +  for how to find the command to run.\n> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n> +  commit with the appropriate `--skip` command\n\nNit: the punctuation is a bit inconsistent, where the second bullet\npoint has a trailing punctuation mark but the other two don't.\n\n> +WHAT IS A MERGE CONFLICT?\n> +-------------------------\n> +\n> +When Git merges two commits together, it looks at the changes that\n> +each side has made and combines those changes. For example, if one side\n> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n> +the same file, then it can easily combine them since there's no overlap.\n> +\n> +But if both sides edited overlapping lines of the same file (for example\n> +one side edited lines 1-5 and the other edited lines 3-6), Git will\n> +not try to guess how to combine those changes. This is called a \"merge\n> +conflict\".\n> +\n> +When this happens, Git shows you both sides' edits and asks you to pick\n> +how to resolve them. It:\n> +\n> +* Stages all of the files which were successfully merged\n> +* For the files with conflicts, it marks them as conflicted, puts both\n> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n> +  that you need to resolve.\n\nSame nit here.\n\n> +[NOTE]\n> +================================\n> +Even if Git successfully merges both sides with no conflicts, it's\n> +possible to end up with code that doesn't work. For example, this can\n> +happen if one side renames a function, and the other side adds a call to\n> +the old function. This is called a \"semantic merge conflict\".\n> +================================\n\nGood callout. We may also want to spell out the consequence of this:\n\"You should always verify the result of a merge regardless of whether or\nnot it has resulted in a conflict.\".\n\n> +[[resolve]]\n> +HOW TO RESOLVE A MERGE CONFLICT\n> +-------------------------------\n> +\n> +The process for resolving a merge conflict is:\n> +\n> +1. Run `git status` to get a list of files with merge conflicts\n> +2. For each one, find the conflict markers\n> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n> +   fix the conflict\n> +3. Run `git add FILENAME` for each file to mark the conflict as resolved\n> +4. Run the appropriate `--continue` command to continue the operation\n> +   that was interrupted by the conflict, for example `git merge --continue`\n> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n> +   below for how to find the command to run.\n\nSame nit regarding punctuation. Or is this actually a thing, where you\nadd punctuation in case it's multiple sentences but not in the case\nwhere it's a single sentence, only? Maybe this is just me not being a\nnative speaker.\n\n> +[[tools]]\n> +TOOLS FOR HANDLING MERGE CONFLICTS\n> +----------------------------------\n> +\n> +Here are some ways to get extra context while handling a merge conflict:\n> +\n> +* There are many graphical \"merge tools\" for Git, which will normally\n> +  show you the different versions of the code side by side.\n> +  If you have a mergetool configured, `git mergetool` will launch it.\n> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n> +  the mergetools Git supports.\n> +\n> +* You can set the configuration variable `merge.conflictstyle=diff3`.\n> +  See <<diff3,DIFF3>> below for more.\n> +\n> +* `git log --merge -p <filename>`  will list all commits which\n\nShould we spell this out as `--patch` instead? That's way easier to grep\nin the manpage in case the reader is curious what the option does.\n\n> +[NOTE]\n> +================================\n> +`zdiff3` is an alternative to `diff3` that makes the merge conflict\n> +shorter by making it more ambiguous.\n> +================================\n\n\"making it more ambiguous\" reads rather curious. Should we maybe take\ninspiration from its documentation and instead say \"by removing matching\nlines on the two sides from the beginning or end of a conflict region\"?\n\n> +[[ours]]\n> +\"OURS\" AND \"THEIRS\"\n> +-------------------\n> +\n> +Sometimes during a merge conflict, Git will use the terms \"ours\" and\n> +\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n> +a file was `deleted by us`.\n> +\n> +\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n> +`HEAD` commit, and \"theirs\" is the other side being merged.\n\nThey may not always be commits, but they are always tree-ishs. But I\nthink it's fine to leave this as-is anyway, as the normal user is never\ngoing to encounter cases where it's not in fact a commit. And when they\ndo they probably don't need this manpage anyway.\n\nOther than this handful of nits I'm happy with this version, thanks!\n\nPatrick\n\n"},{"id":"554843","messageId":"as4RC-g606poy2WB@pks.im","threadId":"66387","inReplyTo":"f99c99f955a101d1aa8c55c0689e3c1230e3d303.1791816795.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-10-13T11:07:55Z","receivedAt":"2026-10-13T11:07:55Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Oct 12, 2026 at 02:53:14PM +0000, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans <julia@jvns.ca>\n> \n> Remove the discussion of merge conflicts and replace it with a link to\n> the guide.\n\nNit: you don't really change the discussion anymore, so this commit\nmessage is inaccurate by now.\n\nPatrick\n\n"},{"id":"555064","messageId":"89df0444-1447-4267-9e28-bc4dc70b0478@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqwlrm7pii.fsf@gitster.g","subject":"Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-14T19:24:13Z","receivedAt":"2026-10-14T19:24:13Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Mon, Oct 12, 2026, at 2:16 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> From: Julia Evans <julia@jvns.ca>\n>>\n>> Introduce a new page, `gitmergeconflicts`, that explains the process of\n>> handling a merge conflict in a way that addresses the following issues,\n>> which came from feedback from Git users on the current explanation of\n>> merge conflicts in the `git merge` man page:\n>>\n>> - The process for resolving a merge conflict is only explained in the\n>> ...\n>> - It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n>\n> It looks a bit annoying that these sentences in the enumeration all\n> lack their full stops.\n\nSure, will fix.\n\n>> Only discuss merge, rebase, cherry-pick, and revert for now even though\n>> there are other ways that merge conflicts can happen because it's\n>> awkward to talk about `am`, `apply`, and `checkout -m`.\n>\n> I do not know \"because it's awkward\" is a good justification,\n> though.  \"awkward\" why?\n\nIt's because `apply` and `am` can also apply patches, and that's a whole\nseparate topic than explaining the 3-way merge. I think explaining the\ndifference between applying a patch and doing a 3-way merge could\nbe interesting to do in the future but this is already quite a big patch\nseries.\n\n> It might be tempting to omit some commands that are less common for\n> new users, but we are touching the main part of the technical manual\n> that are meant ot be used by everybody, so that is not a good reason\n> to choose covering some but not others.\n>\n> I however agree that it is better to avoid appearing to be complete\n> and leaving others (including future ones we add) with \"any other\n> command that does a merge\" as this round of document gives.\n>\n>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n>> ...\n>> +There are 3 ways to handle a merge conflict:\n>> +\n>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n>> +  below for details)\n>> +* Stop the operation and return your branch to its original state\n>> +  with the appropriate `--abort` command, for example `git merge --abort`\n>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n>> +  for how to find the command to run.\n>> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n>> +  commit with the appropriate `--skip` command\n>\n> The third entry is a nice addition.  multi-step anything are the\n> same, including revert, right?  I'd recommend updating it to\n> something like \"if you are in a multi-step operation like `rebase`\"\n> in the same spirit as the \"or any other command\" change you made at\n> the beginning of this file.\n\nDone.\n\n>> +When there's a merge conflict, Git will update the conflicted file\n>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n>> +For example, here's a merge conflict where both sides edited a list of\n>> +fruits in different ways -- one side added \"cherry\" and the other side\n>> +added \"banana\":\n>\n> You added \"-- one side added ...\" at the end, which I think sends a\n> wrong message.  With rcs-merge style conflict, you cannot simply\n> tell, because it is ambiguous.  The original may have had both\n> banana and cherry, in which case the sample output shows the result\n> of one side removing banana and the other side removing cherry.\n\nMake sense, will replace \"added\" with \"has\".\n\n>> +[[diff3]]\n>> +DIFF3\n>> +-----\n>> +\n>> +By default, Git doesn't include the original code when formatting\n>> +a merge conflict. To include the original code, you can set the\n>> +configuration option `merge.conflictstyle` to `diff3`.\n>> +This extra context can make it much easier to understand what's\n>> +happening in a merge conflict.\n>> +\n>> +Here's an example of what a merge conflict would look like when using\n>> +`diff3`. There's an extra section (between `|||||||` and `=======`)\n>> +with the original code.\n>> +\n>> +With this view, you can see that both sides fixed a spelling\n>> +mistake in \"mango\", and each added one fruit to the list.\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",\n>> +    \"mango\",\n>> +||||||| 1c22e48\n>> +    \"mangoooo\",\n>> +=======\n>> +    \"banana\",\n>> +    \"mango\",\n>> +>>>>>>> add-fruit\n>> +    \"orange\",\n>> +]\n>> +----\n>\n> THis is a great example.  \n>\n> But an even better example would be to give this:\n>\n>         FRUITS = [\n>             \"apple\",\n>         <<<<<<< HEAD\n>             \"cherry\",\n>             \"mango\",\n>         ||||||| 1c22e48\n>             \"banana\",\n>             \"cherry\",\n>             \"mangoooo\",\n>         =======\n>             \"banana\",\n>             \"mango\",\n>         >>>>>>> add-fruit\n>             \"orange\",\n>         ]\n>\n> and tell the readers that that the correct resolution is to have\n> \"apply, mango, orange\", as each of cherry and banana was removed by\n> one side while the other side did not touch it.  Having cherry and\n> banana in the result is a tempting but not always correct conclusion\n> unexperienced people would draw from the rcs-merge style output that\n> is ambiguous, and here is a great place to teach it in this flow.\n\nThanks, this is a much better example, for the reasons you say. Will use it.\n\nI always appreciate thinking carefully about which examples to give,\nit's so important.\n\n> Especially because it would make it stand out that the point of\n> diff3's verboseness compared to the rcs-merge output is to\n> disambiguate two cases.  If you start from ABCmO and one side has\n> ABMO while the other side has ACMO, the right resolution would be\n> AMO (the above case I added), but if your starting point were AmO\n> and the two sides ends with ABMO and ACMO respectively, the right\n> resolution would be ABCMO.  The rcs-merge output does not tell you\n> which is more likely to be correct, diff3 disambiguates these two\n> cases by being more verbose.\n>\n> And telling that value of diff3 is about disambiguating is valuable\n> when ...\n>\n>> +[NOTE]\n>> +================================\n>> +`zdiff3` is an alternative to `diff3` that makes the merge conflict\n>> +shorter by making it more ambiguous.\n>> +================================\n>\n> ... this note tells the readers that zdiff3 is a ambigous variant of\n> diff3, hinting its flaw.\n\n"},{"id":"555068","messageId":"695c53d0-6e14-4f4c-a3be-33a8e331f563@app.fastmail.com","threadId":"66387","inReplyTo":"as4RAcQxknZXcBVd@pks.im","subject":"Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-14T19:50:20Z","receivedAt":"2026-10-14T19:50:20Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\nOn Tue, Oct 13, 2026, at 7:07 AM, Patrick Steinhardt wrote:\n> On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:\n>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\n>> new file mode 100644\n>> index 0000000000..3c6eaaddf8\n>> --- /dev/null\n>> +++ b/Documentation/gitmergeconflicts.adoc\n>> @@ -0,0 +1,330 @@\n>> +gitmergeconflicts(7)\n>> +====================\n>> +\n>> +NAME\n>> +----\n>> +gitmergeconflicts - Guide to handling merge conflicts\n>> +\n>> +DESCRIPTION\n>> +-----------\n>> +\n>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git\n>> +cherry-pick`, `git pull`, `git revert`, or any other command that does\n>> +a merge. All of those commands use the same merge algorithm, and the\n>> +process for resolving a merge conflict is always very similar.\n>> +\n>> +There are 3 ways to handle a merge conflict:\n>> +\n>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n>> +  below for details)\n>> +* Stop the operation and return your branch to its original state\n>> +  with the appropriate `--abort` command, for example `git merge --abort`\n>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n>> +  for how to find the command to run.\n>> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n>> +  commit with the appropriate `--skip` command\n>\n> Nit: the punctuation is a bit inconsistent, where the second bullet\n> point has a trailing punctuation mark but the other two don't.\n\nThanks, tried to make this a bit more consistent. I think I have some slightly\nidiosyncratic personal rules for punctuation in bulleted lists that I don't\nfeel very attached to.\n\n>> +WHAT IS A MERGE CONFLICT?\n>> +-------------------------\n>> +\n>> +When Git merges two commits together, it looks at the changes that\n>> +each side has made and combines those changes. For example, if one side\n>> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n>> +the same file, then it can easily combine them since there's no overlap.\n>> +\n>> +But if both sides edited overlapping lines of the same file (for example\n>> +one side edited lines 1-5 and the other edited lines 3-6), Git will\n>> +not try to guess how to combine those changes. This is called a \"merge\n>> +conflict\".\n>> +\n>> +When this happens, Git shows you both sides' edits and asks you to pick\n>> +how to resolve them. It:\n>> +\n>> +* Stages all of the files which were successfully merged\n>> +* For the files with conflicts, it marks them as conflicted, puts both\n>> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n>> +  that you need to resolve.\n>\n> Same nit here.\n\n>> +[NOTE]\n>> +================================\n>> +Even if Git successfully merges both sides with no conflicts, it's\n>> +possible to end up with code that doesn't work. For example, this can\n>> +happen if one side renames a function, and the other side adds a call to\n>> +the old function. This is called a \"semantic merge conflict\".\n>> +================================\n>\n> Good callout. We may also want to spell out the consequence of this:\n> \"You should always verify the result of a merge regardless of whether or\n> not it has resulted in a conflict.\".\n\nI think we should let people use their own judgment about how to use this\ninformation.\n\n>> +[[resolve]]\n>> +HOW TO RESOLVE A MERGE CONFLICT\n>> +-------------------------------\n>> +\n>> +The process for resolving a merge conflict is:\n>> +\n>> +1. Run `git status` to get a list of files with merge conflicts\n>> +2. For each one, find the conflict markers\n>> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n>> +   fix the conflict\n>> +3. Run `git add FILENAME` for each file to mark the conflict as resolved\n>> +4. Run the appropriate `--continue` command to continue the operation\n>> +   that was interrupted by the conflict, for example `git merge --continue`\n>> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n>> +   below for how to find the command to run.\n>\n> Same nit regarding punctuation. Or is this actually a thing, where you\n> add punctuation in case it's multiple sentences but not in the case\n> where it's a single sentence, only? Maybe this is just me not being a\n> native speaker.\n>\n>> +[[tools]]\n>> +TOOLS FOR HANDLING MERGE CONFLICTS\n>> +----------------------------------\n>> +\n>> +Here are some ways to get extra context while handling a merge conflict:\n>> +\n>> +* There are many graphical \"merge tools\" for Git, which will normally\n>> +  show you the different versions of the code side by side.\n>> +  If you have a mergetool configured, `git mergetool` will launch it.\n>> +  See also `merge.tool` in linkgit:git-config[1] for a list of\n>> +  the mergetools Git supports.\n>> +\n>> +* You can set the configuration variable `merge.conflictstyle=diff3`.\n>> +  See <<diff3,DIFF3>> below for more.\n>> +\n>> +* `git log --merge -p <filename>`  will list all commits which\n>\n> Should we spell this out as `--patch` instead? That's way easier to grep\n> in the manpage in case the reader is curious what the option does.\n\nGood idea, will do.\n\n>> +[NOTE]\n>> +================================\n>> +`zdiff3` is an alternative to `diff3` that makes the merge conflict\n>> +shorter by making it more ambiguous.\n>> +================================\n>\n> \"making it more ambiguous\" reads rather curious. Should we maybe take\n> inspiration from its documentation and instead say \"by removing matching\n> lines on the two sides from the beginning or end of a conflict region\"?\n\nHmm, I've gone back and forth a lot on how to explain zdiff3, from\n\n1. Here's how it works and here's an example to illustrate\n2. You shouldn't use it\n3. You may want to use it but be aware that it's ambiguous\n4. Here's more info about about how it works\n\nI think Junio's diff3 example does a really good job of making it clear \nwhy diff3 might be useful. The previous zdiff3 example I had that talked\nabout the pros and cons of using zdiff3 didn't feel very compelling to me\nand I don't know how to write a good one. I think a good example\nprobably does exist, but we might actually need multiple examples\n(both to show how zdiff can be useful and to show the issues).\n\nPerhaps given that we seem to not necessarily want to recommend\nzdiff3, we can just not mention zdiff3 for now and add it back later if/when\nwe feel more confident about how to explain it. I'll try just deleting the note.\n\n>> +[[ours]]\n>> +\"OURS\" AND \"THEIRS\"\n>> +-------------------\n>> +\n>> +Sometimes during a merge conflict, Git will use the terms \"ours\" and\n>> +\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n>> +a file was `deleted by us`.\n>> +\n>> +\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n>> +`HEAD` commit, and \"theirs\" is the other side being merged.\n>\n> They may not always be commits, but they are always tree-ishs. But I\n> think it's fine to leave this as-is anyway, as the normal user is never\n> going to encounter cases where it's not in fact a commit. And when they\n> do they probably don't need this manpage anyway.\n\nInteresting, I didn't know it could be something other than a commit.\n\n>\n> Other than this handful of nits I'm happy with this version, thanks!\n>\n> Patrick\n\nthanks for the review!\n\n"},{"id":"555081","messageId":"xmqqv774orze.fsf@gitster.g","threadId":"66387","inReplyTo":"89df0444-1447-4267-9e28-bc4dc70b0478@app.fastmail.com","subject":"Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-14T22:08:21Z","receivedAt":"2026-10-14T22:08:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> I do not know \"because it's awkward\" is a good justification,\n>> though.  \"awkward\" why?\n>\n> It's because `apply` and `am` can also apply patches, and that's a whole\n> separate topic than explaining the 3-way merge. I think explaining the\n> difference between applying a patch and doing a 3-way merge could\n> be interesting to do in the future but this is already quite a big patch\n> series.\n\nI do not quite follow.  \"apply -3\" is making a 3-way merge among the\nstate _your_ working tree is in, the state shown as the preimage in\nthe patch (i.e., before the patch author had the change they gave\nyou in the patch), and the state shown as the postimage in the patch\n(i.e., after the patch author made the change).\n\nIt is no different from the case where cherry-picking the change the\npatch author had stopped in conflict if (1) the machinery did find\nthe necessary preimage blobs and (2) the 3way application did stop\nin a conflict.\n\n>> I however agree that it is better to avoid appearing to be complete\n>> and leaving others (including future ones we add) with \"any other\n>> command that does a merge\" as this round of document gives.\n\nThanks.\n\n"},{"id":"556037","messageId":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH v4 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:47Z","receivedAt":"2026-10-23T14:04:47Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Handling merge conflicts is difficult, and currently Git's guidance on merge\nconflicts isn't giving users the information they need to navigate the\nprocess. As usual, the process I used to write this was to collect comments\nfrom Git users on the existing documentation, and then address those issues.\nI listed the specific issues we're aiming to solve in the first commit\nmessage in the series.\n\nThis patch series introduces a new manual page, gitmergeconflicts, which\nexplains the process of explaining a merge conflict with examples. It also\nlinks to that new page from the commands which can cause merge conflicts,\ninstead of trying to reexplain the process every time.\n\nChanged in v2:\n\n * Explain what a merge conflict is (thanks to Junio & Ben)\n * rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n   comments)\n * add git log --merge (thanks to Ben)\n * Leave most of the content of git cherry-pick as-is, to make this patch\n   set smaller (thanks to Junio)\n * remove the SYNOPSIS since hopefully that won't be required anymore by the\n   time this is merged\n * Fix a typo in git revert (s/reverted conflict/reverted commit/)\n * 's/the the/the/' (thanks to Patrick)\n * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n * squash the commit fixing the linter error (thanks to Junio)\n * list reviewers in Reviewed-by\n\nChanged in v3:\n\nThanks to all the comments from Junio.\n\n * Add signoff from Marie\n * In \"For example, here's a merge conflict where both sides edited a list\n   of\", add a little more detail about how to interpret the merge conflict\n * When we introduce a merge mention \"semantic merge conflicts\"\n * Say \"... and any other command that does a merge\" when listing commands\n   that can cause merge conflicts.\n * Reviewed-by is not the right thing, use Helped-by\n * Adjust phrasing in git revert and git cherry-pick man pages\n * Reference the \"ours\" section in \"git show :2:filename shows the \"ours\"\"\n * \"there's one file left with conflicts in it: fruits.py\" isn't precise\n   enough, instead say \"the conflicts in fruits.py haven't been marked as\n   resolved\"\n * Delete the explanation of zdiff3 and add a brief warning instead. Don't\n   be too prescriptive, we should tell people what the issue is (ambiguity)\n   instead of trying to impose our opinion.\n * Explain ||||||| when we add diff3\n * Fix example in \"EXAMPLE OF RESOLVING A MERGE CONFLICT\" to make it\n   consistent with the other examples\n * Replace \"configuration option\" with \"configuration variable\"\n * Mention --skip instead of saying \"the most common ways\", which is\n   ambiguous\n * Add a pointer to the extended AUTO_MERGE sentence\n\nChanged in v4:\n\nchanges to the content:\n\n * use Junio's much better example for diff3\n * clarify in the commit message why we're not mentioning git apply: to\n   avoid dealing with patches (thanks to Junio)\n * adjust the wording around \"multi-step operation like a rebase\" (thanks to\n   Junio)\n * Say \"see git-config for more\" in the description of zdiff3. Like Patrick\n   said the explanation of zdiff3 is not really satisfiying, but I don't\n   know how to write a satisfying explanation, and it's better to have a\n   short and obviously unsatisfying explanation than a long unsatisfying\n   one. Added a note in the commit message that perhaps this should be\n   improved in the future. (from Patrick's comment)\n\nchanges cleaning things up:\n\n * add periods at the ends of various sentences in an attempt to be more\n   consistent (thanks to Junio & Patrick)\n * Adjust the formatting around the [NOTE] to make the CI whitespace check\n   pass\n * Replace a couple of instances of \"code\" with \"lines\" (thanks to Junio)\n * Fix Ben's email address (thanks to Ben)\n * Remove the double signoff (thanks to Ben).\n * Make the cherry-pick commit message more accurate (thanks to Patrick)\n\nThanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\nand about 12 others who gave feedback on both the original git merge man\npage, as well as the proposed improvements.\n\nJulia Evans (6):\n  doc: add new gitmergeconflicts man page\n  doc: git-merge: link to new merge conflicts guide\n  doc: git-rebase: link to new merge conflicts guide\n  doc: git-revert: link to new merge conflicts guide\n  doc: git-cherry-pick: link to new merge conflicts guide\n  doc: git-pull: link to new merge conflicts guide\n\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/git-cherry-pick.adoc   |   8 +-\n Documentation/git-merge.adoc         | 125 +---------\n Documentation/git-pull.adoc          |   3 +-\n Documentation/git-rebase.adoc        |  13 +-\n Documentation/git-revert.adoc        |   5 +\n Documentation/gitmergeconflicts.adoc | 339 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 10 files changed, 366 insertions(+), 131 deletions(-)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/2237\n\nRange-diff vs v3:\n\n 1:  7aa0ae7ec3 ! 1:  486a77dbd7 doc: add new gitmergeconflicts man page\n     @@ Commit message\n      \n          - The process for resolving a merge conflict is only explained in the\n            `git merge` man page, even though there are several other commands\n     -      which can result in conflicts\n     +      which can result in conflicts.\n          - Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n            the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n            be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n            Similarly, it says \"The part before the `=======` is typically your\n            side...\", but doesn't explain what \"typically\" means.\n          - It introduces the merge format using an analogy to RCS, which very few\n     -      Git users have ever used\n     +      Git users have ever used.\n          - In \"The only clean-ups you need are to reset the index file to the\n            `HEAD` commit to reverse 2. and to clean up working tree changes made\n            by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n     -      to mean\n     +      to mean.\n          - It uses a cultural reference (\"Conflict resolution is hard; let's go\n            shopping.\") which is confusing or unfamiliar to some people. I think it\n            would be clearer for users to use a code example instead.\n     -    - It doesn't explain the difference between diff3 and zdiff3\n     -    - It sometimes uses the term \"area\" and sometimes uses the term \"hunk\"\n     +    - It doesn't explain the difference between diff3 and zdiff3.\n     +    - It sometimes uses the term \"area\" and sometimes uses the term \"hunk\".\n      \n          Also document the unified `--abort`, `--continue` workflow in one\n          place, since it's a really nice example of a place Git has a consistent\n          interface between similar commands.\n      \n          Only discuss merge, rebase, cherry-pick, and revert for now even though\n     -    there are other ways that merge conflicts can happen because it's\n     -    awkward to talk about `am`, `apply`, and `checkout -m`.\n     +    there are other ways that merge conflicts can happen to avoid getting\n     +    into the difference between applying a patch and doing a 3-way merge.\n     +\n     +    Things to potentially improve in future docs revisions:\n     +\n     +    - The explanation of zdiff3 is unsatisfying. It would be good if we\n     +      could have a clear example of a case where zdiff3 is helpful and a\n     +      case where it's harmful, and if we could give a better sense for\n     +      the reasons why users are actually choosing zdiff3 over diff3\n     +      (or the reverse) in real life.\n      \n          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n     -    Helped-by: D. Ben Knoble <ben.knoble+github@gmail.com>\n     +    Helped-by: D. Ben Knoble <ben.knoble@gmail.com>\n          Helped-by: Patrick Steinhardt <ps@pks.im>\n     -    Signed-off-by: Julia Evans <julia@jvns.ca>\n          Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  with the appropriate `--abort` command, for example `git merge --abort`\n      +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n      +  for how to find the command to run.\n     -+* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic\n     -+  commit with the appropriate `--skip` command\n     ++* Or (if you're in a multi-step operation like a rebase) skip the problematic\n     ++  commit with the appropriate `--skip` command.\n      +\n      +WHAT IS A MERGE CONFLICT?\n      +-------------------------\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +  that you need to resolve.\n      +\n      +[NOTE]\n     -+================================\n      +Even if Git successfully merges both sides with no conflicts, it's\n      +possible to end up with code that doesn't work. For example, this can\n      +happen if one side renames a function, and the other side adds a call to\n      +the old function. This is called a \"semantic merge conflict\".\n     -+================================\n      +\n      +[[markers]]\n      +MERGE CONFLICT MARKERS\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +When there's a merge conflict, Git will update the conflicted file\n      +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n      +For example, here's a merge conflict where both sides edited a list of\n     -+fruits in different ways -- one side added \"cherry\" and the other side\n     -+added \"banana\":\n     ++fruits in different ways -- one side has \"cherry\" and the other side\n     ++has \"banana\":\n      +\n      +----\n      +FRUITS = [\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +]\n      +----\n      +\n     -+The code from one side of the merge conflict is between `<<<<<<<` and\n     -+`=======`, and the code for the other side is between `=======` and\n     ++The lines from one side of the merge conflict is between `<<<<<<<` and\n     ++`=======`, and the lines from the other side is between `=======` and\n      +`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n      +of which side is which.\n      +\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +\n      +The process for resolving a merge conflict is:\n      +\n     -+1. Run `git status` to get a list of files with merge conflicts\n     ++1. Run `git status` to get a list of files with merge conflicts.\n      +2. For each one, find the conflict markers\n     -+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to\n     -+   fix the conflict\n     -+3. Run `git add FILENAME` for each file to mark the conflict as resolved\n     ++   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the file to\n     ++   fix the conflict.\n     ++3. Run `git add FILENAME` for each file to mark the conflict as resolved.\n      +4. Run the appropriate `--continue` command to continue the operation\n      +   that was interrupted by the conflict, for example `git merge --continue`\n      +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +* You can set the configuration variable `merge.conflictstyle=diff3`.\n      +  See <<diff3,DIFF3>> below for more.\n      +\n     -+* `git log --merge -p <filename>`  will list all commits which\n     ++* `git log --merge --patch <filename>`  will list all commits which\n      +  caused the merge conflict for `<filename>`, and the diff\n      +  of how they changed the file.\n      +\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +`diff3`. There's an extra section (between `|||||||` and `=======`)\n      +with the original code.\n      +\n     -+With this view, you can see that both sides fixed a spelling\n     -+mistake in \"mango\", and each added one fruit to the list.\n     -+\n      +----\n      +FRUITS = [\n      +    \"apple\",\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +    \"cherry\",\n      +    \"mango\",\n      +||||||| 1c22e48\n     ++\t\"banana\",\n     ++\t\"cherry\",\n      +    \"mangoooo\",\n      +=======\n      +    \"banana\",\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +]\n      +----\n      +\n     ++With this view, you can see that both sides fixed a spelling\n     ++mistake in \"mango\", and each removed one fruit to the list.\n     ++This makes it more clear how to resolve the merge conflict: since one\n     ++side removed `banana` and one side removed `cherry`, it would probably\n     ++make sense to remove both from the list, like this:\n     ++\n     ++----\n     ++FRUITS = [\n     ++    \"apple\",\n     ++    \"mango\",\n     ++    \"orange\",\n     ++]\n     ++----\n     ++\n      +[NOTE]\n     -+================================\n      +`zdiff3` is an alternative to `diff3` that makes the merge conflict\n     -+shorter by making it more ambiguous.\n     -+================================\n     ++shorter by making it more ambiguous. See linkgit:git-config[1] for more.\n      +\n      +[[ours]]\n      +\"OURS\" AND \"THEIRS\"\n 2:  8bdbd64ca3 = 2:  6862cb4f04 doc: git-merge: link to new merge conflicts guide\n 3:  34ba85fcad = 3:  2bd9850822 doc: git-rebase: link to new merge conflicts guide\n 4:  85e117b070 = 4:  53083b48a3 doc: git-revert: link to new merge conflicts guide\n 5:  f99c99f955 ! 5:  92cfdf260c doc: git-cherry-pick: link to new merge conflicts guide\n     @@ Metadata\n       ## Commit message ##\n          doc: git-cherry-pick: link to new merge conflicts guide\n      \n     -    Remove the discussion of merge conflicts and replace it with a link to\n     -    the guide.\n     -\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git-cherry-pick.adoc ##\n 6:  7831b77178 = 6:  bbbf44aff1 doc: git-pull: link to new merge conflicts guide\n\n-- \ngitgitgadget\n\n"},{"id":"556038","messageId":"486a77dbd78e111f66f8878594a30974c2abe53f.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:48Z","receivedAt":"2026-10-23T14:04:48Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nIntroduce a new page, `gitmergeconflicts`, that explains the process of\nhandling a merge conflict in a way that addresses the following issues,\nwhich came from feedback from Git users on the current explanation of\nmerge conflicts in the `git merge` man page:\n\n- The process for resolving a merge conflict is only explained in the\n  `git merge` man page, even though there are several other commands\n  which can result in conflicts.\n- Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n  the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n  be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n  Similarly, it says \"The part before the `=======` is typically your\n  side...\", but doesn't explain what \"typically\" means.\n- It introduces the merge format using an analogy to RCS, which very few\n  Git users have ever used.\n- In \"The only clean-ups you need are to reset the index file to the\n  `HEAD` commit to reverse 2. and to clean up working tree changes made\n  by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n  to mean.\n- It uses a cultural reference (\"Conflict resolution is hard; let's go\n  shopping.\") which is confusing or unfamiliar to some people. I think it\n  would be clearer for users to use a code example instead.\n- It doesn't explain the difference between diff3 and zdiff3.\n- It sometimes uses the term \"area\" and sometimes uses the term \"hunk\".\n\nAlso document the unified `--abort`, `--continue` workflow in one\nplace, since it's a really nice example of a place Git has a consistent\ninterface between similar commands.\n\nOnly discuss merge, rebase, cherry-pick, and revert for now even though\nthere are other ways that merge conflicts can happen to avoid getting\ninto the difference between applying a patch and doing a 3-way merge.\n\nThings to potentially improve in future docs revisions:\n\n- The explanation of zdiff3 is unsatisfying. It would be good if we\n  could have a clear example of a case where zdiff3 is helpful and a\n  case where it's harmful, and if we could give a better sense for\n  the reasons why users are actually choosing zdiff3 over diff3\n  (or the reverse) in real life.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nHelped-by: D. Ben Knoble <ben.knoble@gmail.com>\nHelped-by: Patrick Steinhardt <ps@pks.im>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/gitmergeconflicts.adoc | 339 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 5 files changed, 343 insertions(+)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\ndiff --git a/.gitattributes b/.gitattributes\nindex 26490ad60a..0a0fc950b1 100644\n--- a/.gitattributes\n+++ b/.gitattributes\n@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n /t/oid-info/* text eol=lf\n /Documentation/git-merge.adoc conflict-marker-size=32\n /Documentation/git-merge-file.adoc conflict-marker-size=32\n+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n /Documentation/gitk.adoc conflict-marker-size=32\n /Documentation/user-manual.adoc conflict-marker-size=32\n /t/t????-*.sh conflict-marker-size=32\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..bc49641dda 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\n MAN7_TXT += gitglossary.adoc\n+MAN7_TXT += gitmergeconflicts.adoc\n MAN7_TXT += gitpacking.adoc\n MAN7_TXT += gitnamespaces.adoc\n MAN7_TXT += gitremote-helpers.adoc\ndiff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\nnew file mode 100644\nindex 0000000000..bcf7d66c62\n--- /dev/null\n+++ b/Documentation/gitmergeconflicts.adoc\n@@ -0,0 +1,339 @@\n+gitmergeconflicts(7)\n+====================\n+\n+NAME\n+----\n+gitmergeconflicts - Guide to handling merge conflicts\n+\n+DESCRIPTION\n+-----------\n+\n+Merge conflicts can happen during a `git merge`, `git rebase`, `git\n+cherry-pick`, `git pull`, `git revert`, or any other command that does\n+a merge. All of those commands use the same merge algorithm, and the\n+process for resolving a merge conflict is always very similar.\n+\n+There are 3 ways to handle a merge conflict:\n+\n+* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n+  below for details)\n+* Stop the operation and return your branch to its original state\n+  with the appropriate `--abort` command, for example `git merge --abort`\n+  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n+  for how to find the command to run.\n+* Or (if you're in a multi-step operation like a rebase) skip the problematic\n+  commit with the appropriate `--skip` command.\n+\n+WHAT IS A MERGE CONFLICT?\n+-------------------------\n+\n+When Git merges two commits together, it looks at the changes that\n+each side has made and combines those changes. For example, if one side\n+edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n+the same file, then it can easily combine them since there's no overlap.\n+\n+But if both sides edited overlapping lines of the same file (for example\n+one side edited lines 1-5 and the other edited lines 3-6), Git will\n+not try to guess how to combine those changes. This is called a \"merge\n+conflict\".\n+\n+When this happens, Git shows you both sides' edits and asks you to pick\n+how to resolve them. It:\n+\n+* Stages all of the files which were successfully merged\n+* For the files with conflicts, it marks them as conflicted, puts both\n+  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n+  that you need to resolve.\n+\n+[NOTE]\n+Even if Git successfully merges both sides with no conflicts, it's\n+possible to end up with code that doesn't work. For example, this can\n+happen if one side renames a function, and the other side adds a call to\n+the old function. This is called a \"semantic merge conflict\".\n+\n+[[markers]]\n+MERGE CONFLICT MARKERS\n+----------------------\n+\n+When there's a merge conflict, Git will update the conflicted file\n+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n+For example, here's a merge conflict where both sides edited a list of\n+fruits in different ways -- one side has \"cherry\" and the other side\n+has \"banana\":\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+The lines from one side of the merge conflict is between `<<<<<<<` and\n+`=======`, and the lines from the other side is between `=======` and\n+`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n+of which side is which.\n+\n+\n+[[resolve]]\n+HOW TO RESOLVE A MERGE CONFLICT\n+-------------------------------\n+\n+The process for resolving a merge conflict is:\n+\n+1. Run `git status` to get a list of files with merge conflicts.\n+2. For each one, find the conflict markers\n+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the file to\n+   fix the conflict.\n+3. Run `git add FILENAME` for each file to mark the conflict as resolved.\n+4. Run the appropriate `--continue` command to continue the operation\n+   that was interrupted by the conflict, for example `git merge --continue`\n+   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n+   below for how to find the command to run.\n++\n+Note: During a `git merge`, `git commit` and `git merge --continue` do\n+the same thing.\n+\n+\n+[[example]]\n+EXAMPLE OF RESOLVING A MERGE CONFLICT\n+-------------------------------------\n+\n+If you see this in your code during a merge conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+Then you might edit that part of the code like this,\n+which includes the fruits from both sides of the conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"banana\",\n+    \"cherry\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[tools]]\n+TOOLS FOR HANDLING MERGE CONFLICTS\n+----------------------------------\n+\n+Here are some ways to get extra context while handling a merge conflict:\n+\n+* There are many graphical \"merge tools\" for Git, which will normally\n+  show you the different versions of the code side by side.\n+  If you have a mergetool configured, `git mergetool` will launch it.\n+  See also `merge.tool` in linkgit:git-config[1] for a list of\n+  the mergetools Git supports.\n+\n+* You can set the configuration variable `merge.conflictstyle=diff3`.\n+  See <<diff3,DIFF3>> below for more.\n+\n+* `git log --merge --patch <filename>`  will list all commits which\n+  caused the merge conflict for `<filename>`, and the diff\n+  of how they changed the file.\n+\n+* Look at the original files.  `git show :1:filename` shows the\n+  common ancestor, `git show :2:filename` shows the \"ours\"\n+  version, and `git show :3:filename` shows the \"theirs\"\n+  version. See <<ours,\"OURS\" AND \"THEIRS\">> below for more on\n+  \"ours\" and \"theirs\".\n+\n+Here are some ways to track your progress while handling a conflict:\n+\n+* Use `git status` to get a list of files with conflicts\n+\n+* Use `git diff --check` to make sure you haven't left any merge\n+  conflict markers in a file by accident. It will print \"leftover\n+  conflict marker\" if it finds any.\n+\n+* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n+  resolve the conflicts.\n+  See <<automerge,EXAMPLE OF USING `AUTO_MERGE`>> below for more.\n+\n+[[git_status]]\n+EXAMPLE: GIT STATUS OUTPUT\n+--------------------------\n+\n+When you're in a merge conflict, you can find out what commands to run\n+to handle the conflict by running `git status`.\n+\n+For example, this `git status` output tells you that:\n+\n+* `git rebase --abort` will safely bring your branch back to its\n+  original state\n+* you should run `git rebase --continue` when you're done resolving all\n+  the conflicts\n+* the conflicts in `fruits.py` haven't been marked as resolved\n+\n+----\n+$ git status\n+You are currently rebasing branch 'main' on '58a9fcc'.\n+  (fix conflicts and then run \"git rebase --continue\")\n+  (use \"git rebase --skip\" to skip this patch)\n+  (use \"git rebase --abort\" to check out the original branch)\n+\n+Unmerged paths:\n+  (use \"git restore --staged <file>...\" to unstage)\n+  (use \"git add <file>...\" to mark resolution)\n+        both modified:   fruits.py\n+----\n+\n+\n+[[diff3]]\n+DIFF3\n+-----\n+\n+By default, Git doesn't include the original code when formatting\n+a merge conflict. To include the original code, you can set the\n+configuration option `merge.conflictstyle` to `diff3`.\n+This extra context can make it much easier to understand what's\n+happening in a merge conflict.\n+\n+Here's an example of what a merge conflict would look like when using\n+`diff3`. There's an extra section (between `|||||||` and `=======`)\n+with the original code.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+||||||| 1c22e48\n+\t\"banana\",\n+\t\"cherry\",\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+With this view, you can see that both sides fixed a spelling\n+mistake in \"mango\", and each removed one fruit to the list.\n+This makes it more clear how to resolve the merge conflict: since one\n+side removed `banana` and one side removed `cherry`, it would probably\n+make sense to remove both from the list, like this:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+[NOTE]\n+`zdiff3` is an alternative to `diff3` that makes the merge conflict\n+shorter by making it more ambiguous. See linkgit:git-config[1] for more.\n+\n+[[ours]]\n+\"OURS\" AND \"THEIRS\"\n+-------------------\n+\n+Sometimes during a merge conflict, Git will use the terms \"ours\" and\n+\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n+a file was `deleted by us`.\n+\n+\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n+`HEAD` commit, and \"theirs\" is the other side being merged.\n+\n+The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n+from the \"ours\" side, and the second part (between `=======` and\n+`>>>>>>>`) is from the \"theirs\" side.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",                      <- ours\n+=======\n+    \"banana\",                      <- theirs\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n+from the branch you're rebasing on (for instance `main` in `git rebase\n+main`).\n+\n+These terms in Git all mean the same thing when dealing with a merge\n+conflict:\n+\n+* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n+* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n+* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n+\n+If you're confused about what something like \"deleted by us\" means, it's\n+often easiest to use some of the tools from\n+<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n+Finding the commit that deleted the file and seeing why is usually more\n+helpful than trying to abstractly reason through what \"us\" means.\n+\n+[[automerge]]\n+EXAMPLE OF USING `AUTO_MERGE`\n+-----------------------------\n+\n+`git diff AUTO_MERGE` will show what changes you've made so far to\n+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n+merge. It contains the result of running the merge algorithm.\n+\n+For example, if we resolved the conflict by adding both \"banana\" and\n+\"cherry\" in order, the diff would look like this:\n+\n+----\n+ FRUITS = [\n+     \"apple\",\n+-<<<<<<< HEAD\n+-    \"cherry\",\n+-=======\n+     \"banana\",\n+->>>>>>> add-fruit\n++    \"cherry\",\n+     \"mango\",\n+     \"orange\",\n+ ]\n+----\n+\n+[NOTE]\n+`AUTO_MERGE` is only set if you're using the default Git merge algorithm.\n+\n+\n+SEE ALSO\n+--------\n+\n+linkgit:git-revert[1]\n+linkgit:git-merge[1]\n+linkgit:git-rebase[1]\n+linkgit:git-cherry-pick[1]\n+linkgit:git-pull[1]\n+linkgit:git-diff[1]\n+\n+GIT\n+---\n+\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f4854f802d..51647957e0 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -202,6 +202,7 @@ manpages = {\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n   'gitpacking.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n   'gitremote-helpers.adoc' : 7,\n   'gitrevisions.adoc' : 7,\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..f6e49c3c85 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -232,6 +232,7 @@ githooks                                userinterfaces\n gitignore                               userinterfaces\n gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n+gitmergeconflicts                       guide\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n gitprotocol-capabilities                developerinterfaces\n-- \ngitgitgadget\n\n\n"},{"id":"556039","messageId":"6862cb4f04350e5b4443c1b93539794660cc56fe.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 2/6] doc: git-merge: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:49Z","receivedAt":"2026-10-23T14:04:49Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAll of the info about merge conflicts has been moved to the new guide\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-merge.adoc | 125 +----------------------------------\n 1 file changed, 3 insertions(+), 122 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex a055384ad6..5b7b41cd10 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation,\n A merge stops if there's a conflict that cannot be resolved\n automatically or if `--no-commit` was provided when initiating the\n merge. At that point you can run `git merge --abort` or `git merge\n---continue`.\n+--continue`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n `git merge --abort` will abort the merge process and try to reconstruct\n the pre-merge state. However, if there were uncommitted changes when the\n@@ -231,127 +232,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-HOW CONFLICTS ARE PRESENTED\n----------------------------\n-\n-During a merge, the working tree files are updated to reflect the result\n-of the merge.  Among the changes made to the common ancestor's version,\n-non-overlapping ones (that is, you changed an area of the file while the\n-other side left that area intact, or vice versa) are incorporated in the\n-final result verbatim.  When both sides made changes to the same area,\n-however, Git cannot randomly pick one side over the other, and asks you to\n-resolve it by leaving what both sides did to that area.\n-\n-By default, Git uses the same style as the one used by the \"merge\" program\n-from the RCS suite to present such a conflicted hunk, like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-The area where a pair of conflicting changes happened is marked with markers\n-+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n-is typically your side, and the part afterwards is typically their side.\n-\n-The default format does not show what the original said in the conflicting\n-area.  You cannot tell how many lines are deleted and replaced with\n-Barbie's remark on your side.  The only thing you can tell is that your\n-side wants to say it is hard and you'd prefer to go shopping, while the\n-other side wants to claim it is easy.\n-\n-An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n-style, the above conflict may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-<<<<<<< yours:sample.txt\n-or cleanly resolved because both sides changed the same way.\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-or cleanly resolved because both sides changed the same way.\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-while in `zdiff3` style, it may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n-another +|||||||+ marker that is followed by the original text.  You can\n-tell that the original just stated a fact, and your side simply gave in to\n-that statement and gave up, while the other side tried to have a more\n-positive attitude.  You can sometimes come up with a better resolution by\n-viewing the original.\n-\n-\n-HOW TO RESOLVE CONFLICTS\n-------------------------\n-\n-After seeing a conflict, you can do two things:\n-\n- * Decide not to merge.  The only clean-ups you need are to reset\n-   the index file to the `HEAD` commit to reverse 2. and to clean\n-   up working tree changes made by 2. and 3.; `git merge --abort`\n-   can be used for this.\n-\n- * Resolve the conflicts.  Git will mark the conflicts in\n-   the working tree.  Edit the files into shape and\n-   `git add` them to the index.  Use `git commit` or\n-   `git merge --continue` to seal the deal. The latter command\n-   checks whether there is a (interrupted) merge in progress\n-   before calling `git commit`.\n-\n-You can work through the conflict with a number of tools:\n-\n- * Use a mergetool.  `git mergetool` to launch a graphical\n-   mergetool which will work through the merge with you.\n-\n- * Look at the diffs.  `git diff` will show a three-way diff,\n-   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n-   versions. `git diff AUTO_MERGE` will show what changes you've\n-   made so far to resolve textual conflicts.\n-\n- * Look at the diffs from each branch. `git log --merge -p <path>`\n-   will show diffs first for the `HEAD` version and then the\n-   `MERGE_HEAD` version.\n-\n- * Look at the originals.  `git show :1:filename` shows the\n-   common ancestor, `git show :2:filename` shows the `HEAD`\n-   version, and `git show :3:filename` shows the `MERGE_HEAD`\n-   version.\n-\n-\n EXAMPLES\n --------\n \n@@ -406,6 +286,7 @@ linkgit:git-reset[1],\n linkgit:git-diff[1], linkgit:git-ls-files[1],\n linkgit:git-add[1], linkgit:git-rm[1],\n linkgit:git-mergetool[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556040","messageId":"2bd9850822605324882794e43773c4be9127bc9e.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 3/6] doc: git-rebase: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:50Z","receivedAt":"2026-10-23T14:04:50Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove some of the detail about how to handle a merge conflict, since\nit's explained in detail in the new guide, and there probably isn't\nenough detail anyway.\n\nLeave the steps since rebase is special and has a `--skip` option which\nthe other commands which cause merge conflicts don't have.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-rebase.adoc | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..da70aff498 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the\n first problematic commit and leave conflict markers. If this happens, you can do\n one of these things:\n \n-1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)\n-   and make edits to resolve the conflict. For each file you edit, you need to\n-   tell Git that the conflict has been resolved. You can mark the conflict as\n-   resolved with  `git add <filename>`. After resolving all of the conflicts,\n+1. Resolve the conflict. After resolving all of the conflicts,\n    you can continue the rebasing process with\n \n    git rebase --continue\n@@ -62,6 +59,9 @@ one of these things:\n \n    git rebase --skip\n \n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a full guide to handling merge conflicts.\n+\n If you don't specify an `<upstream>` to rebase onto, the upstream configured in\n `branch.<name>.remote` and `branch.<name>.merge` options will be used (see\n linkgit:git-config[1] for details) and the `--fork-point` option is\n@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[]\n include::config/rebase.adoc[]\n include::config/sequencer.adoc[]\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitmergeconflicts[7]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \ngitgitgadget\n\n\n"},{"id":"556041","messageId":"53083b48a3177b1899757d0682ebdf7167af00f5.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 4/6] doc: git-revert: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:51Z","receivedAt":"2026-10-23T14:04:51Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-revert.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e63..bb0f859f66 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n+Reverting a commit may result in a merge conflict.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n+\n OPTIONS\n -------\n <commit>...::\n@@ -162,6 +166,7 @@ include::config/revert.adoc[]\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556042","messageId":"92cfdf260ccb07bdf5d255c8de3813d472610be4.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:52Z","receivedAt":"2026-10-23T14:04:52Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-cherry-pick.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex f4cd8b9db7..069e434961 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -19,8 +19,7 @@ Given one or more existing commits, apply the change each one\n introduces, recording a new commit for each.  This requires your\n working tree to be clean (no modifications from the HEAD commit).\n \n-When it is not obvious how to apply a change, the following\n-happens:\n+When a merge conflict happens:\n \n 1. The current branch and `HEAD` pointer stay at the last commit\n    successfully made.\n@@ -36,8 +35,8 @@ happens:\n    conflict markers `<<<<<<<` and `>>>>>>>`.\n 5. No other modifications are made.\n \n-See linkgit:git-merge[1] for some hints on resolving such\n-conflicts.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n@@ -259,6 +258,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n SEE ALSO\n --------\n linkgit:git-revert[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556043","messageId":"bbbf44aff15ab10b67e2f101682ca973ebe99079.1792764293.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"[PATCH v4 6/6] doc: git-pull: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-23T14:04:53Z","receivedAt":"2026-10-23T14:04:53Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-pull.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 88f4fd3926..73f6d460bb 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n \n If there's a merge conflict during the merge or rebase that you don't\n want to handle, you can safely abort it with `git merge --abort` or\n-`git rebase --abort`.\n+`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"556045","messageId":"254688CB-AD21-4283-AE19-F1061C90C6B3@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-23T14:18:54Z","receivedAt":"2026-10-23T14:18:54Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"> Le 23 oct. 2026 à 10:04, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :\n> \n> ﻿Handling merge conflicts is difficult, and currently Git's guidance on merge\n> conflicts isn't giving users the information they need to navigate the\n> process. As usual, the process I used to write this was to collect comments\n> from Git users on the existing documentation, and then address those issues.\n> I listed the specific issues we're aiming to solve in the first commit\n> message in the series.\n> \n> This patch series introduces a new manual page, gitmergeconflicts, which\n> explains the process of explaining a merge conflict with examples. It also\n> links to that new page from the commands which can cause merge conflicts,\n> instead of trying to reexplain the process every time.\n> \n> Changed in v2:\n> \n> * Explain what a merge conflict is (thanks to Junio & Ben)\n> * rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n>   comments)\n> * add git log --merge (thanks to Ben)\n> * Leave most of the content of git cherry-pick as-is, to make this patch\n>   set smaller (thanks to Junio)\n> * remove the SYNOPSIS since hopefully that won't be required anymore by the\n>   time this is merged\n> * Fix a typo in git revert (s/reverted conflict/reverted commit/)\n> * 's/the the/the/' (thanks to Patrick)\n> * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n> * squash the commit fixing the linter error (thanks to Junio)\n> * list reviewers in Reviewed-by\n> \n> Changed in v3:\n> \n> Thanks to all the comments from Junio.\n> \n> * Add signoff from Marie\n> * In \"For example, here's a merge conflict where both sides edited a list\n>   of\", add a little more detail about how to interpret the merge conflict\n> * When we introduce a merge mention \"semantic merge conflicts\"\n> * Say \"... and any other command that does a merge\" when listing commands\n>   that can cause merge conflicts.\n> * Reviewed-by is not the right thing, use Helped-by\n> * Adjust phrasing in git revert and git cherry-pick man pages\n> * Reference the \"ours\" section in \"git show :2:filename shows the \"ours\"\"\n> * \"there's one file left with conflicts in it: fruits.py\" isn't precise\n>   enough, instead say \"the conflicts in fruits.py haven't been marked as\n>   resolved\"\n> * Delete the explanation of zdiff3 and add a brief warning instead. Don't\n>   be too prescriptive, we should tell people what the issue is (ambiguity)\n>   instead of trying to impose our opinion.\n> * Explain ||||||| when we add diff3\n> * Fix example in \"EXAMPLE OF RESOLVING A MERGE CONFLICT\" to make it\n>   consistent with the other examples\n> * Replace \"configuration option\" with \"configuration variable\"\n> * Mention --skip instead of saying \"the most common ways\", which is\n>   ambiguous\n> * Add a pointer to the extended AUTO_MERGE sentence\n> \n> Changed in v4:\n> \n> changes to the content:\n> \n> * use Junio's much better example for diff3\n> * clarify in the commit message why we're not mentioning git apply: to\n>   avoid dealing with patches (thanks to Junio)\n> * adjust the wording around \"multi-step operation like a rebase\" (thanks to\n>   Junio)\n> * Say \"see git-config for more\" in the description of zdiff3. Like Patrick\n>   said the explanation of zdiff3 is not really satisfiying, but I don't\n>   know how to write a satisfying explanation, and it's better to have a\n>   short and obviously unsatisfying explanation than a long unsatisfying\n>   one. Added a note in the commit message that perhaps this should be\n>   improved in the future. (from Patrick's comment)\n> \n> changes cleaning things up:\n> \n> * add periods at the ends of various sentences in an attempt to be more\n>   consistent (thanks to Junio & Patrick)\n> * Adjust the formatting around the [NOTE] to make the CI whitespace check\n>   pass\n> * Replace a couple of instances of \"code\" with \"lines\" (thanks to Junio)\n> * Fix Ben's email address (thanks to Ben)\n> * Remove the double signoff (thanks to Ben).\n> * Make the cherry-pick commit message more accurate (thanks to Patrick)\n> \n> Thanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\n> and about 12 others who gave feedback on both the original git merge man\n> page, as well as the proposed improvements.\n\nI’m happy with this version based on the range-diff, and\nI suspect we are reaching the point of diminishing returns. \n"},{"id":"556071","messageId":"xmqqld7o9zl4.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-23T16:00:23Z","receivedAt":"2026-10-23T16:00:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>      @@ Documentation/gitmergeconflicts.adoc (new)\n>       +    \"cherry\",\n>       +    \"mango\",\n>       +||||||| 1c22e48\n>      ++\t\"banana\",\n>      ++\t\"cherry\",\n>       +    \"mangoooo\",\n>       +=======\n\nIs it intended to use different indentation style for the entries to\nbe removed from the list, or is it a simple mistake?\n\n>       +    \"banana\",\n>      @@ Documentation/gitmergeconflicts.adoc (new)\n>       +]\n>       +----\n>       +\n>      ++With this view, you can see that both sides fixed a spelling\n>      ++mistake in \"mango\", and each removed one fruit to the list.\n\n\"removed one fruit *from* the list\", no?\n\nI'll block time to read the whole thing over later today.  Thanks.\n\n"},{"id":"556072","messageId":"xmqqh5ic9zas.fsf@gitster.g","threadId":"66387","inReplyTo":"pull.2237.v4.git.1792764293.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-23T16:06:35Z","receivedAt":"2026-10-23T16:06:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Handling merge conflicts is difficult, and currently Git's guidance on merge\n> conflicts isn't giving users the information they need to navigate the\n> process. As usual, the process I used to write this was to collect comments\n> from Git users on the existing documentation, and then address those issues.\n> I listed the specific issues we're aiming to solve in the first commit\n> message in the series.\n\n$ make check-docs\nGIT_VERSION=2.56.0.rc2.6.gf97f562a2c\nmake -C Documentation lint-docs\nmake[1]: Entering directory '/home/gitster/w/git/Documentation'\n    LINT MAN SEC gitmergeconflicts.adoc\ngitmergeconflicts.adoc:339: has no required 'SYNOPSIS' section!\n\n\n\n"},{"id":"556073","messageId":"xmqqcxt09yqw.fsf@gitster.g","threadId":"66387","inReplyTo":"xmqqh5ic9zas.fsf@gitster.g","subject":"Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-23T16:18:31Z","receivedAt":"2026-10-23T16:18:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> Handling merge conflicts is difficult, and currently Git's guidance on merge\n>> conflicts isn't giving users the information they need to navigate the\n>> process. As usual, the process I used to write this was to collect comments\n>> from Git users on the existing documentation, and then address those issues.\n>> I listed the specific issues we're aiming to solve in the first commit\n>> message in the series.\n>\n> $ make check-docs\n> GIT_VERSION=2.56.0.rc2.6.gf97f562a2c\n> make -C Documentation lint-docs\n> make[1]: Entering directory '/home/gitster/w/git/Documentation'\n>     LINT MAN SEC gitmergeconflicts.adoc\n> gitmergeconflicts.adoc:339: has no required 'SYNOPSIS' section!\n\nAh, nevermind. Merge to 'seen' is (and has been) taking care of this\nalready.\n\n\n"},{"id":"556102","messageId":"xmqqtsmc44c1.fsf@gitster.g","threadId":"66387","inReplyTo":"486a77dbd78e111f66f8878594a30974c2abe53f.1792764293.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-23T19:14:22Z","receivedAt":"2026-10-23T19:14:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Things to potentially improve in future docs revisions:\n>\n> - The explanation of zdiff3 is unsatisfying. It would be good if we\n>   could have a clear example of a case where zdiff3 is helpful and a\n>   case where it's harmful, and if we could give a better sense for\n>   the reasons why users are actually choosing zdiff3 over diff3\n>   (or the reverse) in real life.\n\nIs this a stale comment?  I think you reduced this to just a side\nnote that says `shoter but ambiguous`, which is probably good\nenough.\n\n> +[[diff3]]\n> +DIFF3\n> +-----\n> +\n> +By default, Git doesn't include the original code when formatting\n> +a merge conflict. To include the original code, you can set the\n> +configuration option `merge.conflictstyle` to `diff3`.\n> +This extra context can make it much easier to understand what's\n> +happening in a merge conflict.\n> +\n> +Here's an example of what a merge conflict would look like when using\n> +`diff3`. There's an extra section (between `|||||||` and `=======`)\n> +with the original code.\n> +\n> +----\n> +FRUITS = [\n> +    \"apple\",\n> +<<<<<<< HEAD\n> +    \"cherry\",\n> +    \"mango\",\n> +||||||| 1c22e48\n> +\t\"banana\",\n> +\t\"cherry\",\n\nThese two should be indented with spaces the same way as all the\nother lines in this list.\n\n> +    \"mangoooo\",\n> +=======\n> +    \"banana\",\n> +    \"mango\",\n> +>>>>>>> add-fruit\n> +    \"orange\",\n> +]\n> +----\n> +\n> +With this view, you can see that both sides fixed a spelling\n> +mistake in \"mango\", and each removed one fruit to the list.\n\n\", and each removed one from the list\", I think.\n\n> +This makes it more clear how to resolve the merge conflict: since one\n> +side removed `banana` and one side removed `cherry`, it would probably\n> +make sense to remove both from the list, like this:\n\nThe reason why removal becomes the correct resolution is not just\none side removed, but the fact that the other side did not touch\nwhat was removed by one side.  The \"indifference by the other\" is\nwhat makes one's removal the preferred action by the semantics of\n3-way merge.\n\nSo, let's rewrite the reason a bit more tightly.\n\n    since one side removed `banana` while the other side did not\n    touch, and the same happend to `cherry`, it makes sense to\n    remove both from the list ...\n\nor somethig like that.\n\nOther than that, I did not see anything questionable in the 6\npatches.\n\n"},{"id":"556331","messageId":"2564bcc2-2f78-4ea2-9b6f-c033e95983d8@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqtsmc44c1.fsf@gitster.g","subject":"Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-26T12:35:47Z","receivedAt":"2026-10-26T12:35:47Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Fri, Oct 23, 2026, at 3:14 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> Things to potentially improve in future docs revisions:\n>>\n>> - The explanation of zdiff3 is unsatisfying. It would be good if we\n>>   could have a clear example of a case where zdiff3 is helpful and a\n>>   case where it's harmful, and if we could give a better sense for\n>>   the reasons why users are actually choosing zdiff3 over diff3\n>>   (or the reverse) in real life.\n>\n> Is this a stale comment?  I think you reduced this to just a side\n> note that says `shoter but ambiguous`, which is probably good\n> enough.\n\nIt's not, but I'll delete it anyway because I don't think it's adding much.\n\n>> +[[diff3]]\n>> +DIFF3\n>> +-----\n>> +\n>> +By default, Git doesn't include the original code when formatting\n>> +a merge conflict. To include the original code, you can set the\n>> +configuration option `merge.conflictstyle` to `diff3`.\n>> +This extra context can make it much easier to understand what's\n>> +happening in a merge conflict.\n>> +\n>> +Here's an example of what a merge conflict would look like when using\n>> +`diff3`. There's an extra section (between `|||||||` and `=======`)\n>> +with the original code.\n>> +\n>> +----\n>> +FRUITS = [\n>> +    \"apple\",\n>> +<<<<<<< HEAD\n>> +    \"cherry\",\n>> +    \"mango\",\n>> +||||||| 1c22e48\n>> +\t\"banana\",\n>> +\t\"cherry\",\n>\n> These two should be indented with spaces the same way as all the\n> other lines in this list.\n\nWill fix, thanks.\n\n>> +    \"mangoooo\",\n>> +=======\n>> +    \"banana\",\n>> +    \"mango\",\n>> +>>>>>>> add-fruit\n>> +    \"orange\",\n>> +]\n>> +----\n>> +\n>> +With this view, you can see that both sides fixed a spelling\n>> +mistake in \"mango\", and each removed one fruit to the list.\n>\n> \", and each removed one from the list\", I think.\n\nThanks, will fix.\n\n>> +This makes it more clear how to resolve the merge conflict: since one\n>> +side removed `banana` and one side removed `cherry`, it would probably\n>> +make sense to remove both from the list, like this:\n>\n> The reason why removal becomes the correct resolution is not just\n> one side removed, but the fact that the other side did not touch\n> what was removed by one side.  The \"indifference by the other\" is\n> what makes one's removal the preferred action by the semantics of\n> 3-way merge.\n>\n> So, let's rewrite the reason a bit more tightly.\n>\n>     since one side removed `banana` while the other side did not\n>     touch, and the same happend to `cherry`, it makes sense to\n>     remove both from the list ...\n\nI tried to edit this (like below) but only ended up removing \"probably\".\nBut \"probably\" was there for a reason, since this is a made up example\nand in the real world you would really need to apply some judgement\nto know what the right thing to do is. I left it as is.\n\n-side removed `banana` and one side removed `cherry`, it would probably\n-make sense to remove both from the list, like this:\n+side removed `banana` and one side removed `cherry`, it makes sense\n+to remove both from the list, like this:\n\n> or somethig like that.\n>\n> Other than that, I did not see anything questionable in the 6\n> patches.\n\n"},{"id":"556332","messageId":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.git.1790261062.gitgitgadget@gmail.com","subject":"[PATCH v5 0/6] [doc] Add new page on merge conflicts","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:39:59Z","receivedAt":"2026-10-26T12:39:59Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"Handling merge conflicts is difficult, and currently Git's guidance on merge\nconflicts isn't giving users the information they need to navigate the\nprocess. As usual, the process I used to write this was to collect comments\nfrom Git users on the existing documentation, and then address those issues.\nI listed the specific issues we're aiming to solve in the first commit\nmessage in the series.\n\nThis patch series introduces a new manual page, gitmergeconflicts, which\nexplains the process of explaining a merge conflict with examples. It also\nlinks to that new page from the commands which can cause merge conflicts,\ninstead of trying to reexplain the process every time.\n\nChanged in v2:\n\n * Explain what a merge conflict is (thanks to Junio & Ben)\n * rewrite the \"ours\" vs \"theirs\" section (thanks to Patrick for the\n   comments)\n * add git log --merge (thanks to Ben)\n * Leave most of the content of git cherry-pick as-is, to make this patch\n   set smaller (thanks to Junio)\n * remove the SYNOPSIS since hopefully that won't be required anymore by the\n   time this is merged\n * Fix a typo in git revert (s/reverted conflict/reverted commit/)\n * 's/the the/the/' (thanks to Patrick)\n * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'\n * squash the commit fixing the linter error (thanks to Junio)\n * list reviewers in Reviewed-by\n\nChanged in v3:\n\nThanks to all the comments from Junio.\n\n * Add signoff from Marie\n * In \"For example, here's a merge conflict where both sides edited a list\n   of\", add a little more detail about how to interpret the merge conflict\n * When we introduce a merge mention \"semantic merge conflicts\"\n * Say \"... and any other command that does a merge\" when listing commands\n   that can cause merge conflicts.\n * Reviewed-by is not the right thing, use Helped-by\n * Adjust phrasing in git revert and git cherry-pick man pages\n * Reference the \"ours\" section in \"git show :2:filename shows the \"ours\"\"\n * \"there's one file left with conflicts in it: fruits.py\" isn't precise\n   enough, instead say \"the conflicts in fruits.py haven't been marked as\n   resolved\"\n * Delete the explanation of zdiff3 and add a brief warning instead. Don't\n   be too prescriptive, we should tell people what the issue is (ambiguity)\n   instead of trying to impose our opinion.\n * Explain ||||||| when we add diff3\n * Fix example in \"EXAMPLE OF RESOLVING A MERGE CONFLICT\" to make it\n   consistent with the other examples\n * Replace \"configuration option\" with \"configuration variable\"\n * Mention --skip instead of saying \"the most common ways\", which is\n   ambiguous\n * Add a pointer to the extended AUTO_MERGE sentence\n\nChanged in v4:\n\nchanges to the content:\n\n * use Junio's much better example for diff3\n * clarify in the commit message why we're not mentioning git apply: to\n   avoid dealing with patches (thanks to Junio)\n * adjust the wording around \"multi-step operation like a rebase\" (thanks to\n   Junio)\n * Say \"see git-config for more\" in the description of zdiff3. Like Patrick\n   said the explanation of zdiff3 is not really satisfiying, but I don't\n   know how to write a satisfying explanation, and it's better to have a\n   short and obviously unsatisfying explanation than a long unsatisfying\n   one. Added a note in the commit message that perhaps this should be\n   improved in the future. (from Patrick's comment)\n\nchanges cleaning things up:\n\n * add periods at the ends of various sentences in an attempt to be more\n   consistent (thanks to Junio & Patrick)\n * Adjust the formatting around the [NOTE] to make the CI whitespace check\n   pass\n * Replace a couple of instances of \"code\" with \"lines\" (thanks to Junio)\n * Fix Ben's email address (thanks to Ben)\n * Remove the double signoff (thanks to Ben).\n * Make the cherry-pick commit message more accurate (thanks to Patrick)\n\nThanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,\nand about 12 others who gave feedback on both the original git merge man\npage, as well as the proposed improvements.\n\nJulia Evans (6):\n  doc: add new gitmergeconflicts man page\n  doc: git-merge: link to new merge conflicts guide\n  doc: git-rebase: link to new merge conflicts guide\n  doc: git-revert: link to new merge conflicts guide\n  doc: git-cherry-pick: link to new merge conflicts guide\n  doc: git-pull: link to new merge conflicts guide\n\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/git-cherry-pick.adoc   |   8 +-\n Documentation/git-merge.adoc         | 125 +---------\n Documentation/git-pull.adoc          |   3 +-\n Documentation/git-rebase.adoc        |  13 +-\n Documentation/git-revert.adoc        |   5 +\n Documentation/gitmergeconflicts.adoc | 339 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 10 files changed, 366 insertions(+), 131 deletions(-)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v5\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v5\nPull-Request: https://github.com/gitgitgadget/git/pull/2237\n\nRange-diff vs v4:\n\n 1:  486a77dbd7 ! 1:  8b526e2bd7 doc: add new gitmergeconflicts man page\n     @@ Commit message\n          there are other ways that merge conflicts can happen to avoid getting\n          into the difference between applying a patch and doing a 3-way merge.\n      \n     -    Things to potentially improve in future docs revisions:\n     -\n     -    - The explanation of zdiff3 is unsatisfying. It would be good if we\n     -      could have a clear example of a case where zdiff3 is helpful and a\n     -      case where it's harmful, and if we could give a better sense for\n     -      the reasons why users are actually choosing zdiff3 over diff3\n     -      (or the reverse) in real life.\n     -\n          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\n          Helped-by: D. Ben Knoble <ben.knoble@gmail.com>\n          Helped-by: Patrick Steinhardt <ps@pks.im>\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +    \"cherry\",\n      +    \"mango\",\n      +||||||| 1c22e48\n     -+\t\"banana\",\n     -+\t\"cherry\",\n     ++    \"banana\",\n     ++    \"cherry\",\n      +    \"mangoooo\",\n      +=======\n      +    \"banana\",\n     @@ Documentation/gitmergeconflicts.adoc (new)\n      +----\n      +\n      +With this view, you can see that both sides fixed a spelling\n     -+mistake in \"mango\", and each removed one fruit to the list.\n     ++mistake in \"mango\", and each removed one fruit from the list.\n      +This makes it more clear how to resolve the merge conflict: since one\n      +side removed `banana` and one side removed `cherry`, it would probably\n      +make sense to remove both from the list, like this:\n 2:  6862cb4f04 = 2:  3dc763a2a2 doc: git-merge: link to new merge conflicts guide\n 3:  2bd9850822 = 3:  02351af1b5 doc: git-rebase: link to new merge conflicts guide\n 4:  53083b48a3 = 4:  10f8947b68 doc: git-revert: link to new merge conflicts guide\n 5:  92cfdf260c = 5:  e1fe1c4aa3 doc: git-cherry-pick: link to new merge conflicts guide\n 6:  bbbf44aff1 = 6:  4f434f5acd doc: git-pull: link to new merge conflicts guide\n\n-- \ngitgitgadget\n\n"},{"id":"556333","messageId":"8b526e2bd7a8f4f3ce030f3f0b0b50b3fab02f14.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:00Z","receivedAt":"2026-10-26T12:40:00Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nIntroduce a new page, `gitmergeconflicts`, that explains the process of\nhandling a merge conflict in a way that addresses the following issues,\nwhich came from feedback from Git users on the current explanation of\nmerge conflicts in the `git merge` man page:\n\n- The process for resolving a merge conflict is only explained in the\n  `git merge` man page, even though there are several other commands\n  which can result in conflicts.\n- Sometimes we use \"ours\" and \"theirs\" to refer to the two sides of\n  the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should\n  be consistent. Also the terms \"ours\" and \"theirs\" are not explained.\n  Similarly, it says \"The part before the `=======` is typically your\n  side...\", but doesn't explain what \"typically\" means.\n- It introduces the merge format using an analogy to RCS, which very few\n  Git users have ever used.\n- In \"The only clean-ups you need are to reset the index file to the\n  `HEAD` commit to reverse 2. and to clean up working tree changes made\n  by 2. and 3.\", it's not clear to users what \"2\" and \"3\" are supposed\n  to mean.\n- It uses a cultural reference (\"Conflict resolution is hard; let's go\n  shopping.\") which is confusing or unfamiliar to some people. I think it\n  would be clearer for users to use a code example instead.\n- It doesn't explain the difference between diff3 and zdiff3.\n- It sometimes uses the term \"area\" and sometimes uses the term \"hunk\".\n\nAlso document the unified `--abort`, `--continue` workflow in one\nplace, since it's a really nice example of a place Git has a consistent\ninterface between similar commands.\n\nOnly discuss merge, rebase, cherry-pick, and revert for now even though\nthere are other ways that merge conflicts can happen to avoid getting\ninto the difference between applying a patch and doing a 3-way merge.\n\nCo-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nHelped-by: D. Ben Knoble <ben.knoble@gmail.com>\nHelped-by: Patrick Steinhardt <ps@pks.im>\nSigned-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n .gitattributes                       |   1 +\n Documentation/Makefile               |   1 +\n Documentation/gitmergeconflicts.adoc | 339 +++++++++++++++++++++++++++\n Documentation/meson.build            |   1 +\n command-list.txt                     |   1 +\n 5 files changed, 343 insertions(+)\n create mode 100644 Documentation/gitmergeconflicts.adoc\n\ndiff --git a/.gitattributes b/.gitattributes\nindex 26490ad60a..0a0fc950b1 100644\n--- a/.gitattributes\n+++ b/.gitattributes\n@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace\n /t/oid-info/* text eol=lf\n /Documentation/git-merge.adoc conflict-marker-size=32\n /Documentation/git-merge-file.adoc conflict-marker-size=32\n+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32\n /Documentation/gitk.adoc conflict-marker-size=32\n /Documentation/user-manual.adoc conflict-marker-size=32\n /t/t????-*.sh conflict-marker-size=32\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..bc49641dda 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc\n MAN7_TXT += giteveryday.adoc\n MAN7_TXT += gitfaq.adoc\n MAN7_TXT += gitglossary.adoc\n+MAN7_TXT += gitmergeconflicts.adoc\n MAN7_TXT += gitpacking.adoc\n MAN7_TXT += gitnamespaces.adoc\n MAN7_TXT += gitremote-helpers.adoc\ndiff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc\nnew file mode 100644\nindex 0000000000..99052ab506\n--- /dev/null\n+++ b/Documentation/gitmergeconflicts.adoc\n@@ -0,0 +1,339 @@\n+gitmergeconflicts(7)\n+====================\n+\n+NAME\n+----\n+gitmergeconflicts - Guide to handling merge conflicts\n+\n+DESCRIPTION\n+-----------\n+\n+Merge conflicts can happen during a `git merge`, `git rebase`, `git\n+cherry-pick`, `git pull`, `git revert`, or any other command that does\n+a merge. All of those commands use the same merge algorithm, and the\n+process for resolving a merge conflict is always very similar.\n+\n+There are 3 ways to handle a merge conflict:\n+\n+* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>\n+  below for details)\n+* Stop the operation and return your branch to its original state\n+  with the appropriate `--abort` command, for example `git merge --abort`\n+  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below\n+  for how to find the command to run.\n+* Or (if you're in a multi-step operation like a rebase) skip the problematic\n+  commit with the appropriate `--skip` command.\n+\n+WHAT IS A MERGE CONFLICT?\n+-------------------------\n+\n+When Git merges two commits together, it looks at the changes that\n+each side has made and combines those changes. For example, if one side\n+edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of\n+the same file, then it can easily combine them since there's no overlap.\n+\n+But if both sides edited overlapping lines of the same file (for example\n+one side edited lines 1-5 and the other edited lines 3-6), Git will\n+not try to guess how to combine those changes. This is called a \"merge\n+conflict\".\n+\n+When this happens, Git shows you both sides' edits and asks you to pick\n+how to resolve them. It:\n+\n+* Stages all of the files which were successfully merged\n+* For the files with conflicts, it marks them as conflicted, puts both\n+  sides' edits in the file, and leaves <<markers, merge conflict markers>>\n+  that you need to resolve.\n+\n+[NOTE]\n+Even if Git successfully merges both sides with no conflicts, it's\n+possible to end up with code that doesn't work. For example, this can\n+happen if one side renames a function, and the other side adds a call to\n+the old function. This is called a \"semantic merge conflict\".\n+\n+[[markers]]\n+MERGE CONFLICT MARKERS\n+----------------------\n+\n+When there's a merge conflict, Git will update the conflicted file\n+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.\n+For example, here's a merge conflict where both sides edited a list of\n+fruits in different ways -- one side has \"cherry\" and the other side\n+has \"banana\":\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+The lines from one side of the merge conflict is between `<<<<<<<` and\n+`=======`, and the lines from the other side is between `=======` and\n+`>>>>>>>`. See <<ours,\"OURS\" AND \"THEIRS\">> below for a full explanation\n+of which side is which.\n+\n+\n+[[resolve]]\n+HOW TO RESOLVE A MERGE CONFLICT\n+-------------------------------\n+\n+The process for resolving a merge conflict is:\n+\n+1. Run `git status` to get a list of files with merge conflicts.\n+2. For each one, find the conflict markers\n+   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the file to\n+   fix the conflict.\n+3. Run `git add FILENAME` for each file to mark the conflict as resolved.\n+4. Run the appropriate `--continue` command to continue the operation\n+   that was interrupted by the conflict, for example `git merge --continue`\n+   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>\n+   below for how to find the command to run.\n++\n+Note: During a `git merge`, `git commit` and `git merge --continue` do\n+the same thing.\n+\n+\n+[[example]]\n+EXAMPLE OF RESOLVING A MERGE CONFLICT\n+-------------------------------------\n+\n+If you see this in your code during a merge conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+=======\n+    \"banana\",\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+Then you might edit that part of the code like this,\n+which includes the fruits from both sides of the conflict:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"banana\",\n+    \"cherry\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+\n+[[tools]]\n+TOOLS FOR HANDLING MERGE CONFLICTS\n+----------------------------------\n+\n+Here are some ways to get extra context while handling a merge conflict:\n+\n+* There are many graphical \"merge tools\" for Git, which will normally\n+  show you the different versions of the code side by side.\n+  If you have a mergetool configured, `git mergetool` will launch it.\n+  See also `merge.tool` in linkgit:git-config[1] for a list of\n+  the mergetools Git supports.\n+\n+* You can set the configuration variable `merge.conflictstyle=diff3`.\n+  See <<diff3,DIFF3>> below for more.\n+\n+* `git log --merge --patch <filename>`  will list all commits which\n+  caused the merge conflict for `<filename>`, and the diff\n+  of how they changed the file.\n+\n+* Look at the original files.  `git show :1:filename` shows the\n+  common ancestor, `git show :2:filename` shows the \"ours\"\n+  version, and `git show :3:filename` shows the \"theirs\"\n+  version. See <<ours,\"OURS\" AND \"THEIRS\">> below for more on\n+  \"ours\" and \"theirs\".\n+\n+Here are some ways to track your progress while handling a conflict:\n+\n+* Use `git status` to get a list of files with conflicts\n+\n+* Use `git diff --check` to make sure you haven't left any merge\n+  conflict markers in a file by accident. It will print \"leftover\n+  conflict marker\" if it finds any.\n+\n+* Use `git diff AUTO_MERGE` to show what changes you've made so far to\n+  resolve the conflicts.\n+  See <<automerge,EXAMPLE OF USING `AUTO_MERGE`>> below for more.\n+\n+[[git_status]]\n+EXAMPLE: GIT STATUS OUTPUT\n+--------------------------\n+\n+When you're in a merge conflict, you can find out what commands to run\n+to handle the conflict by running `git status`.\n+\n+For example, this `git status` output tells you that:\n+\n+* `git rebase --abort` will safely bring your branch back to its\n+  original state\n+* you should run `git rebase --continue` when you're done resolving all\n+  the conflicts\n+* the conflicts in `fruits.py` haven't been marked as resolved\n+\n+----\n+$ git status\n+You are currently rebasing branch 'main' on '58a9fcc'.\n+  (fix conflicts and then run \"git rebase --continue\")\n+  (use \"git rebase --skip\" to skip this patch)\n+  (use \"git rebase --abort\" to check out the original branch)\n+\n+Unmerged paths:\n+  (use \"git restore --staged <file>...\" to unstage)\n+  (use \"git add <file>...\" to mark resolution)\n+        both modified:   fruits.py\n+----\n+\n+\n+[[diff3]]\n+DIFF3\n+-----\n+\n+By default, Git doesn't include the original code when formatting\n+a merge conflict. To include the original code, you can set the\n+configuration option `merge.conflictstyle` to `diff3`.\n+This extra context can make it much easier to understand what's\n+happening in a merge conflict.\n+\n+Here's an example of what a merge conflict would look like when using\n+`diff3`. There's an extra section (between `|||||||` and `=======`)\n+with the original code.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",\n+    \"mango\",\n+||||||| 1c22e48\n+    \"banana\",\n+    \"cherry\",\n+    \"mangoooo\",\n+=======\n+    \"banana\",\n+    \"mango\",\n+>>>>>>> add-fruit\n+    \"orange\",\n+]\n+----\n+\n+With this view, you can see that both sides fixed a spelling\n+mistake in \"mango\", and each removed one fruit from the list.\n+This makes it more clear how to resolve the merge conflict: since one\n+side removed `banana` and one side removed `cherry`, it would probably\n+make sense to remove both from the list, like this:\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+[NOTE]\n+`zdiff3` is an alternative to `diff3` that makes the merge conflict\n+shorter by making it more ambiguous. See linkgit:git-config[1] for more.\n+\n+[[ours]]\n+\"OURS\" AND \"THEIRS\"\n+-------------------\n+\n+Sometimes during a merge conflict, Git will use the terms \"ours\" and\n+\"theirs\" (or \"us\" and \"them\"). For example, `git status` might say that\n+a file was `deleted by us`.\n+\n+\"Ours\" and \"theirs\" are both commits: \"ours\" is the current\n+`HEAD` commit, and \"theirs\" is the other side being merged.\n+\n+The first part of a merge conflict (between `<<<<<<<` and `=======`) is\n+from the \"ours\" side, and the second part (between `=======` and\n+`>>>>>>>`) is from the \"theirs\" side.\n+\n+----\n+FRUITS = [\n+    \"apple\",\n+<<<<<<< HEAD\n+    \"cherry\",                      <- ours\n+=======\n+    \"banana\",                      <- theirs\n+>>>>>>> add-fruit\n+    \"mango\",\n+    \"orange\",\n+]\n+----\n+\n+During a rebase, it can seem \"upside down\" because the \"ours\" commit is\n+from the branch you're rebasing on (for instance `main` in `git rebase\n+main`).\n+\n+These terms in Git all mean the same thing when dealing with a merge\n+conflict:\n+\n+* \"common ancestor\" and \"base\". The files from this commit are \"in stage 1\".\n+* \"ours\", \"us\", and `HEAD`. The files from this commit are \"in stage 2\".\n+* \"theirs\", \"them\". The files from this commit are \"in stage 3\".\n+\n+If you're confused about what something like \"deleted by us\" means, it's\n+often easiest to use some of the tools from\n+<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.\n+Finding the commit that deleted the file and seeing why is usually more\n+helpful than trying to abstractly reason through what \"us\" means.\n+\n+[[automerge]]\n+EXAMPLE OF USING `AUTO_MERGE`\n+-----------------------------\n+\n+`git diff AUTO_MERGE` will show what changes you've made so far to\n+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a\n+merge. It contains the result of running the merge algorithm.\n+\n+For example, if we resolved the conflict by adding both \"banana\" and\n+\"cherry\" in order, the diff would look like this:\n+\n+----\n+ FRUITS = [\n+     \"apple\",\n+-<<<<<<< HEAD\n+-    \"cherry\",\n+-=======\n+     \"banana\",\n+->>>>>>> add-fruit\n++    \"cherry\",\n+     \"mango\",\n+     \"orange\",\n+ ]\n+----\n+\n+[NOTE]\n+`AUTO_MERGE` is only set if you're using the default Git merge algorithm.\n+\n+\n+SEE ALSO\n+--------\n+\n+linkgit:git-revert[1]\n+linkgit:git-merge[1]\n+linkgit:git-rebase[1]\n+linkgit:git-cherry-pick[1]\n+linkgit:git-pull[1]\n+linkgit:git-diff[1]\n+\n+GIT\n+---\n+\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f4854f802d..51647957e0 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -202,6 +202,7 @@ manpages = {\n   'gitfaq.adoc' : 7,\n   'gitglossary.adoc' : 7,\n   'gitpacking.adoc' : 7,\n+  'gitmergeconflicts.adoc' : 7,\n   'gitnamespaces.adoc' : 7,\n   'gitremote-helpers.adoc' : 7,\n   'gitrevisions.adoc' : 7,\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..f6e49c3c85 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -232,6 +232,7 @@ githooks                                userinterfaces\n gitignore                               userinterfaces\n gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n+gitmergeconflicts                       guide\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n gitprotocol-capabilities                developerinterfaces\n-- \ngitgitgadget\n\n\n"},{"id":"556334","messageId":"3dc763a2a2f10f453102ad3b9232d9291e7cca75.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 2/6] doc: git-merge: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:01Z","receivedAt":"2026-10-26T12:40:01Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nAll of the info about merge conflicts has been moved to the new guide\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-merge.adoc | 125 +----------------------------------\n 1 file changed, 3 insertions(+), 122 deletions(-)\n\ndiff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc\nindex a055384ad6..5b7b41cd10 100644\n--- a/Documentation/git-merge.adoc\n+++ b/Documentation/git-merge.adoc\n@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation,\n A merge stops if there's a conflict that cannot be resolved\n automatically or if `--no-commit` was provided when initiating the\n merge. At that point you can run `git merge --abort` or `git merge\n---continue`.\n+--continue`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n `git merge --abort` will abort the merge process and try to reconstruct\n the pre-merge state. However, if there were uncommitted changes when the\n@@ -231,127 +232,6 @@ git merge v1.2.3^0\n git merge --ff-only v1.2.3\n ----\n \n-HOW CONFLICTS ARE PRESENTED\n----------------------------\n-\n-During a merge, the working tree files are updated to reflect the result\n-of the merge.  Among the changes made to the common ancestor's version,\n-non-overlapping ones (that is, you changed an area of the file while the\n-other side left that area intact, or vice versa) are incorporated in the\n-final result verbatim.  When both sides made changes to the same area,\n-however, Git cannot randomly pick one side over the other, and asks you to\n-resolve it by leaving what both sides did to that area.\n-\n-By default, Git uses the same style as the one used by the \"merge\" program\n-from the RCS suite to present such a conflicted hunk, like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-The area where a pair of conflicting changes happened is marked with markers\n-+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`\n-is typically your side, and the part afterwards is typically their side.\n-\n-The default format does not show what the original said in the conflicting\n-area.  You cannot tell how many lines are deleted and replaced with\n-Barbie's remark on your side.  The only thing you can tell is that your\n-side wants to say it is hard and you'd prefer to go shopping, while the\n-other side wants to claim it is easy.\n-\n-An alternative style can be used by setting the `merge.conflictStyle`\n-configuration variable to either `diff3` or `zdiff3`.  In `diff3`\n-style, the above conflict may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-<<<<<<< yours:sample.txt\n-or cleanly resolved because both sides changed the same way.\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-or cleanly resolved because both sides changed the same way.\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-while in `zdiff3` style, it may look like this:\n-\n-------------\n-Here are lines that are either unchanged from the common\n-ancestor, or cleanly resolved because only one side changed,\n-or cleanly resolved because both sides changed the same way.\n-<<<<<<< yours:sample.txt\n-Conflict resolution is hard;\n-let's go shopping.\n-||||||| base:sample.txt\n-or cleanly resolved because both sides changed identically.\n-Conflict resolution is hard.\n-=======\n-Git makes conflict resolution easy.\n->>>>>>> theirs:sample.txt\n-And here is another line that is cleanly resolved or unmodified.\n-------------\n-\n-In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses\n-another +|||||||+ marker that is followed by the original text.  You can\n-tell that the original just stated a fact, and your side simply gave in to\n-that statement and gave up, while the other side tried to have a more\n-positive attitude.  You can sometimes come up with a better resolution by\n-viewing the original.\n-\n-\n-HOW TO RESOLVE CONFLICTS\n-------------------------\n-\n-After seeing a conflict, you can do two things:\n-\n- * Decide not to merge.  The only clean-ups you need are to reset\n-   the index file to the `HEAD` commit to reverse 2. and to clean\n-   up working tree changes made by 2. and 3.; `git merge --abort`\n-   can be used for this.\n-\n- * Resolve the conflicts.  Git will mark the conflicts in\n-   the working tree.  Edit the files into shape and\n-   `git add` them to the index.  Use `git commit` or\n-   `git merge --continue` to seal the deal. The latter command\n-   checks whether there is a (interrupted) merge in progress\n-   before calling `git commit`.\n-\n-You can work through the conflict with a number of tools:\n-\n- * Use a mergetool.  `git mergetool` to launch a graphical\n-   mergetool which will work through the merge with you.\n-\n- * Look at the diffs.  `git diff` will show a three-way diff,\n-   highlighting changes from both the `HEAD` and `MERGE_HEAD`\n-   versions. `git diff AUTO_MERGE` will show what changes you've\n-   made so far to resolve textual conflicts.\n-\n- * Look at the diffs from each branch. `git log --merge -p <path>`\n-   will show diffs first for the `HEAD` version and then the\n-   `MERGE_HEAD` version.\n-\n- * Look at the originals.  `git show :1:filename` shows the\n-   common ancestor, `git show :2:filename` shows the `HEAD`\n-   version, and `git show :3:filename` shows the `MERGE_HEAD`\n-   version.\n-\n-\n EXAMPLES\n --------\n \n@@ -406,6 +286,7 @@ linkgit:git-reset[1],\n linkgit:git-diff[1], linkgit:git-ls-files[1],\n linkgit:git-add[1], linkgit:git-rm[1],\n linkgit:git-mergetool[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556335","messageId":"02351af1b5bb25b4125e85c52de9070ac6af2e64.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 3/6] doc: git-rebase: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:02Z","receivedAt":"2026-10-26T12:40:02Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRemove some of the detail about how to handle a merge conflict, since\nit's explained in detail in the new guide, and there probably isn't\nenough detail anyway.\n\nLeave the steps since rebase is special and has a `--skip` option which\nthe other commands which cause merge conflicts don't have.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-rebase.adoc | 13 +++++++++----\n 1 file changed, 9 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..da70aff498 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the\n first problematic commit and leave conflict markers. If this happens, you can do\n one of these things:\n \n-1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)\n-   and make edits to resolve the conflict. For each file you edit, you need to\n-   tell Git that the conflict has been resolved. You can mark the conflict as\n-   resolved with  `git add <filename>`. After resolving all of the conflicts,\n+1. Resolve the conflict. After resolving all of the conflicts,\n    you can continue the rebasing process with\n \n    git rebase --continue\n@@ -62,6 +59,9 @@ one of these things:\n \n    git rebase --skip\n \n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a full guide to handling merge conflicts.\n+\n If you don't specify an `<upstream>` to rebase onto, the upstream configured in\n `branch.<name>.remote` and `branch.<name>.merge` options will be used (see\n linkgit:git-config[1] for details) and the `--fork-point` option is\n@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[]\n include::config/rebase.adoc[]\n include::config/sequencer.adoc[]\n \n+SEE ALSO\n+--------\n+\n+linkgit:gitmergeconflicts[7]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \ngitgitgadget\n\n\n"},{"id":"556336","messageId":"10f8947b685c4a5c2c1af9823e08a058d6944250.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 4/6] doc: git-revert: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:03Z","receivedAt":"2026-10-26T12:40:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-revert.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e63..bb0f859f66 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.\n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n between the three commands.\n \n+Reverting a commit may result in a merge conflict.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n+\n OPTIONS\n -------\n <commit>...::\n@@ -162,6 +166,7 @@ include::config/revert.adoc[]\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556337","messageId":"e1fe1c4aa3e1248e3b9d1bb4bcc8786265468157.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 5/6] doc: git-cherry-pick: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:04Z","receivedAt":"2026-10-26T12:40:04Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-cherry-pick.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex f4cd8b9db7..069e434961 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -19,8 +19,7 @@ Given one or more existing commits, apply the change each one\n introduces, recording a new commit for each.  This requires your\n working tree to be clean (no modifications from the HEAD commit).\n \n-When it is not obvious how to apply a change, the following\n-happens:\n+When a merge conflict happens:\n \n 1. The current branch and `HEAD` pointer stay at the last commit\n    successfully made.\n@@ -36,8 +35,8 @@ happens:\n    conflict markers `<<<<<<<` and `>>>>>>>`.\n 5. No other modifications are made.\n \n-See linkgit:git-merge[1] for some hints on resolving such\n-conflicts.\n+See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`)\n+for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n@@ -259,6 +258,7 @@ $ git cherry-pick -Xpatience topic^  <4>\n SEE ALSO\n --------\n linkgit:git-revert[1]\n+linkgit:gitmergeconflicts[7]\n \n GIT\n ---\n-- \ngitgitgadget\n\n\n"},{"id":"556338","messageId":"4f434f5acdd55775c6ddcaced073e5a0e3ff732e.1793018405.git.gitgitgadget@gmail.com","threadId":"66387","inReplyTo":"pull.2237.v5.git.1793018405.gitgitgadget@gmail.com","subject":"[PATCH v5 6/6] doc: git-pull: link to new merge conflicts guide","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-26T12:40:05Z","receivedAt":"2026-10-26T12:40:05Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n Documentation/git-pull.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc\nindex 88f4fd3926..73f6d460bb 100644\n--- a/Documentation/git-pull.adoc\n+++ b/Documentation/git-pull.adoc\n@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.\n \n If there's a merge conflict during the merge or rebase that you don't\n want to handle, you can safely abort it with `git merge --abort` or\n-`git rebase --abort`.\n+`git rebase --abort`. See linkgit:gitmergeconflicts[7]\n+(or `git help mergeconflicts`) for a guide to handling merge conflicts.\n \n OPTIONS\n -------\n-- \ngitgitgadget\n\n"},{"id":"556352","messageId":"xmqqmrs0v87w.fsf@gitster.g","threadId":"66387","inReplyTo":"2564bcc2-2f78-4ea2-9b6f-c033e95983d8@app.fastmail.com","subject":"Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-26T14:37:23Z","receivedAt":"2026-10-26T14:37:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> So, let's rewrite the reason a bit more tightly.\n>>\n>>     since one side removed `banana` while the other side did not\n>>     touch, and the same happend to `cherry`, it makes sense to\n>>     remove both from the list ...\n>\n> I tried to edit this (like below) but only ended up removing \"probably\".\n> But \"probably\" was there for a reason, since this is a made up example\n> and in the real world you would really need to apply some judgement\n> to know what the right thing to do is. I left it as is.\n>\n> -side removed `banana` and one side removed `cherry`, it would probably\n> -make sense to remove both from the list, like this:\n> +side removed `banana` and one side removed `cherry`, it makes sense\n> +to remove both from the list, like this:\n\nAre we talking past each other?  I did not mean \"probably\" was not\ntight enough, and probably is probably a good thing to have there.\n\nThe value I wanted to bring on the table was to point out that the\nchanges are not just \"one side did something\", but \"one side did\nsomething where the other side had no opinion on (hence it didn't do\nanything)\".  It is the basis of how 3-way merge works and helps to\nresolve the example for removal of both.\n\n\n"},{"id":"556353","messageId":"d330a5ba-cefd-4a4e-aef5-972a931d4d8c@app.fastmail.com","threadId":"66387","inReplyTo":"xmqqmrs0v87w.fsf@gitster.g","subject":"Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-26T14:47:33Z","receivedAt":"2026-10-26T14:47:33Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Mon, Oct 26, 2026, at 10:37 AM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n>>> So, let's rewrite the reason a bit more tightly.\n>>>\n>>>     since one side removed `banana` while the other side did not\n>>>     touch, and the same happend to `cherry`, it makes sense to\n>>>     remove both from the list ...\n>>\n>> I tried to edit this (like below) but only ended up removing \"probably\".\n>> But \"probably\" was there for a reason, since this is a made up example\n>> and in the real world you would really need to apply some judgement\n>> to know what the right thing to do is. I left it as is.\n>>\n>> -side removed `banana` and one side removed `cherry`, it would probably\n>> -make sense to remove both from the list, like this:\n>> +side removed `banana` and one side removed `cherry`, it makes sense\n>> +to remove both from the list, like this:\n>\n> Are we talking past each other?  I did not mean \"probably\" was not\n> tight enough, and probably is probably a good thing to have there.\n>\n> The value I wanted to bring on the table was to point out that the\n> changes are not just \"one side did something\", but \"one side did\n> something where the other side had no opinion on (hence it didn't do\n> anything)\".  It is the basis of how 3-way merge works and helps to\n> resolve the example for removal of both.\n\nOh, I see.  This is such a simple example that IMO trying to explain\nin more detail exactly \"why\" the resolution is correct risks confusing\npeople. My goal with saying \"one side removed 'banana'\" is just\nto give an example of how to read what the merge conflict above is\nsaying, since the syntax might be new to people.\n\n"},{"id":"556376","messageId":"xmqq5wyos7g0.fsf@gitster.g","threadId":"66387","inReplyTo":"d330a5ba-cefd-4a4e-aef5-972a931d4d8c@app.fastmail.com","subject":"Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-26T17:22:23Z","receivedAt":"2026-10-26T17:22:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> The value I wanted to bring on the table was to point out that the\n>> changes are not just \"one side did something\", but \"one side did\n>> something where the other side had no opinion on (hence it didn't do\n>> anything)\".  It is the basis of how 3-way merge works and helps to\n>> resolve the example for removal of both.\n>\n> Oh, I see.  This is such a simple example that IMO trying to explain\n> in more detail exactly \"why\" the resolution is correct risks confusing\n> people. My goal with saying \"one side removed 'banana'\" is just\n> to give an example of how to read what the merge conflict above is\n> saying, since the syntax might be new to people.\n\nOK.  Other than that, I do not think anybody saw an issue in this\niteration, and I suspect that we are reaching the point of diminishing\nreturns.  Let me mark the topic as ready for 'next'.\n\nTHanks.\n\n"}]}