Repository navigation
[doc] Add new page on merge conflicts #2237
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace | |
| /t/oid-info/* text eol=lf | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Introduce a new page, `gitmergeconflicts`, that explains the process of
> handling a merge conflict in a way that addresses the following issues,
> which came from feedback from Git users on the current explanation of
> merge conflicts in the `git merge` man page:
Good goal.
> - The process for resolving a merge conflict is only explained in the
> `git merge` man page, even though there are several other commands
> which can result in conflicts
> - Sometimes we use "ours" and "theirs" to refer to the two sides of
> the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should
> be consistent. Also the terms "ours" and "theirs" are not explained.
> Similarly, it says "The part before the `=======` is typically your
> side...", but doesn't explain what "typically" means.
> - It introduces the merge format using an analogy to RCS, which very few
> Git users have ever used
> - In "The only clean-ups you need are to reset the index file to the
> `HEAD` commit to reverse 2. and to clean up working tree changes made
> by 2. and 3.", it's not clear to users what "2" and "3" are supposed
> to mean
> - It uses a cultural reference ("Conflict resolution is hard; let's go
> shopping.") which is confusing or unfamiliar to some people. I think it
> would be clearer for users to use a code example instead.
> - It doesn't explain the difference between diff3 and zdiff3
> - It sometimes uses the term "area" and sometimes uses the term "hunk"
It is a bit hard to evaluate this list, as we do not see any of the
above problems excised from the existing documents in this step.
But at least we can verify that the new text presented in this patch
does not fall into the same trap as above, so I'll keep that in mind
while reviewing this step.
> Also document the unified `--abort`, `--continue` workflow in one
> place, since it's a really nice example of a place Git has a consistent
> interface between similar commands.
Great.
> Co-Authored-By: Marie Claire LeBlanc Flanagan <[email protected]>
> Reviewed-by: D. Ben Knoble <[email protected]>
> Reviewed-by: Patrick Steinhardt <[email protected]>
> Signed-off-by: Julia Evans <[email protected]>
We want a sign-off by the coauthor, too.
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..5b0ba1a1de
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,333 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
> +the same merge algorithm, and the process for resolving a merge conflict
> +is always very similar.
Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order
tolimit ourselves to most common ways to help new people by keeping
the description to the absolute minimum?
Or were they just overlooked?
In any case, the first paragraph clearly stating that conflicts
happen with operations other than 'merge' is a very welcome change.
On this list, we often say "mergy operations can cause conflicts",
with the understanding that readers know what mergy operations are
and "conflicts" alone can convey the state you call "merge
conflicts" in this document. But in a document for end-users, using
a longer term "merge conflicts" instead of "conflicts" and avoiding
"mergy operations" like you did above may be a better direction to
go.
> +The most common ways to handle a merge conflict are:
A natural paraphrase of the above is "A merge conflict is typically
handled by these ways", but I thought the current readers are
puzzled by "typically your side" that does not say when is typical.
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> + below for details)
> +* Or stop the operation and return your branch to its original state
> + with the appropriate `--abort` command, for example `git merge --abort`
> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
> + for how to find the command to run.
Both are good options and I do not think of a middle way. Perhaps
we do not have to say that these are "the most common" and instead
say "You handle a merge conflict by doing either of these two"?
Saying "return your branch to" is a bit misleading for two reasons.
Conflicts presented to the users are primarily visible in their
working tree files and the index. A single commit operations like
'merge', 'pull', and 'revert' does not touch your branch if they hit
a conflict, and 'rebase' works on a detached HEAD, and stops without
touching your branch when it sees a conflict.
If I were writing this, with the goal of avoiding the issues the
current text has you listed in the proposed log message, I would
probably say something like this:
* Or give up and return to the original state with ...
> +WHAT IS A MERGE CONFLICT?
> +-------------------------
> +
> +When Git merges two commits together, it looks at the changes that
> +each side has made and combines those changes. For example, if one side
> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
> +the same file, then it can easily combine them since there's no overlap.
Many of the operations, even "git merge", is not about merging "two
commits" together, but I do not think of a good way to explain it,
so I accept that phrasing as a helpful white lie. I mention this
because somebody else may be able to come up with a better phrasing
that I (or authors of this iteration) couldn't think of.
> +But if both sides edited overlapping lines of the same file (for example
> +one side edited lines 1-5 and the other edited lines 3-6), Git will
> +not try to guess how to combine those changes. This is called a "merge
> +conflict".
> +
> +When this happens, Git shows you both sides' edits and asks you to pick
> +how to resolve them. It:
> +
> +* Stages all of the files which were successfully merged
> +* For the files with conflicts, it marks them as conflicted, puts both
> + sides' edits in the file, and leaves <<markers, merge conflict markers>>
> + that you need to resolve.
By the way, I think we should briefly mention what sematnic merge
conflicts are, and that Git does not detect them and that this
manual page does not tell readers how to deal with them.
Note that non-overlapping changes from two sides may leave the
result in an inconsistent state. With the edit to lines 1-5,
one side may have changed the name of a function, while with the
edit to lines 20-25, the other side may have added a new call to
the function by its original name. This type of inconsistencies
are called semantic conflicts, Git has no way knowing that a
merge introduced semantic conflicts, and ends up producing a
broken result without merge conflicts. This document does not
cover what to do with semantic conflicts.
That is overly long, but perhaps you can condense it down to the
essense and shrink down to 1/3 of the size.
> +[[markers]]
> +MERGE CONFLICT MARKERS
> +----------------------
> +
> +When there's a merge conflict, Git will update the conflicted file
> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
I notice that when you introduce `diff3` below, you silently add
`|||||||` to the mix without explaining what it is.
`|||||||` may also be used as merge conflict markers (explained
later).
or something along the line here may help. Or explain what it is in
`diff3` section. Either would work. Adding without explanation
would not.
> +For example, here's a merge conflict where both sides edited a list of
> +fruits in different ways:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit
> + "mango",
> + "orange",
> +]
> +----
> +
> +The code from one side of the merge conflict is between `<<<<<<<` and
> +`=======`, and the code for the other side is between `=======` and
> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
> +of which side is which.
If we said "one side wanted to have 'apple, cherry, mango, orange',
while the other side wanted 'apply, banana, mango, orange', in the
FRUITS array", would it help the understanding? Or is it too
obvious?
> +[[resolve]]
> +HOW TO RESOLVE A MERGE CONFLICT
> +-------------------------------
> +
> +The process for resolving a merge conflict is:
> +
> +1. Run `git status` to get a list of files with merge conflicts
> +2. For each one, find the conflict markers
> + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
> + fix the conflict
> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
> +4. Run the appropriate `--continue` command to continue the operation
> + that was interrupted by the conflict, for example `git merge --continue`
> + or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
> + below for how to find the command to run.
> ++
> +Note: During a `git merge`, `git commit` and `git merge --continue` do
> +the same thing.
> +
> +
> +[[example]]
> +EXAMPLE OF RESOLVING A MERGE CONFLICT
> +-------------------------------------
> +
> +If you see this in your code during a merge conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> + "mango",
> +=======
> + "banana",
> + "mango",
> +>>>>>>> add-fruit
> + "orange",
> +]
> +----
It would make your readers puzzled why the example is subtly
different from the earlier one that showed "mango" as not touched by
either side. I see this lays the groundwork for later demonstration
of `diff3`, so having both sides explicitly want "mango" is a good
example. Perhaps update the first example to be the same as this
one, which would reduce the mental burden by readers?
> +
> +Then you might edit that part of the code like this,
> +which includes the fruits from both sides of the conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> + "banana",
> + "cherry",
> + "mango",
> + "orange",
> +]
> +----
OK.
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> + show you the different versions of the code side by side.
> + If you have a mergetool configured, `git mergetool` will launch it.
> + See also `merge.tool` in linkgit:git-config[1] for a list of
> + the mergetools Git supports.
> +
> +* You can set the configuration option `merge.conflictstyle=diff3`.
> + See <<diff3,DIFF3 AND ZDIFF3>> below for more.
These are called 'configuration variables' throughout the manual
pages. Be consistent and replace "configuration option" with
"configuration variable", perhaps?
> +* `git log --merge -p <filename>` will list all commits which
> + caused the merge conflict for `<filename>`, and the diff
> + of how they changed the file.
Maybe worth mentioning that `--left-right` often helps when you are
not super familiar with the histories being merged.
> +* Look at the original files. `git show :1:filename` shows the
> + common ancestor, `git show :2:filename` shows the "ours"
> + version, and `git show :3:filename` shows the "theirs"
> + version.
Maybe it will help to say we will explain "ours" and "theirs" later
in this document.
> +Here are some ways to track your progress while handling a conflict:
> +
> +* Use `git status` to get a list of files with conflicts
> +
> +* Use `git diff --check` to make sure you haven't left any merge
> + conflict markers in a file by accident. It will print "leftover
> + conflict marker" if it finds any.
Good. This also complains about whitespace errors, by the way, but
the last sentence here would be sufficient to help the readers to
tell them apart.
> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to
> + resolve the conflicts.
Does a "See below" here help readers who haven't learned what
AUTO_MERGE is? If you can describe what AUTO_MERGE records (in
other words, what you are comparing your progress against) in a
sentence of two here, that would alleviate the need to assure them
that we have more in-depth coverage on this topic elsewhere.
> +[[git_status]]
> +EXAMPLE: GIT STATUS OUTPUT
> +--------------------------
> +
> +When you're in a merge conflict, you can find out what commands to run
> +to handle the conflict by running `git status`.
> +
> +For example, this `git status` output tells you that:
> +
> +* `git rebase --abort` will safely bring your branch back to its
> + original state
> +* you should run `git rebase --continue` when you're done resolving all
> + the conflicts
> +* there's one file left with conflicts in it: `fruits.py`
There may be users, after seeing the last point, left puzzled why
fruits.py is still listed after they edited the file like instructed
in an earlier example but haven't marked the resolution.
`fruits.py` is not marked as its conflicts resolved yet.
or something?
> +----
> +$ git status
> +You are currently rebasing branch 'main' on '58a9fcc'.
> + (fix conflicts and then run "git rebase --continue")
> + (use "git rebase --skip" to skip this patch)
> + (use "git rebase --abort" to check out the original branch)
> +
> +Unmerged paths:
> + (use "git restore --staged <file>..." to unstage)
> + (use "git add <file>..." to mark resolution)
> + both modified: fruits.py
> +----
The approach to give explanations first and then an example the
explanation explains next is refreshing to me. As long as the
explanations are short enough, this may work better than the usual
order to say "you'd see something like this. let us explain ...".
> +[[diff3]]
> +DIFF3 AND ZDIFF3
> +----------------
> +
> +By default, Git doesn't include the original code when formatting
> +a merge conflict. To include the original code, you can set the
> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.
> +This extra context can make it much easier to understand what's
> +happening in a merge conflict.
I think most on the list considers `zdiff3` a failed experiment that
reduces usefulness of `diff3`. Do we want to recommend it?
Is it obvious to readers what "original" we are talking about? We
are not talking about the state we started the mergy operation from.
We are talking about what the common ancestor had before two sides
started working on the text to cause the divergence that conflicted.
One way I can think of to resolve this is to back to "What is a
merge conflict?" section and introduce "original" right there. I'll
SHOUT my additions below:
When Git merges two commits together, it looks at the changes
that each side has made SINCE THE TWO SIDES DIVERGED and
combines those changes. WE OFTEN CALL THIS STATE THEY DIVERGED
FROM THE "ORIGINAL". For example, if one side edited lines 1-5
of `hello.py` and the other side edited lines 20-25 of the same
file, then it can easily combine them since there's no overlap.
If you later use "common" or "common ancestor", you can explain they
are "original" we defined in the above paragraph.
Or ...
> +Here's an example of what a merge conflict would look like when using
> +`diff3`. It shows, in order, the "ours" side of the conflict, the
> +original code (`"mangoooo"`), and the "theirs" side of the
> +conflict. With this view, you can see that both sides fixed the spelling
> +mistake in "mango", and each added one fruit to the list.
... perhaps you avoid "common ancestor" altogether, with the
intention to deprecate it, and introduce "original", like in the
above paragraph? That is fine too. Once we establish what to call
"common, ours, theirs", we should add them to glossary-contents, as
I do not think we describe any of the ones we currently use there.
As I already mentioned, just like you said <<< === encloses your
side and === >>> encloses their side in 2-way conflict display,
we need to say <<< ||| encloses yours and ||| === encloses common
in diff3 output. How theirs is shown remains the same. Here is my
attempt to do so with least disruption to the flow of the text.
Here is an example of what the same conflict might look with
`diff3`. It uses a new separator `|||||||` before `=======`,
and shows, in order the "ours" side ...
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> + "mango",
> +||||||| 1c22e48
> + "mangoooo",
> +=======
> + "banana",
> + "mango",
> +>>>>>>> add-fruit
> + "orange",
> +]
> +----
> +
> +Here's the same example using `zdiff3`. `zdiff3` takes lines that are
> +shared between both sides (the `"mango"` line) and moves them outside
> +the conflicted area. This makes the conflicted area shorter, but the
> +downside is that it's impossible to tell if `"mango"` was part of the
> +original list of fruits or not.
Yes, exactly. That is why I think we shouldn't promote it, but
write it off as a failed experiment, and just tell them not to use
it in this document, without giving an example.
If the original were "apple, banana, cherry, mangoooo, orange", and
ours and theirs were the same as the above example, then a desirable
conflict resolution would be "apple, mango, orange", because both
sides knew the original had banana and cherry, and each side
rejected one of them each. It would be a good demonstration of why
`diff3` is a better format than `(rcs)merge`, so if we were to spend
lines on an example, I'd rather see it here, instead of zdiff3 example.
By the way, is it just me who finds those "Here's", "there's"
contractions disturbing in an official manual? I've seen many of
them while reviewing this to be annoyed enough and had to blurt it
out X-<.
> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Sometimes during a merge conflict, Git will use the terms "ours" and
> +"theirs" (or "us" and "them"). For example, `git status` might say that
> +a file was `deleted by us`.
OK.
> +"Ours" and "theirs" are both commits: "ours" is the current
> +`HEAD` commit, and "theirs" is the other side being merged.
Now, "commits" is again a white lie. The story becomes more
complicated when we talk about cherry-pick and revert, but if we
primarily stick to what happens in 'merge' (which is what I've seen
so far in this document), then it shouldn't add any extra difficulty
to understand by saying "ours and theirs are history of changes
leading to the two commits since they diverged from the original" to
add clarity.
> +The first part of a merge conflict (between `<<<<<<<` and `=======`) is
> +from the "ours" side, and the second part (between `=======` and
> +`>>>>>>>`) is from the "theirs" side.
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry", <- ours
> +=======
> + "banana", <- theirs
> +>>>>>>> add-fruit
> + "mango",
> + "orange",
> +]
> +----
> +
> +During a rebase, it can seem "upside down" because the "ours" commit is
> +from the branch you're rebasing on (for instance `main` in `git rebase
> +main`).
> +
> +These terms in Git all mean the same thing when dealing with a merge
> +conflict:
> +
> +* "common ancestor" and "base". The files from this commit are "in stage 1".
> +* "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
> +* "theirs", "them". The files from this commit are "in stage 3".
> +
> +If you're confused about what something like "deleted by us" means, it's
> +often easiest to use some of the tools from
> +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
> +Finding the commit that deleted the file and seeing why is usually more
> +helpful than trying to abstractly reason through what "us" means.
> +
> +[[automerge]]
> +EXAMPLE OF USING `AUTO_MERGE`
> +-----------------------------
> +
> +`git diff AUTO_MERGE` will show what changes you've made so far to
> +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a
> +merge. It contains the result of running the merge algorithm.
The first sentence gave me "Huh? You haven't explained what
AUTO_MERGE is yet". It may be just me, but I would have expected
presentation order to be more like:
When merge conflicts happen, the result of merge algorithm,
together with conflict markers, is recorded in AUTO_MERGE. As
you resolve conflicts, you can compare your working tree files
against it with `git diff AUTO_MERGE` to see your progress.
> +For example, if we resolved the conflict by adding both "banana" and
> +"cherry" in order, the diff would look like this:
> +
> +----
> + FRUITS = [
> + "apple",
> +-<<<<<<< HEAD
> +- "cherry",
> +-=======
> + "banana",
> +->>>>>>> add-fruit
> ++ "cherry",
> + "mango",
> + "orange",
> + ]
> +----
Thanks.
I was puzzled by this
> - In "The only clean-ups you need are to reset the index file to the
> `HEAD` commit to reverse 2. and to clean up working tree changes made
> by 2. and 3.", it's not clear to users what "2" and "3" are supposed
> to mean
and did some digging.
The text comes from ffb1a4bed5 (Documentation: Describe merge
operation a bit better., 2005-11-28) that had "When there are
conflicts, these things happen. 1. HEAD does not move, 2. Cleanly
merged paths are updated in the index 3. Conflicts are recorded in
higher stage index entries and working tree files show conflict
markers, 4. No other changes are done" well before the mysterious
reference to 2. and 3.
When ebef7e5049 (Documentation: simplify How Merge Works,
2010-01-23) tried to simplify the description, the list of "these
things happen" were removed/rewritten, and yet instructions on how
to reset are left behind, still referring to 2. and 3.
We probably want a separate patch for Documentation/git-merge.adoc
to rectify this 16 year old mistake.There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): Thanks for the review, I'm especially excited about the idea to remove zdiff3.
>> Co-Authored-By: Marie Claire LeBlanc Flanagan <[email protected]>
>> Reviewed-by: D. Ben Knoble <[email protected]>
>> Reviewed-by: Patrick Steinhardt <[email protected]>
>> Signed-off-by: Julia Evans <[email protected]>
>
> We want a sign-off by the coauthor, too.
Will do.
>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
>> new file mode 100644
>> index 0000000000..5b0ba1a1de
>> --- /dev/null
>> +++ b/Documentation/gitmergeconflicts.adoc
>> @@ -0,0 +1,333 @@
>> +gitmergeconflicts(7)
>> +====================
>> +
>> +NAME
>> +----
>> +gitmergeconflicts - Guide to handling merge conflicts
>> +
>> +DESCRIPTION
>> +-----------
>> +
>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
>> +the same merge algorithm, and the process for resolving a merge conflict
>> +is always very similar.
>
> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order
> to limit ourselves to most common ways to help new people by keeping
> the description to the absolute minimum?
It's deliberate, we talked about that a bit in the discussion of the v1.
Can add a note in the commit message.
> In any case, the first paragraph clearly stating that conflicts
> happen with operations other than 'merge' is a very welcome change.
> On this list, we often say "mergy operations can cause conflicts",
> with the understanding that readers know what mergy operations are
> and "conflicts" alone can convey the state you call "merge
> conflicts" in this document. But in a document for end-users, using
> a longer term "merge conflicts" instead of "conflicts" and avoiding
> "mergy operations" like you did above may be a better direction to
> go.
>
>> +The most common ways to handle a merge conflict are:
>
> A natural paraphrase of the above is "A merge conflict is typically
> handled by these ways", but I thought the current readers are
> puzzled by "typically your side" that does not say when is typical.
>
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> + below for details)
>> +* Or stop the operation and return your branch to its original state
>> + with the appropriate `--abort` command, for example `git merge --abort`
>> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>> + for how to find the command to run.
>
> Both are good options and I do not think of a middle way. Perhaps
> we do not have to say that these are "the most common" and instead
> say "You handle a merge conflict by doing either of these two"?
I agree the "the most common" is kind of weaselly and I'd like to be more clear.
The reason I wrote "typically" is that during a rebase, there's an extra
"skip" option, so it's not strictly true to say that there are just two options.
Not sure if there's another option I'm not thinking of other than the
"skip" in rebase.
> Saying "return your branch to" is a bit misleading for two reasons.
> Conflicts presented to the users are primarily visible in their
> working tree files and the index. A single commit operations like
> 'merge', 'pull', and 'revert' does not touch your branch if they hit
> a conflict, and 'rebase' works on a detached HEAD, and stops without
> touching your branch when it sees a conflict.
>
> If I were writing this, with the goal of avoiding the issues the
> current text has you listed in the proposed log message, I would
> probably say something like this:
>
> * Or give up and return to the original state with ...
That's reasonable, I think "return to the original state" would be fine.
Will look at this.
>
>> +WHAT IS A MERGE CONFLICT?
>> +-------------------------
>> +
>> +When Git merges two commits together, it looks at the changes that
>> +each side has made and combines those changes. For example, if one side
>> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>> +the same file, then it can easily combine them since there's no overlap.
>
> Many of the operations, even "git merge", is not about merging "two
> commits" together, but I do not think of a good way to explain it,
> so I accept that phrasing as a helpful white lie. I mention this
> because somebody else may be able to come up with a better phrasing
> that I (or authors of this iteration) couldn't think of.
>
>> +But if both sides edited overlapping lines of the same file (for example
>> +one side edited lines 1-5 and the other edited lines 3-6), Git will
>> +not try to guess how to combine those changes. This is called a "merge
>> +conflict".
>> +
>> +When this happens, Git shows you both sides' edits and asks you to pick
>> +how to resolve them. It:
>> +
>> +* Stages all of the files which were successfully merged
>> +* For the files with conflicts, it marks them as conflicted, puts both
>> + sides' edits in the file, and leaves <<markers, merge conflict markers>>
>> + that you need to resolve.
>
> By the way, I think we should briefly mention what sematnic merge
> conflicts are, and that Git does not detect them and that this
> manual page does not tell readers how to deal with them.
>
> Note that non-overlapping changes from two sides may leave the
> result in an inconsistent state. With the edit to lines 1-5,
> one side may have changed the name of a function, while with the
> edit to lines 20-25, the other side may have added a new call to
> the function by its original name. This type of inconsistencies
> are called semantic conflicts, Git has no way knowing that a
> merge introduced semantic conflicts, and ends up producing a
> broken result without merge conflicts. This document does not
> cover what to do with semantic conflicts.
>
> That is overly long, but perhaps you can condense it down to the
> essense and shrink down to 1/3 of the size.
I was thinking about that too. Maybe we can briefly mention that git's
merges are not guaranteed to produce working code even when they
succeed and point to an example further down the page.
Added to my list of things to work on.
>> +[[markers]]
>> +MERGE CONFLICT MARKERS
>> +----------------------
>> +
>> +When there's a merge conflict, Git will update the conflicted file
>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>
> I notice that when you introduce `diff3` below, you silently add
> `|||||||` to the mix without explaining what it is.
>
> `|||||||` may also be used as merge conflict markers (explained
> later).
>
> or something along the line here may help. Or explain what it is in
> `diff3` section. Either would work. Adding without explanation
> would not.
I think explaining it in the diff3 section makes sense, will do.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways:
>> +
>> +----
>> +FRUITS = [
>> + "apple",
>> +<<<<<<< HEAD
>> + "cherry",
>> +=======
>> + "banana",
>> +>>>>>>> add-fruit
>> + "mango",
>> + "orange",
>> +]
>> +----
>> +
>> +The code from one side of the merge conflict is between `<<<<<<<` and
>> +`=======`, and the code for the other side is between `=======` and
>> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
>> +of which side is which.
>
> If we said "one side wanted to have 'apple, cherry, mango, orange',
> while the other side wanted 'apply, banana, mango, orange', in the
> FRUITS array", would it help the understanding? Or is it too
> obvious?
I think it could make sense to add something here yes.
Added to my list.
>> +[[example]]
>> +EXAMPLE OF RESOLVING A MERGE CONFLICT
>> +-------------------------------------
>> +
>> +If you see this in your code during a merge conflict:
>> +
>> +----
>> +FRUITS = [
>> + "apple",
>> +<<<<<<< HEAD
>> + "cherry",
>> + "mango",
>> +=======
>> + "banana",
>> + "mango",
>> +>>>>>>> add-fruit
>> + "orange",
>> +]
>> +----
>
> It would make your readers puzzled why the example is subtly
> different from the earlier one that showed "mango" as not touched by
> either side. I see this lays the groundwork for later demonstration
> of `diff3`, so having both sides explicitly want "mango" is a good
> example. Perhaps update the first example to be the same as this
> one, which would reduce the mental burden by readers?
I very much agree it's important for the examples to match,
will work on that. It's a bit tricky with diff3 like you say.
>> +[[tools]]
>> +TOOLS FOR HANDLING MERGE CONFLICTS
>> +----------------------------------
>> +
>> +Here are some ways to get extra context while handling a merge conflict:
>> +
>> +* There are many graphical "merge tools" for Git, which will normally
>> + show you the different versions of the code side by side.
>> + If you have a mergetool configured, `git mergetool` will launch it.
>> + See also `merge.tool` in linkgit:git-config[1] for a list of
>> + the mergetools Git supports.
>> +
>> +* You can set the configuration option `merge.conflictstyle=diff3`.
>> + See <<diff3,DIFF3 AND ZDIFF3>> below for more.
>
> These are called 'configuration variables' throughout the manual
> pages. Be consistent and replace "configuration option" with
> "configuration variable", perhaps?
They seem to be both used interchangeably already:
```
$ grep 'configuration variable' *.adoc | wc -l
256
$ grep 'configuration option' *.adoc | wc -l
46
```
`git-config.adoc` uses the term "configuration option" 2 times
and "configuration variable" once. Is there supposed to be
some difference between these terms? As far as I can tell
from brief history spelunking Git has used those terms
interchangeably for a long time. AFAIK "configuration option"
is the term more often used outside Git.
>> +* `git log --merge -p <filename>` will list all commits which
>> + caused the merge conflict for `<filename>`, and the diff
>> + of how they changed the file.
>
> Maybe worth mentioning that `--left-right` often helps when you are
> not super familiar with the histories being merged.
I don't understand what this does or what it would be useful for so
it's not possible for me to explain it :). From my perspective
"ours" and "theirs" are already confusing enough and introducing
"left" and "right" seems like a lot. Is "left" the same as "ours"?
>> +* Look at the original files. `git show :1:filename` shows the
>> + common ancestor, `git show :2:filename` shows the "ours"
>> + version, and `git show :3:filename` shows the "theirs"
>> + version.
>
> Maybe it will help to say we will explain "ours" and "theirs" later
> in this document.
Plausible, added to my todo list to look at, thanks.
>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to
>> + resolve the conflicts.
>
> Does a "See below" here help readers who haven't learned what
> AUTO_MERGE is? If you can describe what AUTO_MERGE records (in
> other words, what you are comparing your progress against) in a
> sentence of two here, that would alleviate the need to assure them
> that we have more in-depth coverage on this topic elsewhere.
I think this is okay the way it is.
>> +[[git_status]]
>> +EXAMPLE: GIT STATUS OUTPUT
>> +--------------------------
>> +
>> +When you're in a merge conflict, you can find out what commands to run
>> +to handle the conflict by running `git status`.
>> +
>> +For example, this `git status` output tells you that:
>> +
>> +* `git rebase --abort` will safely bring your branch back to its
>> + original state
>> +* you should run `git rebase --continue` when you're done resolving all
>> + the conflicts
>> +* there's one file left with conflicts in it: `fruits.py`
>
> There may be users, after seeing the last point, left puzzled why
> fruits.py is still listed after they edited the file like instructed
> in an earlier example but haven't marked the resolution.
>
> `fruits.py` is not marked as its conflicts resolved yet.
>
> or something?
Thanks, agreed that "there's one file left with conflicts in it: `fruits.py`" isn't
precise enough. Will make it more accurate.
>> +----
>> +$ git status
>> +You are currently rebasing branch 'main' on '58a9fcc'.
>> + (fix conflicts and then run "git rebase --continue")
>> + (use "git rebase --skip" to skip this patch)
>> + (use "git rebase --abort" to check out the original branch)
>> +
>> +Unmerged paths:
>> + (use "git restore --staged <file>..." to unstage)
>> + (use "git add <file>..." to mark resolution)
>> + both modified: fruits.py
>> +----
>
> The approach to give explanations first and then an example the
> explanation explains next is refreshing to me. As long as the
> explanations are short enough, this may work better than the usual
> order to say "you'd see something like this. let us explain ...".
Glad to hear it!
>> +[[diff3]]
>> +DIFF3 AND ZDIFF3
>> +----------------
>> +
>> +By default, Git doesn't include the original code when formatting
>> +a merge conflict. To include the original code, you can set the
>> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.
>> +This extra context can make it much easier to understand what's
>> +happening in a merge conflict.
>
> I think most on the list considers `zdiff3` a failed experiment that
> reduces usefulness of `diff3`. Do we want to recommend it?
I'd be extremely happy to remove this if the list doesn't think zdiff3
is useful. When I was writing this I was confused by zdiff3 and thought
diff3 made a lot more sense.
Maybe we could add a note like this somewhere?
NOTE: zdiff3 was an experimental alternative to diff3 that makes
the merge conflict shorter by introducing more ambiguity.
It's still there for backwards compatibility but we don't recommend it.
> By the way, is it just me who finds those "Here's", "there's"
> contractions disturbing in an official manual? I've seen many of
> them while reviewing this to be annoyed enough and had to blurt it
> out X-<.
I find "here is" and "there is" to be distracting and overly formal,
different people are different I guess :)
>> +"Ours" and "theirs" are both commits: "ours" is the current
>> +`HEAD` commit, and "theirs" is the other side being merged.
>
> Now, "commits" is again a white lie. The story becomes more
> complicated when we talk about cherry-pick and revert, but if we
> primarily stick to what happens in 'merge' (which is what I've seen
> so far in this document), then it shouldn't add any extra difficulty
> to understand by saying "ours and theirs are history of changes
> leading to the two commits since they diverged from the original" to
> add clarity.
>
>> +The first part of a merge conflict (between `<<<<<<<` and `=======`) is
>> +from the "ours" side, and the second part (between `=======` and
>> +`>>>>>>>`) is from the "theirs" side.
>> +
>> +----
>> +FRUITS = [
>> + "apple",
>> +<<<<<<< HEAD
>> + "cherry", <- ours
>> +=======
>> + "banana", <- theirs
>> +>>>>>>> add-fruit
>> + "mango",
>> + "orange",
>> +]
>> +----
>> +
>> +During a rebase, it can seem "upside down" because the "ours" commit is
>> +from the branch you're rebasing on (for instance `main` in `git rebase
>> +main`).
>> +
>> +These terms in Git all mean the same thing when dealing with a merge
>> +conflict:
>> +
>> +* "common ancestor" and "base". The files from this commit are "in stage 1".
>> +* "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
>> +* "theirs", "them". The files from this commit are "in stage 3".
>> +
>> +If you're confused about what something like "deleted by us" means, it's
>> +often easiest to use some of the tools from
>> +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
>> +Finding the commit that deleted the file and seeing why is usually more
>> +helpful than trying to abstractly reason through what "us" means.
>> +
>> +[[automerge]]
>> +EXAMPLE OF USING `AUTO_MERGE`
>> +-----------------------------
>> +
>> +`git diff AUTO_MERGE` will show what changes you've made so far to
>> +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a
>> +merge. It contains the result of running the merge algorithm.
>
> The first sentence gave me "Huh? You haven't explained what
> AUTO_MERGE is yet". It may be just me, but I would have expected
> presentation order to be more like:
>
> When merge conflicts happen, the result of merge algorithm,
> together with conflict markers, is recorded in AUTO_MERGE. As
> you resolve conflicts, you can compare your working tree files
> against it with `git diff AUTO_MERGE` to see your progress.
Can take a look but I don't think it makes a big difference.
>> +For example, if we resolved the conflict by adding both "banana" and
>> +"cherry" in order, the diff would look like this:
>> +
>> +----
>> + FRUITS = [
>> + "apple",
>> +-<<<<<<< HEAD
>> +- "cherry",
>> +-=======
>> + "banana",
>> +->>>>>>> add-fruit
>> ++ "cherry",
>> + "mango",
>> + "orange",
>> + ]
>> +----
>
> Thanks.
>
>
> I was puzzled by this
>
>> - In "The only clean-ups you need are to reset the index file to the
>> `HEAD` commit to reverse 2. and to clean up working tree changes made
>> by 2. and 3.", it's not clear to users what "2" and "3" are supposed
>> to mean
>
> and did some digging.
>
> The text comes from ffb1a4bed5 (Documentation: Describe merge
> operation a bit better., 2005-11-28) that had "When there are
> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly
> merged paths are updated in the index 3. Conflicts are recorded in
> higher stage index entries and working tree files show conflict
> markers, 4. No other changes are done" well before the mysterious
> reference to 2. and 3.
>
> When ebef7e5049 (Documentation: simplify How Merge Works,
> 2010-01-23) tried to simplify the description, the list of "these
> things happen" were removed/rewritten, and yet instructions on how
> to reset are left behind, still referring to 2. and 3.
>
> We probably want a separate patch for Documentation/git-merge.adoc
> to rectify this 16 year old mistake.
Thanks for investigating!There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
>>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>>> + below for details)
>>> +* Or stop the operation and return your branch to its original state
>>> + with the appropriate `--abort` command, for example `git merge --abort`
>>> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>>> + for how to find the command to run.
>>
>> Both are good options and I do not think of a middle way. Perhaps
>> we do not have to say that these are "the most common" and instead
>> say "You handle a merge conflict by doing either of these two"?
>
> I agree the "the most common" is kind of weaselly and I'd like to be more clear.
> The reason I wrote "typically" is that during a rebase, there's an extra
> "skip" option, so it's not strictly true to say that there are just two options.
> Not sure if there's another option I'm not thinking of other than the
> "skip" in rebase.
I do not think anything like "rebase --skip" in a multi-step
integration is what this document covers particularly well to begin
with. Taking each conflicted step individually, with "skip", you
are stopping the operation without resolving the conflict.
Perhaps make it clear that in the above you are talking about what
to do with each individual opportunity to give back conflict
resolution to the command? If you describe these two choices in the
context of multi-step operation, each "we stopped due to conflict
and gave control back to you" opportunity gives you these choices:
* Give up, pretend this step did not exist, and continue.
* Resolve the conflict, record it, and continue.
In addition, you have "--abort" to give up the whole thing.
And a single step operation like "git merge" is a degenerated case
of the above. "and continue" part does not exist.
> I was thinking about that too. Maybe we can briefly mention that git's
> merges are not guaranteed to produce working code even when they
> succeed and point to an example further down the page.
> Added to my list of things to work on.
It's not limited to "GIt's merges" but applies in general.
>>> +[[tools]]
>>> +TOOLS FOR HANDLING MERGE CONFLICTS
>>> +----------------------------------
>>> +
>>> +Here are some ways to get extra context while handling a merge conflict:
>>> +
>>> +* There are many graphical "merge tools" for Git, which will normally
>>> + show you the different versions of the code side by side.
>>> + If you have a mergetool configured, `git mergetool` will launch it.
>>> + See also `merge.tool` in linkgit:git-config[1] for a list of
>>> + the mergetools Git supports.
>>> +
>>> +* You can set the configuration option `merge.conflictstyle=diff3`.
>>> + See <<diff3,DIFF3 AND ZDIFF3>> below for more.
>>
>> These are called 'configuration variables' throughout the manual
>> pages. Be consistent and replace "configuration option" with
>> "configuration variable", perhaps?
>
> They seem to be both used interchangeably already:
>
> ```
> $ grep 'configuration variable' *.adoc | wc -l
> 256
> $ grep 'configuration option' *.adoc | wc -l
> 46
> ```
Do not make it worse. The latter were mostly added people like you
who responds like the above; aim to be more consistent instead.
>>> +* `git log --merge -p <filename>` will list all commits which
>>> + caused the merge conflict for `<filename>`, and the diff
>>> + of how they changed the file.
>>
>> Maybe worth mentioning that `--left-right` often helps when you are
>> not super familiar with the histories being merged.
>
> I don't understand what this does or what it would be useful for so
> it's not possible for me to explain it :). From my perspective
> "ours" and "theirs" are already confusing enough and introducing
> "left" and "right" seems like a lot. Is "left" the same as "ours"?
If you do not understand what it does, perhaps try it out?
"git log -p --merge" is to break down the ours/theirs into
individual steps when changes on these sides were brought in in
multiple steps. It shows individual changes per commit, but if you
are not super familiar with these histories being merged, it is not
obvious which commit came from which side. And --left-right option
is a way to help you tell which one came from which.
>>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to
>>> + resolve the conflicts.
>>
>> Does a "See below" here help readers who haven't learned what
>> AUTO_MERGE is? If you can describe what AUTO_MERGE records (in
>> other words, what you are comparing your progress against) in a
>> sentence of two here, that would alleviate the need to assure them
>> that we have more in-depth coverage on this topic elsewhere.
>
> I think this is okay the way it is.
Is it because, unlike --left-right, you understand what it does?
Not everybody shares what you know, you know ;-)
* AUTO_MERGE records the initial merge result with conflict
markers. `git diff AUTO_MERGE` can be used to show how much
progress you made to resolve these conflicts.
perhaps.
> Maybe we could add a note like this somewhere?
>
> NOTE: zdiff3 was an experimental alternative to diff3 that makes
> the merge conflict shorter by introducing more ambiguity.
> It's still there for backwards compatibility but we don't recommend it.
Drop "experimental" and I am 100% behind that statement ;-).
>> By the way, is it just me who finds those "Here's", "there's"
>> contractions disturbing in an official manual? I've seen many of
>> them while reviewing this to be annoyed enough and had to blurt it
>> out X-<.
>
> I find "here is" and "there is" to be distracting and overly formal,
> different people are different I guess :)
I would prefer to be consistent in a single documentation set, though.
>> The text comes from ffb1a4bed5 (Documentation: Describe merge
>> operation a bit better., 2005-11-28) that had "When there are
>> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly
>> merged paths are updated in the index 3. Conflicts are recorded in
>> higher stage index entries and working tree files show conflict
>> markers, 4. No other changes are done" well before the mysterious
>> reference to 2. and 3.
>>
>> When ebef7e5049 (Documentation: simplify How Merge Works,
>> 2010-01-23) tried to simplify the description, the list of "these
>> things happen" were removed/rewritten, and yet instructions on how
>> to reset are left behind, still referring to 2. and 3.
>>
>> We probably want a separate patch for Documentation/git-merge.adoc
>> to rectify this 16 year old mistake.
>
> Thanks for investigating!
Heh, you already did the separate patch, which is [2/6], which I am
happy with.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
Comments on a few more points.
>> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order
>> to limit ourselves to most common ways to help new people by keeping
>> the description to the absolute minimum?
>
> It's deliberate, we talked about that a bit in the discussion of the v1.
> Can add a note in the commit message.
Being a part of _the_ technical manual on Git, I would like to see
us aim for completeness, and where we don't leave a note that the
description is not complete. In this case, between
Merge conflicts can happen during a `git merge`, `git rebase`, `git
cherry-pick`, `git pull`, `git am -3`, `git checkout -m`, `git
stash pop`, or `git revert`.
that aims for completeness and
Merge conflicts can happen during a `git merge`, `git rebase`, `git
cherry-pick`, `git pull`, or `git revert`, and other operations.
that admits the list is not complete, I have slight preference to
the first one.
>> By the way, is it just me who finds those "Here's", "there's"
>> contractions disturbing in an official manual? I've seen many of
>> them while reviewing this to be annoyed enough and had to blurt it
>> out X-<.
>
> I find "here is" and "there is" to be distracting and overly formal,
> different people are different I guess :)
But I wouldn't want you to be "different" here. This is not your
diary or personal note. This being a part of the technical manual,
I would prefer to see the same formalness applied everywhere.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Introduce a new page, `gitmergeconflicts`, that explains the process of
> handling a merge conflict in a way that addresses the following issues,
> which came from feedback from Git users on the current explanation of
> merge conflicts in the `git merge` man page:
>
> - The process for resolving a merge conflict is only explained in the
> ...
> - It sometimes uses the term "area" and sometimes uses the term "hunk"
It looks a bit annoying that these sentences in the enumeration all
lack their full stops.
> Only discuss merge, rebase, cherry-pick, and revert for now even though
> there are other ways that merge conflicts can happen because it's
> awkward to talk about `am`, `apply`, and `checkout -m`.
I do not know "because it's awkward" is a good justification,
though. "awkward" why?
It might be tempting to omit some commands that are less common for
new users, but we are touching the main part of the technical manual
that are meant ot be used by everybody, so that is not a good reason
to choose covering some but not others.
I however agree that it is better to avoid appearing to be complete
and leaving others (including future ones we add) with "any other
command that does a merge" as this round of document gives.
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> ...
> +There are 3 ways to handle a merge conflict:
> +
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> + below for details)
> +* Stop the operation and return your branch to its original state
> + with the appropriate `--abort` command, for example `git merge --abort`
> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
> + for how to find the command to run.
> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic
> + commit with the appropriate `--skip` command
The third entry is a nice addition. multi-step anything are the
same, including revert, right? I'd recommend updating it to
something like "if you are in a multi-step operation like `rebase`"
in the same spirit as the "or any other command" change you made at
the beginning of this file.
> +[NOTE]
> +================================
> +Even if Git successfully merges both sides with no conflicts, it's
> +possible to end up with code that doesn't work. For example, this can
> +happen if one side renames a function, and the other side adds a call to
> +the old function. This is called a "semantic merge conflict".
> +================================
OK.
> +When there's a merge conflict, Git will update the conflicted file
> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> +For example, here's a merge conflict where both sides edited a list of
> +fruits in different ways -- one side added "cherry" and the other side
> +added "banana":
You added "-- one side added ..." at the end, which I think sends a
wrong message. With rcs-merge style conflict, you cannot simply
tell, because it is ambiguous. The original may have had both
banana and cherry, in which case the sample output shows the result
of one side removing banana and the other side removing cherry.
The only thing you can say from the sample output below is in the
current state "one side has cherry where the other side has banana,
and everything else is the same". You cannot say more without
seeing diff3 style conflict.
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit
> + "mango",
> + "orange",
> +]
> +----
> +
> +The code from one side of the merge conflict is between `<<<<<<<` and
> +`=======`, and the code for the other side is between `=======` and
> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
> +of which side is which.
> +[[example]]
> +EXAMPLE OF RESOLVING A MERGE CONFLICT
> +-------------------------------------
> +
> +If you see this in your code during a merge conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit
> + "mango",
> + "orange",
> +]
> +----
> +
> +Then you might edit that part of the code like this,
> +which includes the fruits from both sides of the conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> + "banana",
> + "cherry",
> + "mango",
> + "orange",
> +]
> +----
So, this is one possible resolution. We cannot tell if it is the
correct one.
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> ...
The incremental changes to this list looks good.
> +[[diff3]]
> +DIFF3
> +-----
> +
> +By default, Git doesn't include the original code when formatting
> +a merge conflict. To include the original code, you can set the
> +configuration option `merge.conflictstyle` to `diff3`.
> +This extra context can make it much easier to understand what's
> +happening in a merge conflict.
> +
> +Here's an example of what a merge conflict would look like when using
> +`diff3`. There's an extra section (between `|||||||` and `=======`)
> +with the original code.
> +
> +With this view, you can see that both sides fixed a spelling
> +mistake in "mango", and each added one fruit to the list.
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> + "mango",
> +||||||| 1c22e48
> + "mangoooo",
> +=======
> + "banana",
> + "mango",
> +>>>>>>> add-fruit
> + "orange",
> +]
> +----
THis is a great example.
But an even better example would be to give this:
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry",
"mango",
||||||| 1c22e48
"banana",
"cherry",
"mangoooo",
=======
"banana",
"mango",
>>>>>>> add-fruit
"orange",
]
and tell the readers that that the correct resolution is to have
"apply, mango, orange", as each of cherry and banana was removed by
one side while the other side did not touch it. Having cherry and
banana in the result is a tempting but not always correct conclusion
unexperienced people would draw from the rcs-merge style output that
is ambiguous, and here is a great place to teach it in this flow.
Especially because it would make it stand out that the point of
diff3's verboseness compared to the rcs-merge output is to
disambiguate two cases. If you start from ABCmO and one side has
ABMO while the other side has ACMO, the right resolution would be
AMO (the above case I added), but if your starting point were AmO
and the two sides ends with ABMO and ACMO respectively, the right
resolution would be ABCMO. The rcs-merge output does not tell you
which is more likely to be correct, diff3 disambiguates these two
cases by being more verbose.
And telling that value of diff3 is about disambiguating is valuable
when ...
> +[NOTE]
> +================================
> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
> +shorter by making it more ambiguous.
> +================================
... this note tells the readers that zdiff3 is a ambigous variant of
diff3, hinting its flaw.
There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..3c6eaaddf8
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,330 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, `git revert`, or any other command that does
> +a merge. All of those commands use the same merge algorithm, and the
> +process for resolving a merge conflict is always very similar.
> +
> +There are 3 ways to handle a merge conflict:
> +
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> + below for details)
> +* Stop the operation and return your branch to its original state
> + with the appropriate `--abort` command, for example `git merge --abort`
> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
> + for how to find the command to run.
> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic
> + commit with the appropriate `--skip` command
Nit: the punctuation is a bit inconsistent, where the second bullet
point has a trailing punctuation mark but the other two don't.
> +WHAT IS A MERGE CONFLICT?
> +-------------------------
> +
> +When Git merges two commits together, it looks at the changes that
> +each side has made and combines those changes. For example, if one side
> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
> +the same file, then it can easily combine them since there's no overlap.
> +
> +But if both sides edited overlapping lines of the same file (for example
> +one side edited lines 1-5 and the other edited lines 3-6), Git will
> +not try to guess how to combine those changes. This is called a "merge
> +conflict".
> +
> +When this happens, Git shows you both sides' edits and asks you to pick
> +how to resolve them. It:
> +
> +* Stages all of the files which were successfully merged
> +* For the files with conflicts, it marks them as conflicted, puts both
> + sides' edits in the file, and leaves <<markers, merge conflict markers>>
> + that you need to resolve.
Same nit here.
> +[NOTE]
> +================================
> +Even if Git successfully merges both sides with no conflicts, it's
> +possible to end up with code that doesn't work. For example, this can
> +happen if one side renames a function, and the other side adds a call to
> +the old function. This is called a "semantic merge conflict".
> +================================
Good callout. We may also want to spell out the consequence of this:
"You should always verify the result of a merge regardless of whether or
not it has resulted in a conflict.".
> +[[resolve]]
> +HOW TO RESOLVE A MERGE CONFLICT
> +-------------------------------
> +
> +The process for resolving a merge conflict is:
> +
> +1. Run `git status` to get a list of files with merge conflicts
> +2. For each one, find the conflict markers
> + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
> + fix the conflict
> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
> +4. Run the appropriate `--continue` command to continue the operation
> + that was interrupted by the conflict, for example `git merge --continue`
> + or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
> + below for how to find the command to run.
Same nit regarding punctuation. Or is this actually a thing, where you
add punctuation in case it's multiple sentences but not in the case
where it's a single sentence, only? Maybe this is just me not being a
native speaker.
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> + show you the different versions of the code side by side.
> + If you have a mergetool configured, `git mergetool` will launch it.
> + See also `merge.tool` in linkgit:git-config[1] for a list of
> + the mergetools Git supports.
> +
> +* You can set the configuration variable `merge.conflictstyle=diff3`.
> + See <<diff3,DIFF3>> below for more.
> +
> +* `git log --merge -p <filename>` will list all commits which
Should we spell this out as `--patch` instead? That's way easier to grep
in the manpage in case the reader is curious what the option does.
> +[NOTE]
> +================================
> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
> +shorter by making it more ambiguous.
> +================================
"making it more ambiguous" reads rather curious. Should we maybe take
inspiration from its documentation and instead say "by removing matching
lines on the two sides from the beginning or end of a conflict region"?
> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Sometimes during a merge conflict, Git will use the terms "ours" and
> +"theirs" (or "us" and "them"). For example, `git status` might say that
> +a file was `deleted by us`.
> +
> +"Ours" and "theirs" are both commits: "ours" is the current
> +`HEAD` commit, and "theirs" is the other side being merged.
They may not always be commits, but they are always tree-ishs. But I
think it's fine to leave this as-is anyway, as the normal user is never
going to encounter cases where it's not in fact a commit. And when they
do they probably don't need this manpage anyway.
Other than this handful of nits I'm happy with this version, thanks!
Patrick |
||
| /Documentation/git-merge.adoc conflict-marker-size=32 | ||
| /Documentation/git-merge-file.adoc conflict-marker-size=32 | ||
| /Documentation/gitmergeconflicts.adoc conflict-marker-size=32 | ||
| /Documentation/gitk.adoc conflict-marker-size=32 | ||
| /Documentation/user-manual.adoc conflict-marker-size=32 | ||
| /t/t????-*.sh conflict-marker-size=32 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc | |
| MAN7_TXT += giteveryday.adoc | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> Documentation/Makefile | 1 +
> Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++
> Documentation/meson.build | 1 +
> 3 files changed, 296 insertions(+)
> create mode 100644 Documentation/gitmergeconflicts.adoc
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f8dea4b395..bc49641dda 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc
> MAN7_TXT += giteveryday.adoc
> MAN7_TXT += gitfaq.adoc
> MAN7_TXT += gitglossary.adoc
> +MAN7_TXT += gitmergeconflicts.adoc
This unfortunately needs to be accompanied with a matching change to
help the other build system.
You probably want to move your change to set conflict-marker-size
for this new file to this step, not at the end as if an
afterthought.
Documentation/meson.build | 1 +
1 file changed, 1 insertion(+)
diff --git c/Documentation/meson.build w/Documentation/meson.build
index 51647957e0..10b0637991 100644
--- c/Documentation/meson.build
+++ w/Documentation/meson.build
@@ -201,6 +201,7 @@ manpages = {
'giteveryday.adoc' : 7,
'gitfaq.adoc' : 7,
'gitglossary.adoc' : 7,
+ 'gitmergeconflicts.adoc' : 7,
'gitpacking.adoc' : 7,
'gitmergeconflicts.adoc' : 7,
'gitnamespaces.adoc' : 7,There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): Junio C Hamano <[email protected]> writes:
> This unfortunately needs to be accompanied with a matching change to
> help the other build system.
I did get a build failure due to meson, but apparently not due to
this step in the 7-patch series.
> You probably want to move your change to set conflict-marker-size
> for this new file to this step, not at the end as if an
> afterthought.
This still stands, though.
Sorry, a wrong patch and a false alarm.
>
>
> Documentation/meson.build | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git c/Documentation/meson.build w/Documentation/meson.build
> index 51647957e0..10b0637991 100644
> --- c/Documentation/meson.build
> +++ w/Documentation/meson.build
> @@ -201,6 +201,7 @@ manpages = {
> 'giteveryday.adoc' : 7,
> 'gitfaq.adoc' : 7,
> 'gitglossary.adoc' : 7,
> + 'gitmergeconflicts.adoc' : 7,
> 'gitpacking.adoc' : 7,
> 'gitmergeconflicts.adoc' : 7,
> 'gitnamespaces.adoc' : 7,There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Thu, Sep 24, 2026 at 02:44:16PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..612b683e40
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,294 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +
> +SYNOPSIS
> +--------
> +Guide to handling merge conflicts
> +
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
Should all of these be using linkgit:, like for example in
linkgit:git-merge[1]?
> +the same merge algorithm, and the process for resolving a merge conflict
> +is always very similar.
There's also git-am(1), but only when adding the "--3way" flag. So maybe
it's best to ignore that command indeed.
> +The most common ways to handle a merge conflict are:
> +
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> + below for details)
> +* Or stop the operation and return your branch to its original state
> + with the appropriate `--abort` command, for example `git merge --abort`
> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
> + for how to find the command to run.
I wonder whether the explanation should be expanded a bit to briefly
explain how Git performs a 3-way merge in the first place. I feel like
it's quite important to understand what the three different sides of the
merge are to make sense of it.
But I may be too far detached from the "normal" user, so this may only
cause more confusion for our users.
> +[[markers]]
> +MERGE CONFLICT MARKERS
> +----------------------
> +
> +Merge conflicts happen when both of the sides being merged edit the same
> +area of a file. When this happens, Git will update the conflicted file
I wonder whether we want to use "hunk" instead of "area". It's jargon
again, but I have never heard anybody speak about an "area" before
myself.
> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> +For example, here's a merge conflict where both sides edited a list of
> +fruits in different ways:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit
A bit of a tangent, but sometimes I wonder whether we should make the
respective commits a bit easier to access. For example, we could put the
equivalent of `git rev-parse --reference <commit>` here for each of the
sides.
> + "mango",
> + "orange",
> +]
> +----
> +
> +The code from one side of the merge conflict is between `<<<<<<<` and
> +`=======`, and the code for the other side is between `=======` and
> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
> +of which side is which.
> +
> +
> +[[resolve]]
> +HOW TO RESOLVE A MERGE CONFLICT
> +-------------------------------
> +
> +The process for resolving a merge conflict is:
> +
> +1. Run `git status` to get a list of files with merge conflicts
> +2. For each one, find the conflict markers
> + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
> + fix the conflict
> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
> +4. Run the appropriate `--continue` command to continue the operation
> + that was interrupted by the conflict, for example `git merge --continue`
> + or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
> + below for how to find the command to run.
> ++
> +Note: During a `git merge`, `git commit` and `git merge --continue` do
> +the the same thing.
s/the the/the/
Maybe we should also say "During a conflicted `git merge`.", but maybe
that's redundant.
> +[[example]]
> +EXAMPLE OF RESOLVING A MERGE CONFLICT
> +-------------------------------------
> +
> +If you see this in your code during a merge conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> + "mango",
> +=======
> + "banana",
> + "mango",
> +>>>>>>> add-fruit
> + "orange",
> +]
> +----
> +
> +Then you might edit that part of the code like this,
> +which includes the fruits from both sides of the conflict:
I tend to forget that by default, we only render ours/theirs in the
conflict. I always feel like that makes it way harder to resolve
conflicts as you don't have the context of what the code looked like
originally. So I have diff3 configured locally for ages.
> +----
> +FRUITS = [
> + "apple",
> + "banana",
> + "cherry",
> + "mango",
> + "orange",
> +]
> +----
> +
> +
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> + show you the different versions of the code side by side.
> + If you have a mergetool configured, `git mergetool` will launch it.
> + See also `merge.tool` in linkgit:git-config[1] for a list of
> + the mergetools Git supports.
There's also `git merge-tool --tool-help` to list all available drivers.
[snip]
> +[[diff3]]
> +DIFF3 AND ZDIFF3
> +----------------
> +
> +By default, Git doesn't include the original code when formatting
> +a merge conflict. To include the original code, you can set the
> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.
> +This extra context can make it much easier to understand what's
> +happening in a merge conflict.
Indeed.
[snip]
> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Git refers to the first part of a merge conflict (between `<<<<<<<`
> +and `=======`) as "ours" and the second part (between `=======` and
> +`>>>>>>>`) as "theirs".
> +
> +Normally, "ours" is the commit that was checked out before you started
> +the merge, and "theirs" is the other commit.
> +
> +But when the merge conflict was caused by a `git rebase`, it's the
> +opposite: "theirs" is the commit that was checked out before you started
> +the merge. This is because under the hood, `git rebase main` checks out
> +the `main` commit first before doing the merge operation.
Hmm. This part is a bit confusing to me. "ours" is always the commit
that's currently checked out, and "theirs" is always the one that is
getting merged into the checked-out commit.
How about a variant of the following instead?
In a conflict, the side between `<<<<<<<` and `=======` is "ours"
and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
always the side that `HEAD` points to while the merge happens; "theirs"
is the commit being merged into it.
For `git merge <other>`, `HEAD` is your current branch, so "ours" is
your branch and "theirs" is `<other>`.
For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
your commits are then replayed on top one at a time. So "ours" is the
already-rebased history starting at `<upstream>`, and "theirs" is the
commit from your original branch that is currently being replayed.
> +These terms in Git all mean the same thing when dealing with a merge
> +conflict:
> +
> +* "common ancestor", "base", and "stage 1"
> +* "ours", "us", "stage 2", and `HEAD`
> +* "theirs", "them", and "stage 3"
I wouldn't say that "stage N" is equivalent to the respective other
terms. These stages rather refer to the different versions of a specific
file as recorded in the index, they do not indicate a specific commit.
In contrast to that, all the other terms may also indicate a specific
version of a file, but may also refer to the commits.
PatrickThere was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): >> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
>
> Should all of these be using linkgit:, like for example in
> linkgit:git-merge[1]?
Makes sense to me, will change.
>> +The most common ways to handle a merge conflict are:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> + below for details)
>> +* Or stop the operation and return your branch to its original state
>> + with the appropriate `--abort` command, for example `git merge --abort`
>> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>> + for how to find the command to run.
>
> I wonder whether the explanation should be expanded a bit to briefly
> explain how Git performs a 3-way merge in the first place. I feel like
> it's quite important to understand what the three different sides of the
> merge are to make sense of it.
>
> But I may be too far detached from the "normal" user, so this may only
> cause more confusion for our users.
I think it would cause more confusion. I did some experiments in explaining
merge conflicts using the concept of 3-way merge a couple of years
ago and it didn't go well.
My experience was that what users they found the most useful was
learning about the tools Git offers (like `git diff --check` and `diff3`),
so that's why this document focuses on tools and formatting much
more than concepts.
I think it would be cool to find a way to explain how 3-way merge works at in
this document in some later iteration though, maybe at the end. Definitely some
folks would find it interesting. I didn't understand 3-way merge myself until a
couple of years ago and it was fun for me to learn, but it didn't really help me
use Git effectively.
(this is quickly becoming a bit of a novel, but it's often very counterintuitive
how some facts that seem "fundamental" about how Git works actually turn
out to not be very important to understand in practice to use it effectively.
It's something I find tough to talk about on this mailing list because it's something
I've only been able to learn empirically)
>> +[[markers]]
>> +MERGE CONFLICT MARKERS
>> +----------------------
>> +
>> +Merge conflicts happen when both of the sides being merged edit the same
>> +area of a file. When this happens, Git will update the conflicted file
>
> I wonder whether we want to use "hunk" instead of "area". It's jargon
> again, but I have never heard anybody speak about an "area" before
> myself.
Ah thanks, I think I took "area" from the `git-merge` man page.
I looked up how I explained this previously and I used "lines of code",
which I think communicates the same meaning without the jargon.
I'll try that instead.
>> +Note: During a `git merge`, `git commit` and `git merge --continue` do
>> +the the same thing.
>
> s/the the/the/
Will fix.
>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways:
>> +
>> +----
>> +FRUITS = [
>> + "apple",
>> +<<<<<<< HEAD
>> + "cherry",
>> +=======
>> + "banana",
>> +>>>>>>> add-fruit
> Hide quoted text
>
> A bit of a tangent, but sometimes I wonder whether we should make the
> respective commits a bit easier to access. For example, we could put the
> equivalent of `git rev-parse --reference <commit>` here for each of the
> sides.
Personally I'm not sure if the commit ID would do much for me, but I feel
like it would help me if it were possible to include the commit message.
> I tend to forget that by default, we only render ours/theirs in the
> conflict. I always feel like that makes it way harder to resolve
> conflicts as you don't have the context of what the code looked like
> originally. So I have diff3 configured locally for ages.
Every time I show people diff3 someone tells me how happy they
are to learn it :)
>> +* There are many graphical "merge tools" for Git, which will normally
>> + show you the different versions of the code side by side.
>> + If you have a mergetool configured, `git mergetool` will launch it.
>> + See also `merge.tool` in linkgit:git-config[1] for a list of
>> + the mergetools Git supports.
>
> There's also `git merge-tool --tool-help` to list all available drivers.
Oh, cool! It's fun that it autodetects which ones you have installed
on your system. I'll suggest that.
>
> [snip]
>> +[[ours]]
>> +"OURS" AND "THEIRS"
>> +-------------------
>> +
>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>> +and `=======`) as "ours" and the second part (between `=======` and
>> +`>>>>>>>`) as "theirs".
>> +
>> +Normally, "ours" is the commit that was checked out before you started
>> +the merge, and "theirs" is the other commit.
>> +
>> +But when the merge conflict was caused by a `git rebase`, it's the
>> +opposite: "theirs" is the commit that was checked out before you started
>> +the merge. This is because under the hood, `git rebase main` checks out
>> +the `main` commit first before doing the merge operation.
>
> Hmm. This part is a bit confusing to me. "ours" is always the commit
> that's currently checked out, and "theirs" is always the one that is
> getting merged into the checked-out commit.
>
> How about a variant of the following instead?
>
> In a conflict, the side between `<<<<<<<` and `=======` is "ours"
> and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
> always the side that `HEAD` points to while the merge happens; "theirs"
> is the commit being merged into it.
>
> For `git merge <other>`, `HEAD` is your current branch, so "ours" is
> your branch and "theirs" is `<other>`.
>
> For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
> your commits are then replayed on top one at a time. So "ours" is the
> already-rebased history starting at `<upstream>`, and "theirs" is the
> commit from your original branch that is currently being replayed.
Thanks, your suggestion gives me some other ways to think about this.
I think I'll try to write something shorter that is unambiguous, instead of trying
to use more words to make it feel more intuitive. I don't think I actually know
anyone who feels it's easy to understand the way merge conflicts are
presented, and more explanation may not help.
It might be more useful here to encourage (again) folks to use one of the many
amazing tools available (in the "tools" section) to get more context.
>> +These terms in Git all mean the same thing when dealing with a merge
>> +conflict:
>> +
>> +* "common ancestor", "base", and "stage 1"
>> +* "ours", "us", "stage 2", and `HEAD`
>> +* "theirs", "them", and "stage 3"
>
> I wouldn't say that "stage N" is equivalent to the respective other
> terms. These stages rather refer to the different versions of a specific
> file as recorded in the index, they do not indicate a specific commit.
> In contrast to that, all the other terms may also indicate a specific
> version of a file, but may also refer to the commits.
Thanks, will try to figure out how to make it more accurate.
We could also refer to gitdatamodel if folks want to learn what the
term "stage" means too.
Thanks for the review!
- JuliaThere was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
>>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>>> +For example, here's a merge conflict where both sides edited a list of
>>> +fruits in different ways:
>>> +
>>> +----
>>> +FRUITS = [
>>> + "apple",
>>> +<<<<<<< HEAD
>>> + "cherry",
>>> +=======
>>> + "banana",
>>> +>>>>>>> add-fruit
>> Hide quoted text
>>
>> A bit of a tangent, but sometimes I wonder whether we should make the
>> respective commits a bit easier to access. For example, we could put the
>> equivalent of `git rev-parse --reference <commit>` here for each of the
>> sides.
>
> Personally I'm not sure if the commit ID would do much for me, but I feel
> like it would help me if it were possible to include the commit message.
It would also help the resolution, not just committing after you are
done. It may not matter while picking between cherry and banana to
show your personal preference on fruits, but in a more involved
conflicted merge, it may help to be able to view "git show $commit",
"git diff ...$commit", and "git diff $commit..." where $commit is
the "add-fruit" side of the merge to understand what they wanted to
do, and what we have done while they weren't looking.
>> I tend to forget that by default, we only render ours/theirs in the
>> conflict. I always feel like that makes it way harder to resolve
>> conflicts as you don't have the context of what the code looked like
>> originally. So I have diff3 configured locally for ages.
>
> Every time I show people diff3 someone tells me how happy they
> are to learn it :)
Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
this strongly enough to think it should become the default).
Knowing what the original was before one side wanted to say "cherry"
while the other side wanted to say "banana" sometimes helps a great
deal to decide what to do with the conflict.There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote:
> "Julia Evans" <[email protected]> writes:
>
> >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> >>> +For example, here's a merge conflict where both sides edited a list of
> >>> +fruits in different ways:
> >>> +
> >>> +----
> >>> +FRUITS = [
> >>> + "apple",
> >>> +<<<<<<< HEAD
> >>> + "cherry",
> >>> +=======
> >>> + "banana",
> >>> +>>>>>>> add-fruit
> >> Hide quoted text
> >>
> >> A bit of a tangent, but sometimes I wonder whether we should make the
> >> respective commits a bit easier to access. For example, we could put the
> >> equivalent of `git rev-parse --reference <commit>` here for each of the
> >> sides.
> >
> > Personally I'm not sure if the commit ID would do much for me, but I feel
> > like it would help me if it were possible to include the commit message.
>
> It would also help the resolution, not just committing after you are
> done. It may not matter while picking between cherry and banana to
> show your personal preference on fruits, but in a more involved
> conflicted merge, it may help to be able to view "git show $commit",
> "git diff ...$commit", and "git diff $commit..." where $commit is
> the "add-fruit" side of the merge to understand what they wanted to
> do, and what we have done while they weren't looking.
Yup. Doesn't mean we cannot _also_ include the names that we have above.
So in the above example it could be for example:
+FRUITS = [
+ "apple",
+<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
+ "cherry",
+=======
+ "banana",
+>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)
That format would have a bunch of advantages:
- We don't have to teach users about special refs like MERGE_HEAD to
let them figure out how to access each of the commits.
- It gives a bit more context about what each specific side does, at
least if you have good commit messages.
- It also gives a sense of timing because we include dates, and that
may help in some situations to figure out what's what.
I'll create an issue on the GitLab side and ask someone in the team to
maybe give this a try.
> >> I tend to forget that by default, we only render ours/theirs in the
> >> conflict. I always feel like that makes it way harder to resolve
> >> conflicts as you don't have the context of what the code looked like
> >> originally. So I have diff3 configured locally for ages.
> >
> > Every time I show people diff3 someone tells me how happy they
> > are to learn it :)
>
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.
I very much agree that it should be the default.
PatrickThere was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): > +FRUITS = [
> + "apple",
> +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)
>
> That format would have a bunch of advantages:
>
> - We don't have to teach users about special refs like MERGE_HEAD to
> let them figure out how to access each of the commits.
>
> - It gives a bit more context about what each specific side does, at
> least if you have good commit messages.
>
> - It also gives a sense of timing because we include dates, and that
> may help in some situations to figure out what's what.
This is so cool, I love the idea of including the dates and the commit
messages!!! I think this would be very helpful for the reasons you say.
Though re "We don't have to teach users about special refs
like MERGE_HEAD": I think that users today could run`git show HEAD`
or `git show add-fruit` to see the commits on each side? I've never
used MERGE_HEAD though so maybe I'm misunderstanding what
it does. I think adding the commit ID makes it clearer too.
I just ran downstairs to show my partner this example at 8am
because I was so excited about it :) (he liked it too)There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): Junio C Hamano <[email protected]> writes:
>>>> +FRUITS = [
>>>> + "apple",
>>>> +<<<<<<< HEAD
>>>> + "cherry",
>>>> +=======
>>>> + "banana",
>>>> +>>>>>>> add-fruit
>
>> Every time I show people diff3 someone tells me how happy they
>> are to learn it :)
>
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.
Before I forget, here is a good illustration to tell why diff3 style
is often essential to correct conflict resolution that we can tell
new users. You may want to throw it in to your new manual pages.
If the conflict looks like this
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry",
|||||||
=======
"banana",
>>>>>>> add-fruit
then we can tell that in the beginning there was only 'apple', and
one side wanted to add 'cherry', while the other side wanted to add
'banana'. It is likely that we would make both sides happy by
adding both of them.
But on the other hand, if the conflict looks like this
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry",
|||||||
"banana",
"cherry",
=======
"banana",
>>>>>>> add-fruit
we can tell that before two sides started editing, we had 'apple',
'banana', and 'cherry'. While both wanted to keep 'apple', one side
did not want 'banana', and the other side did not want 'cherry'. It
is plausible that we can please both of them by removing these two.
With just two-sides, the user who is trying to resolve the conflict
cannot tell the difference.There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): >> [snip]
>>> +[[ours]]
>>> +"OURS" AND "THEIRS"
>>> +-------------------
>>> +
>>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>>> +and `=======`) as "ours" and the second part (between `=======` and
>>> +`>>>>>>>`) as "theirs".
>>> +
>>> +Normally, "ours" is the commit that was checked out before you started
>>> +the merge, and "theirs" is the other commit.
>>> +
>>> +But when the merge conflict was caused by a `git rebase`, it's the
>>> +opposite: "theirs" is the commit that was checked out before you started
>>> +the merge. This is because under the hood, `git rebase main` checks out
>>> +the `main` commit first before doing the merge operation.
>>
>> Hmm. This part is a bit confusing to me. "ours" is always the commit
>> that's currently checked out, and "theirs" is always the one that is
>> getting merged into the checked-out commit.
>>
>> How about a variant of the following instead?
>>
>> In a conflict, the side between `<<<<<<<` and `=======` is "ours"
>> and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
>> always the side that `HEAD` points to while the merge happens; "theirs"
>> is the commit being merged into it.
>>
>> For `git merge <other>`, `HEAD` is your current branch, so "ours" is
>> your branch and "theirs" is `<other>`.
>>
>> For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
>> your commits are then replayed on top one at a time. So "ours" is the
>> already-rebased history starting at `<upstream>`, and "theirs" is the
>> commit from your original branch that is currently being replayed.
>
> Thanks, your suggestion gives me some other ways to think about this.
>
> I think I'll try to write something shorter that is unambiguous,
> instead of trying
> to use more words to make it feel more intuitive. I don't think I
> actually know
> anyone who feels it's easy to understand the way merge conflicts are
> presented, and more explanation may not help.
>
> It might be more useful here to encourage (again) folks to use one of the many
> amazing tools available (in the "tools" section) to get more context.
>
>>> +These terms in Git all mean the same thing when dealing with a merge
>>> +conflict:
>>> +
>>> +* "common ancestor", "base", and "stage 1"
>>> +* "ours", "us", "stage 2", and `HEAD`
>>> +* "theirs", "them", and "stage 3"
>>
>> I wouldn't say that "stage N" is equivalent to the respective other
>> terms. These stages rather refer to the different versions of a specific
>> file as recorded in the index, they do not indicate a specific commit.
>> In contrast to that, all the other terms may also indicate a specific
>> version of a file, but may also refer to the commits.
>
> Thanks, will try to figure out how to make it more accurate.
> We could also refer to gitdatamodel if folks want to learn what the
> term "stage" means too.
Marie and I worked on the OURS AND THEIRS section today and I think it's clearer
now but also longer (instead of shorter which was my dream). We added an attempt
at humor at the end to hopefully help things a bit.
"OURS" AND "THEIRS"
-------------------
Sometimes during a merge conflict, Git will use the terms "ours" and
"theirs" (or "us" and "them"). For example, `git status` might say that
a file was `deleted by us`.
"Ours" and "theirs" are both commits: "ours" is the current
`HEAD` commit, and "theirs" is the other side being merged.
The first part of a merge conflict (between `<<<<<<<` and `=======`) is
from the "ours" side, and the second part (between `=======` and
`>>>>>>>`) is from the "theirs" side.
----
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry", <- ours
=======
"banana", <- theirs
>>>>>>> add-fruit
"mango",
"orange",
]
----
During a rebase, it can seem "upside down" because the "ours" commit is
from the branch you're rebasing on (for instance `main` in `git rebase
main`).
These terms in Git all mean the same thing when dealing with a merge
conflict:
* "common ancestor" and "base". The files from this commit are "in stage 1".
* "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
* "theirs", "them". The files from this commit are "in stage 3".
If you're confused about what something like "deleted by us" means, it's
often easiest to use some of the tools from
<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
Finding the commit that deleted the file and seeing why is usually more
helpful than trying to abstractly reason through what "us" means.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
> Marie and I worked on the OURS AND THEIRS section today and I think it's clearer
> now but also longer (instead of shorter which was my dream). We added an attempt
> at humor at the end to hopefully help things a bit.
>
> "OURS" AND "THEIRS"
> -------------------
>
> Sometimes during a merge conflict, Git will use the terms "ours" and
> "theirs" (or "us" and "them"). For example, `git status` might say that
> a file was `deleted by us`.
>
> "Ours" and "theirs" are both commits: "ours" is the current
> `HEAD` commit, and "theirs" is the other side being merged.
>
> The first part of a merge conflict (between `<<<<<<<` and `=======`) is
> from the "ours" side, and the second part (between `=======` and
> `>>>>>>>`) is from the "theirs" side.
>
> ----
> FRUITS = [
> "apple",
> <<<<<<< HEAD
> "cherry", <- ours
> =======
> "banana", <- theirs
> >>>>>>> add-fruit
> "mango",
> "orange",
> ]
> ----
>
> During a rebase, it can seem "upside down" because the "ours" commit is
> from the branch you're rebasing on (for instance `main` in `git rebase
> main`).
>
> These terms in Git all mean the same thing when dealing with a merge
> conflict:
>
> * "common ancestor" and "base". The files from this commit are "in stage 1".
> * "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
> * "theirs", "them". The files from this commit are "in stage 3".
>
> If you're confused about what something like "deleted by us" means, it's
> often easiest to use some of the tools from
> <<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
> Finding the commit that deleted the file and seeing why is usually more
> helpful than trying to abstractly reason through what "us" means.
May I ask what is in scope for this effort?
We previously discussed updating the conflict markers (the 'HEAD'
and 'add-fruit' labels in the example above). Doing so would
require code changes, which goes beyond mere documentation updates.
But if a minor code change like that makes the documentation much
easier to understand, I think we should consider doing so.
Along the same line, if git status stopped saying "deleted by us"
and instead used a different phrase, would that help reduce the
"upside down" confusion [*]? Is it acceptable to bend the code
a little if it helps the documentation?
[Footnote]
* I suspect that the "upside down" feeling is not really about the
terms "ours" and "theirs" themselves. Rather, it comes from how
one conceptualizes what 'rebase' does compared to 'merge'.
During a rebase, we temporarily pretend that we are working on
the upstream branch and replay our local changes on top of it.
Once the user adopts this mindset, displaying the upstream state
first (the point from which we start building the consolidated
history) followed by the local state (what was done differently
by the local side) becomes consistent with how 'merge' displays
conflicts (where we start from our local state and merge the
incoming changes).There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): >> During a rebase, it can seem "upside down" because the "ours" commit is
>> from the branch you're rebasing on (for instance `main` in `git rebase
>> main`).
>>
>> These terms in Git all mean the same thing when dealing with a merge
>> conflict:
>>
>> * "common ancestor" and "base". The files from this commit are "in stage 1".
>> * "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
>> * "theirs", "them". The files from this commit are "in stage 3".
>>
>> If you're confused about what something like "deleted by us" means, it's
>> often easiest to use some of the tools from
>> <<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
>> Finding the commit that deleted the file and seeing why is usually more
>> helpful than trying to abstractly reason through what "us" means.
>
> May I ask what is in scope for this effort?
>
> We previously discussed updating the conflict markers (the 'HEAD'
> and 'add-fruit' labels in the example above). Doing so would
> require code changes, which goes beyond mere documentation updates.
> But if a minor code change like that makes the documentation much
> easier to understand, I think we should consider doing so.
>
> Along the same line, if git status stopped saying "deleted by us"
> and instead used a different phrase, would that help reduce the
> "upside down" confusion [*]? Is it acceptable to bend the code
> a little if it helps the documentation?
I agree that would make sense. I have some changes to advice
(on other areas) in local branches on my machine already :)
I think of it as sort of "documentation driven development" (write the
documentation, and if it feels upsetting what the documentation is
saying, then try to change the code so we're happier with the docs!)
I don't have a clear idea for how to improve the way `git status`
presents merge conflicts to make it less confusing right now though.
Brainstorming a bit, here's some commentary on this `git status` output:
On branch main
Your branch and 'origin/main' have diverged,
and have 2 and 1 different commits each, respectively.
(use "git pull" if you want to integrate the remote branch with yours)
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: fruits.py
no changes added to commit (use "git add" and/or "git commit -a")
1. `(use "git pull" if you want to integrate the remote branch with yours)`
is not helpful advice here, it's not even allowed to run `git pull`
in the middle of a merge conflict.
2. `git add` is sort of not helpful here, all of the unmerged files currently
have conflict markers, so the next step is definitely not to run `git add`,
it's to edit one of the unmerged files. But perhaps it's unrealistic to
be running the equivalent of `git diff --check` in `git status` just to
help users out.
3. Not sure if "unmerged" is the best term here, maybe "conflicted"?
4. It gives the advice to use `git add` twice which is weird.
5. One part of the advice refers to the process of fixing conflicts as
"fix conflicts" but the other part calls it "mark resolution". Should
probably be consistent there.
But as you can see those comments are all over the place, some of them
are just wording changes, some of them would involve adding a bunch of
conditional logic to the advice system that might not be realistic,
I don't know.
> [Footnote]
>
> * I suspect that the "upside down" feeling is not really about the
> terms "ours" and "theirs" themselves. Rather, it comes from how
> one conceptualizes what 'rebase' does compared to 'merge'.
> During a rebase, we temporarily pretend that we are working on
> the upstream branch and replay our local changes on top of it.
> Once the user adopts this mindset, displaying the upstream state
> first (the point from which we start building the consolidated
> history) followed by the local state (what was done differently
> by the local side) becomes consistent with how 'merge' displays
> conflicts (where we start from our local state and merge the
> incoming changes).
I will say that I know all of these facts but it has never helped
me to remember "ours" and "theirs" :). I'm pretty resistant in general
to telling people they need to adopt the "right mindset", IMO
it's normal for people to have different points of view.
When explaining Git I heard a lot of "yes I know all that but I just
don't like to think about it that way" and it really helped me
to learn to respect when folks said that and try to see it from
their point of view. |
||
| MAN7_TXT += gitfaq.adoc | ||
| MAN7_TXT += gitglossary.adoc | ||
| MAN7_TXT += gitmergeconflicts.adoc | ||
| MAN7_TXT += gitpacking.adoc | ||
| MAN7_TXT += gitnamespaces.adoc | ||
| MAN7_TXT += gitremote-helpers.adoc | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -19,8 +19,7 @@ Given one or more existing commits, apply the change each one | |
| introduces, recording a new commit for each. This requires your | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Remove the discussion of merge conflicts and replace it with a link to
> the guide.
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-cherry-pick.adoc | 23 ++++-------------------
> 1 file changed, 4 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index f4cd8b9db7..d93829600b 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one
> introduces, recording a new commit for each. This requires your
> working tree to be clean (no modifications from the HEAD commit).
>
> -When it is not obvious how to apply a change, the following
> -happens:
> -
> -1. The current branch and `HEAD` pointer stay at the last commit
> - successfully made.
> -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
> - introduced the change that is difficult to apply, unless the
> - `--no-commit` option was given.
> -3. Paths in which the change applied cleanly are updated both
> - in the index file and in your working tree.
> -4. For conflicting paths, the index file records up to three
> - versions, as described in the "TRUE MERGE" section of
> - linkgit:git-merge[1]. The working tree files will include
> - a description of the conflict bracketed by the usual
> - conflict markers `<<<<<<<` and `>>>>>>>`.
> -5. No other modifications are made.
> -
> -See linkgit:git-merge[1] for some hints on resolving such
> -conflicts.
> +When it is not obvious how to apply a change, there may
> +be a merge conflict. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.
The new document may explain how to resolve conflicts, but are the
details removed from here that are specific to the 'cherry-pick'
operation also covered there?
For example, during a difficult cherry-pick, it is often handy to be
able to run 'git show CHERRY_PICK_HEAD', but now users are not told
about the pseudo-ref, which seems like a real loss.
The fact that cleanly auto-resolved contents for paths are recorded
in the index may be shared with all other merge-like operations,
and it need not be part of the "how to resolve a conflicted
merge-like operation" recipe, but users need to be assured that this
is what happens somewhere in the documentation set. The list
removed here served that purpose for this specific command, but it
is now gone.
I do not recall offhand whether we explicitly tell our users that
all merge-like operations update the index with cleanly auto-resolved
results and only leave conflicts to be hand-resolved by the user,
but even if we did so elsewhere, I do not see any reference to that
in the existing text of the 'cherry-pick' manual, nor does this
patch series add such a link. At least item #2 and #3 should be
kept in the list, I think. A better alternative might be to add
your new reference, and shorten the description given in item #4,
and leave everything else as before.
Thanks.
>
> OPTIONS
> -------
> @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^ <4>
> SEE ALSO
> --------
> linkgit:git-revert[1]
> +linkgit:gitmergeconflicts[7]
>
> GIT
> ---There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): > The new document may explain how to resolve conflicts, but are the
> details removed from here that are specific to the 'cherry-pick'
> operation also covered there?
I'll update this series to make fewer changes to this page as you
suggest to make the diff smaller.
> For example, during a difficult cherry-pick, it is often handy to be
> able to run 'git show CHERRY_PICK_HEAD', but now users are not told
> about the pseudo-ref, which seems like a real loss.
I'll put this back for now, but I removed it because I couldn't
understand why CHERRY_PICK_HEAD might be useful, and some of my user research
showed that almost nobody uses `CHERRY_PICK_HEAD`. I always appreciate people
telling me why these things are actually useful though, and even if very few
people use something, maybe more people would use it if it was clear why it's
useful :)
My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
only useful if you're cherry-picking multiple commits at the same time.
Is the following an accurate explanation?:
> If the conflict happened when cherry picking multiple commits, you can run
> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.
> The fact that cleanly auto-resolved contents for paths are recorded
> in the index may be shared with all other merge-like operations,
> and it need not be part of the "how to resolve a conflicted
> merge-like operation" recipe, but users need to be assured that this
> is what happens somewhere in the documentation set. The list
> removed here served that purpose for this specific command, but it
> is now gone.
That makes sense to me. One major benefit of making a
centralized page is that each man page explains different aspects
of the merge conflict process, and we can make sure that anyone
who needs to solve a merge conflict is aware of all the aspects.
I'll think about how to explain that.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
> My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
> only useful if you're cherry-picking multiple commits at the same time.
> Is the following an accurate explanation?:
>
>> If the conflict happened when cherry picking multiple commits, you can run
>> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.
You do not have to limit yourself to the multi-pick case. If you
make it a habit to use CHERRY_PICK_HEAD, you do not have to remember
exactly which commit you specified on the command line to pick when
stopped by a conflict during a cherry-pick. This is especially true
for those who have already made it a habit to use MERGE_HEAD when
stopped by a conflict during a merge. Not having to think when you
can mechanically perform a routine task is bliss.
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> -When it is not obvious how to apply a change, the following
> -happens:
> +When it is not obvious how to apply a change, there may
> +be a merge conflict. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.
"Obvious to whom" was the first thing that came to my mind, even
though the blame largely lies on the original. Can't we get rid of
the above pragraph altogether, and "See new one" at the end where
you replaced "See git-merge" reference below?
> +When a merge conflict happens:
>
> 1. The current branch and `HEAD` pointer stay at the last commit
> successfully made.
> @@ -36,9 +39,6 @@ happens:
> conflict markers `<<<<<<<` and `>>>>>>>`.
> 5. No other modifications are made.
>
> -See linkgit:git-merge[1] for some hints on resolving such
> -conflicts.
> -
> OPTIONS
> -------
> <commit>...::
> @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^ <4>
> SEE ALSO
> --------
> linkgit:git-revert[1]
> +linkgit:gitmergeconflicts[7]
>
> GIT
> ---There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): On Fri, Oct 9, 2026, at 2:26 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email protected]> writes:
>
>> -When it is not obvious how to apply a change, the following
>> -happens:
>> +When it is not obvious how to apply a change, there may
>> +be a merge conflict. See linkgit:gitmergeconflicts[7]
>> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.
>
> "Obvious to whom" was the first thing that came to my mind, even
> though the blame largely lies on the original. Can't we get rid of
> the above pragraph altogether, and "See new one" at the end where
> you replaced "See git-merge" reference below?
Sounds good to me. Same for the language around revert.
>> +When a merge conflict happens:
>>
>> 1. The current branch and `HEAD` pointer stay at the last commit
>> successfully made.
>> @@ -36,9 +39,6 @@ happens:
>> conflict markers `<<<<<<<` and `>>>>>>>`.
>> 5. No other modifications are made.
>>
>> -See linkgit:git-merge[1] for some hints on resolving such
>> -conflicts.
>> -
>> OPTIONS
>> -------
>> <commit>...::
>> @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^ <4>
>> SEE ALSO
>> --------
>> linkgit:git-revert[1]
>> +linkgit:gitmergeconflicts[7]
>>
>> GIT
>> ---There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Mon, Oct 12, 2026 at 02:53:14PM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <[email protected]>
>
> Remove the discussion of merge conflicts and replace it with a link to
> the guide.
Nit: you don't really change the discussion anymore, so this commit
message is inaccurate by now.
Patrick |
||
| working tree to be clean (no modifications from the HEAD commit). | ||
|
|
||
| When a merge conflict happens: | ||
|
|
||
| 1. The current branch and `HEAD` pointer stay at the last commit | ||
| successfully made. | ||
|
|
@@ -36,8 +35,8 @@ happens: | |
| conflict markers `<<<<<<<` and `>>>>>>>`. | ||
| 5. No other modifications are made. | ||
|
|
||
| See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`) | ||
| for a guide to handling merge conflicts. | ||
|
|
||
| OPTIONS | ||
| ------- | ||
|
|
@@ -259,6 +258,7 @@ $ git cherry-pick -Xpatience topic^ <4> | |
| SEE ALSO | ||
| -------- | ||
| linkgit:git-revert[1] | ||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation, | |
| A merge stops if there's a conflict that cannot be resolved | ||
|
There was a problem hiding this comment. "D. Ben Knoble" wrote on the Git mailing list (how to reply to this email): Hi Julia,
On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> All of the info about merge conflicts has been moved to the new guide
> Among the changes made to the common ancestor's version,
> -non-overlapping ones (that is, you changed an area of the file while the
> -other side left that area intact, or vice versa) are incorporated in the
> -final result verbatim. When both sides made changes to the same area,
> -however, Git cannot randomly pick one side over the other, and asks you to
> -resolve it by leaving what both sides did to that area.
> - * Look at the diffs from each branch. `git log --merge -p <path>`
> - will show diffs first for the `HEAD` version and then the
> - `MERGE_HEAD` version.
I think these are both valuable pieces of information we have lost in
the new guide (unless I misremember just having read patch 1 :).
The first explains a bit more about what a conflict *is*. Maybe that's
old-hat nowadays, but I think it could be nice to keep a statement
about why conflicts exist.
The second is a very useful way to get more context to help resolve
conflicts! I have an alias "conflict = log --oneline --graph
--left-right --boundary --merge" for a similar purpose, and I think
the new guide should help folks discover --merge. Often I can get a
better sense of how to resolve conflicts by comparing the original
changes on each side, or I might at least know who to ask about what
to do.
--
D. Ben KnobleThere was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
> Hi Julia,
>
> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
> <[email protected]> wrote:
>>
>> From: Julia Evans <[email protected]>
>>
>> All of the info about merge conflicts has been moved to the new guide
>
>> Among the changes made to the common ancestor's version,
>> -non-overlapping ones (that is, you changed an area of the file while the
>> -other side left that area intact, or vice versa) are incorporated in the
>> -final result verbatim. When both sides made changes to the same area,
>> -however, Git cannot randomly pick one side over the other, and asks you to
>> -resolve it by leaving what both sides did to that area.
>
>> - * Look at the diffs from each branch. `git log --merge -p <path>`
>> - will show diffs first for the `HEAD` version and then the
>> - `MERGE_HEAD` version.
>
> I think these are both valuable pieces of information we have lost in
> the new guide (unless I misremember just having read patch 1 :).
>
> The first explains a bit more about what a conflict *is*. Maybe that's
> old-hat nowadays, but I think it could be nice to keep a statement
> about why conflicts exist.
Will think about this!
> The second is a very useful way to get more context to help resolve
> conflicts! I have an alias "conflict = log --oneline --graph
> --left-right --boundary --merge" for a similar purpose, and I think
> the new guide should help folks discover --merge. Often I can get a
> better sense of how to resolve conflicts by comparing the original
> changes on each side, or I might at least know who to ask about what
> to do.
Thanks, I meant to flag this: the reason I deleted it was really
just that I couldn't understand what `git log --merge -p <path>` did
from the documentation and so I removed it until I could figure it out.
I thought that `--merge` meant that it had something to do with merge
commits, but upon further investigation it looks like that's not true, and
that `--merges` is related to merge commits, `--merge` is something
totally different which is relevant any time there's a conflict
My best guess now is that it would make sense to include this
under "Tools to get more context". Maybe something like this:
> `git log --merge -p <filename>` will print out all commits which
> caused the merge conflict for `<filename>`, and the diff
> of how they changed the file.
("which caused the merge conflict for" is a little more vague, but
I'm trying to convey the intent, and hopefully folks can look at
`man git log` if they want to know the specifics)
This does sound really useful.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
> Thanks, I meant to flag this: the reason I deleted it was really
> just that I couldn't understand what `git log --merge -p <path>` did
> from the documentation and so I removed it until I could figure it out.
It looks at the index to figure out which paths we got conflicts on,
and then does "git log -p <those> <conflicted> <paths>". You can
give a pathspec from the command line to further limit the output.
>> `git log --merge -p <filename>` will print out all commits which
>> caused the merge conflict for `<filename>`, and the diff
>> of how they changed the file.
If you _know_ which exact single file you are interested in, there
is not much you gain from the "--merge" option. "--left-right"
option may be a lot more useful there. It let's you see which side
of the merge gave you what changes.There was a problem hiding this comment. Ben Knoble wrote on the Git mailing list (how to reply to this email): > Le 25 sept. 2026 à 14:19, Junio C Hamano <[email protected]> a écrit :
>
> "Julia Evans" <[email protected]> writes:
>
>> Thanks, I meant to flag this: the reason I deleted it was really
>> just that I couldn't understand what `git log --merge -p <path>` did
>> from the documentation and so I removed it until I could figure it out.
>
> It looks at the index to figure out which paths we got conflicts on,
> and then does "git log -p <those> <conflicted> <paths>". You can
> give a pathspec from the command line to further limit the output.
This explanation omits the manual’s “HEAD…<other>” argument
that the merge option implies, which is important for
understanding the option and my alias ;)There was a problem hiding this comment. Ben Knoble wrote on the Git mailing list (how to reply to this email): > Le 25 sept. 2026 à 12:59, Julia Evans <[email protected]> a écrit :
>
>
>
>> On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
>> Hi Julia,
[snip]
>> The second is a very useful way to get more context to help resolve
>> conflicts! I have an alias "conflict = log --oneline --graph
>> --left-right --boundary --merge" for a similar purpose, and I think
>> the new guide should help folks discover --merge. Often I can get a
>> better sense of how to resolve conflicts by comparing the original
>> changes on each side, or I might at least know who to ask about what
>> to do.
>
> Thanks, I meant to flag this: the reason I deleted it was really
> just that I couldn't understand what `git log --merge -p <path>` did
> from the documentation and so I removed it until I could figure it out.
> I thought that `--merge` meant that it had something to do with merge
> commits, but upon further investigation it looks like that's not true, and
> that `--merges` is related to merge commits, `--merge` is something
> totally different which is relevant any time there's a conflict
>
> My best guess now is that it would make sense to include this
> under "Tools to get more context". Maybe something like this:
>
>> `git log --merge -p <filename>` will print out all commits which
>> caused the merge conflict for `<filename>`, and the diff
>> of how they changed the file.
>
> ("which caused the merge conflict for" is a little more vague, but
> I'm trying to convey the intent, and hopefully folks can look at
> `man git log` if they want to know the specifics)
>
> This does sound really useful.
That reads well enough for me! Thanks. There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
> Like I mentioned before elsewhere it takes a super light approach to
> introducing the 3-way merge. (there is intentionally no mention
> of "since they diverged from the common ancestor" etc)
>
> WHAT IS A MERGE CONFLICT?
> -------------------------
>
> When Git merges two commits together, it looks at the changes that
> each side has made and combines those changes. For example, if one side
> edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
> `hello.py`, then it can easily combine them.
Some immediate reactions.
- Is it obvious that the reason why it can "easily combine" them,
or would it help to be more explicit (i.e., "as there is no
overlap")?
- The second "of `hello.py`" forced me to go back and look at the
first one again to make sure we are talking about the same file.
I would imagine if the latter were "lines 20-25 of the same file",
it would have read better at least to me.
> But if both sides edited overlapping lines of the same file (for example
> one side edited lines 1-5 and the other edited lines 3-6), Git will
> not try to guess how to combine those changes. This is called a "merge
> conflict".
- "cannot guess" would be more direct than "will not try to guess".
> When this happens, Git shows you both sides' edits and asks you to pick
> how to resolve them. It:
>
> * Stages all of the files which were successfully merged
- "merged without conflicts" would be more direct than "successfully merged".
> * For the files with conflicts, it leaves them unstaged, puts both
> sides' edits in the file, and leaves <<markers, merge conflict markers>>
> that you need to resolve.
- "unstaged" sounds as if somebody ran "git rm --cached" on the
paths, but that is not what you want to tell your readers.
- "it leaves them unstaged" -> "it remembers them as conflicted",
perhaps? This hints that Git has a mechanism to remember the
conflicted paths even after you removed the conflict markers from
the file to your readers.
There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): >> WHAT IS A MERGE CONFLICT?
>> -------------------------
>>
>> When Git merges two commits together, it looks at the changes that
>> each side has made and combines those changes. For example, if one side
>> edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>> `hello.py`, then it can easily combine them.
>
> Some immediate reactions.
Thanks, incorporated a few of these ("it marks them as conflicted",
"since there's no overlap", "the same file")
>> But if both sides edited overlapping lines of the same file (for example
>> one side edited lines 1-5 and the other edited lines 3-6), Git will
>> not try to guess how to combine those changes. This is called a "merge
>> conflict".
>
> - "cannot guess" would be more direct than "will not try to guess".
The way I think about it as a user is that Git takes an intentionally conservative
approach and I appreciate the conservatism. Compared to a more aggressive
syntax-aware merge system like `mergiraf` which has done merges I don't
agree with.There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans" <[email protected]> writes:
>> - "cannot guess" would be more direct than "will not try to guess".
>
> The way I think about it as a user is that Git takes an intentionally conservative
> approach and I appreciate the conservatism. Compared to a more aggressive
> syntax-aware merge system like `mergiraf` which has done merges I don't
> agree with.
Your disagreement with their result suggests that they guessed when
they could not do so reliably. I agree that our approach is more
conservative, but we can call it being more honest.
;-).There was a problem hiding this comment. "D. Ben Knoble" wrote on the Git mailing list (how to reply to this email): On Fri, Oct 2, 2026 at 1:01 PM Julia Evans <[email protected]> wrote:
>
>
>
> On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote:
> > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
> >> Hi Julia,
> >>
> >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
> >> <[email protected]> wrote:
> >>>
> >>> From: Julia Evans <[email protected]>
> >>>
> >>> All of the info about merge conflicts has been moved to the new guide
> >>
> >>> Among the changes made to the common ancestor's version,
> >>> -non-overlapping ones (that is, you changed an area of the file while the
> >>> -other side left that area intact, or vice versa) are incorporated in the
> >>> -final result verbatim. When both sides made changes to the same area,
> >>> -however, Git cannot randomly pick one side over the other, and asks you to
> >>> -resolve it by leaving what both sides did to that area.
>
> >> I think these are both valuable pieces of information we have lost in
> >> the new guide (unless I misremember just having read patch 1 :).
> >>
> >> The first explains a bit more about what a conflict *is*. Maybe that's
> >> old-hat nowadays, but I think it could be nice to keep a statement
> >> about why conflicts exist.
> >
> > Will think about this!
>
> After talking this through with my collaborator Marie, we wrote a new
> "what is a merge conflict?" section which I'll include in the v2.
>
> Like I mentioned before elsewhere it takes a super light approach to
> introducing the 3-way merge. (there is intentionally no mention
> of "since they diverged from the common ancestor" etc)
>
> WHAT IS A MERGE CONFLICT?
> -------------------------
>
> When Git merges two commits together, it looks at the changes that
> each side has made and combines those changes. For example, if one side
> edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
> `hello.py`, then it can easily combine them.
>
> But if both sides edited overlapping lines of the same file (for example
> one side edited lines 1-5 and the other edited lines 3-6), Git will
> not try to guess how to combine those changes. This is called a "merge
> conflict".
>
> When this happens, Git shows you both sides' edits and asks you to pick
> how to resolve them. It:
>
> * Stages all of the files which were successfully merged
> * For the files with conflicts, it leaves them unstaged, puts both
> sides' edits in the file, and leaves <<markers, merge conflict markers>>
> that you need to resolve.
>
I quite like this. I'm sure it oversimplifies somewhere, but at least
I personally cannot immediately see where (or how it does any harm to)
;)
Thanks!
PS Unlike Junio---perhaps due to my lack of older Git history and
terminology, despite using Git since 2016?---I would never have read
"unstaged" as *deleted* from the index. Just changed and not updated
in the index (i.e., not "git add"-ed).
--
D. Ben KnobleThere was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "D. Ben Knoble" <[email protected]> writes:
> PS Unlike Junio---perhaps due to my lack of older Git history and
> terminology, despite using Git since 2016?---I would never have read
> "unstaged" as *deleted* from the index. Just changed and not updated
> in the index (i.e., not "git add"-ed).
I agree such an interpretation is certainly possible.
The verb "to unstage" would be the opposite of "to stage", but it is
ambiguous what kind of oppositeness you want to express. This is
unlike "to stage" whose possible interpretation is fairly narrow.
You register the contents that you consider desirable for the path
using various means. On the other hand, "to unstage" is undoing the
result of your earlier act "to stage", but it may mean reverting to
what is recorded in HEAD (i.e., "git reset HEAD -- path"), undoing
the fact that you added a path to the index (i.e., "git rm --cached
-- path"). Neither interpretation is what you want when talking
about what a conflicted merge does to remember the three stages for
a conflicted path in the index.
Hence my suggestion to avoid using the verb.
There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Thu, Sep 24, 2026 at 02:44:17PM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <[email protected]>
>
> All of the info about merge conflicts has been moved to the new guide
Pedantic nit: missing punctuation.
Other than that I agree with Ben, one part that we lose here is some
context on what a merge conflict even is.
PatrickThere was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> All of the info about merge conflicts has been moved to the new guide
In the body text end the sentence with a full stop.
And I just went though the "new guide" with fine toothed comb, I am
very much qualified to judge if the above claim is correct. Let's
see.
> @@ -231,127 +232,6 @@ git merge v1.2.3^0
> git merge --ff-only v1.2.3
> ----
>
> -HOW CONFLICTS ARE PRESENTED
> ----------------------------
> -
> -During a merge, the working tree files are updated to reflect the result
> -of the merge. Among the changes made to the common ancestor's version,
> -non-overlapping ones (that is, you changed an area of the file while the
> -other side left that area intact, or vice versa) are incorporated in the
> -final result verbatim. When both sides made changes to the same area,
> -however, Git cannot randomly pick one side over the other, and asks you to
> -resolve it by leaving what both sides did to that area.
OK. We said working tree files are updated. We made a weak
reference to "common ancestor" but with my suggested updates I think
we sufficiently cover this. "Git cannot ... and asks you ..." had a
nice nuance that we may not have captured in the new document (we
stop at "will not try to guess" and say "asks you to pick" in a
seaprate paragraph, which feels a bit detached than the original
here [***]).
> -By default, Git uses the same style as the one used by the "merge" program
> -from the RCS suite to present such a conflicted hunk, like this:
> -
> -------------
> -Here are lines that are either unchanged from the common
> -ancestor, or cleanly resolved because only one side changed,
> -or cleanly resolved because both sides changed the same way.
> -<<<<<<< yours:sample.txt
> -Conflict resolution is hard;
> -let's go shopping.
> -=======
> -Git makes conflict resolution easy.
> ->>>>>>> theirs:sample.txt
> -And here is another line that is cleanly resolved or unmodified.
> -------------
> -
> -The area where a pair of conflicting changes happened is marked with markers
> -+<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======`
> -is typically your side, and the part afterwards is typically their side.
> -
> -The default format does not show what the original said in the conflicting
> -area. You cannot tell how many lines are deleted and replaced with
> -Barbie's remark on your side. The only thing you can tell is that your
> -side wants to say it is hard and you'd prefer to go shopping, while the
> -other side wants to claim it is easy.
We covered all of the above, except for the reference to RCS which
we explicitly wanted to lose. Good.
> -An alternative style can be used by setting the `merge.conflictStyle`
> ...
> -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
> -another +|||||||+ marker that is followed by the original text.
This is what we were missing in the new guide, which I tried to
rectify without looking at this exact text. In any shape it should
be preserved somehow [***].
> - You can
> -tell that the original just stated a fact, and your side simply gave in to
> -that statement and gave up, while the other side tried to have a more
> -positive attitude. You can sometimes come up with a better resolution by
> -viewing the original.
We covered this with "fruits from both sides" example, and I think
the explanation there is shorter and simpler to understand.
> -HOW TO RESOLVE CONFLICTS
> -------------------------
> -
> -After seeing a conflict, you can do two things:
> -
> - * Decide not to merge. The only clean-ups you need are to reset
> - the index file to the `HEAD` commit to reverse 2. and to clean
> - up working tree changes made by 2. and 3.; `git merge --abort`
> - can be used for this.
> -
> - * Resolve the conflicts. Git will mark the conflicts in
> - the working tree. Edit the files into shape and
> - `git add` them to the index. Use `git commit` or
> - `git merge --continue` to seal the deal. The latter command
> - checks whether there is a (interrupted) merge in progress
> - before calling `git commit`.
The new text tried to have a wiggle room with "most common", but
nothing is lost from the above if we tweak it with my suggested
"there are only two" [***].
> -You can work through the conflict with a number of tools:
> -
> - * Use a mergetool. `git mergetool` to launch a graphical
> - mergetool which will work through the merge with you.
> -
> - * Look at the diffs. `git diff` will show a three-way diff,
> - highlighting changes from both the `HEAD` and `MERGE_HEAD`
> - versions. `git diff AUTO_MERGE` will show what changes you've
> - made so far to resolve textual conflicts.
> -
> - * Look at the diffs from each branch. `git log --merge -p <path>`
> - will show diffs first for the `HEAD` version and then the
> - `MERGE_HEAD` version.
> -
> - * Look at the originals. `git show :1:filename` shows the
> - common ancestor, `git show :2:filename` shows the `HEAD`
> - version, and `git show :3:filename` shows the `MERGE_HEAD`
> - version.
We covered this in "Tools for handling" section. This version
groups AUTO_MERGE together with other tools, which may have its
advantages and disadvantages. The latter two bullet points in the
above list is about static view, so is three-way O A B diff. Use of
mergetool and 'diff AUTO_MERGE" are more dynamic "how far have you
come" view. So separating the "git diff" that shows three-way
comparison and "git diff AUTO_MERGE" in the new document sounds like
an improvement (even though 'mergetool' blurs the boundary between
"how the conflict looked like" and "what your eventual conflict you
are working toward may look like", though [***]).
Overall, I fully agree with these removals. We may want to take a
few points (marked with [***]) we learned during this review back to
the new document from here, though.
Thanks. |
||
| automatically or if `--no-commit` was provided when initiating the | ||
| merge. At that point you can run `git merge --abort` or `git merge | ||
| --continue`. See linkgit:gitmergeconflicts[7] | ||
| (or `git help mergeconflicts`) for a guide to handling merge conflicts. | ||
|
|
||
| `git merge --abort` will abort the merge process and try to reconstruct | ||
| the pre-merge state. However, if there were uncommitted changes when the | ||
|
|
@@ -231,127 +232,6 @@ git merge v1.2.3^0 | |
| git merge --ff-only v1.2.3 | ||
| ---- | ||
|
|
||
| EXAMPLES | ||
| -------- | ||
|
|
||
|
|
@@ -406,6 +286,7 @@ linkgit:git-reset[1], | |
| linkgit:git-diff[1], linkgit:git-ls-files[1], | ||
| linkgit:git-add[1], linkgit:git-rm[1], | ||
| linkgit:git-mergetool[1] | ||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour. | |
|
|
||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-pull.adoc | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
> index 88f4fd3926..73f6d460bb 100644
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.
>
> If there's a merge conflict during the merge or rebase that you don't
> want to handle, you can safely abort it with `git merge --abort` or
> -`git rebase --abort`.
> +`git rebase --abort`. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.
>
> OPTIONS
> -------
Very good. |
||
| If there's a merge conflict during the merge or rebase that you don't | ||
| want to handle, you can safely abort it with `git merge --abort` or | ||
| `git rebase --abort`. See linkgit:gitmergeconflicts[7] | ||
| (or `git help mergeconflicts`) for a guide to handling merge conflicts. | ||
|
|
||
| OPTIONS | ||
| ------- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the | |
| first problematic commit and leave conflict markers. If this happens, you can do | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Remove some of the detail about how to handle a merge conflict, since
> it's explained in detail in the new guide, and there probably isn't
> enough detail anyway.
>
> Leave the steps since rebase is special and has a `--skip` option which
> the other commands which cause merge conflicts don't have.
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-rebase.adoc | 13 +++++++++----
> 1 file changed, 9 insertions(+), 4 deletions(-)
Great. There is nothing I would miss from these removed lines. All
are already described better in the new document, with or without
suggestions I made during reviews of [1/6] and [2/6].
|
||
| one of these things: | ||
|
|
||
| 1. Resolve the conflict. After resolving all of the conflicts, | ||
| you can continue the rebasing process with | ||
|
|
||
| git rebase --continue | ||
|
|
@@ -62,6 +59,9 @@ one of these things: | |
|
|
||
| git rebase --skip | ||
|
|
||
| See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`) | ||
| for a full guide to handling merge conflicts. | ||
|
|
||
| If you don't specify an `<upstream>` to rebase onto, the upstream configured in | ||
| `branch.<name>.remote` and `branch.<name>.merge` options will be used (see | ||
| linkgit:git-config[1] for details) and the `--fork-point` option is | ||
|
|
@@ -1284,6 +1284,11 @@ include::includes/cmd-config-section-all.adoc[] | |
| include::config/rebase.adoc[] | ||
| include::config/sequencer.adoc[] | ||
|
|
||
| SEE ALSO | ||
| -------- | ||
|
|
||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
| Part of the linkgit:git[1] suite | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory. | |
| See "Reset, restore and revert" in linkgit:git[1] for the differences | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-revert.adoc | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc
> index ffba365e63..1edf98b9aa 100644
> --- a/Documentation/git-revert.adoc
> +++ b/Documentation/git-revert.adoc
> @@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.
> See "Reset, restore and revert" in linkgit:git[1] for the differences
> between the three commands.
>
> +If there have been new commits since the reverted commit, there may
> +be a merge conflict. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.
> +
This is a strange thing to say. Is it worth special casing the
revert of the tip commit that much? "Reverting a commit may resolt
in a merge conflict" should be sufficient, I would think.
> OPTIONS
> -------
> <commit>...::
> @@ -162,6 +166,7 @@ include::config/revert.adoc[]
> SEE ALSO
> --------
> linkgit:git-cherry-pick[1]
> +linkgit:gitmergeconflicts[7]
>
> GIT
> --- |
||
| between the three commands. | ||
|
|
||
| Reverting a commit may result in a merge conflict. | ||
| See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`) | ||
| for a guide to handling merge conflicts. | ||
|
|
||
| OPTIONS | ||
| ------- | ||
| <commit>...:: | ||
|
|
@@ -162,6 +166,7 @@ include::config/revert.adoc[] | |
| SEE ALSO | ||
| -------- | ||
| linkgit:git-cherry-pick[1] | ||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Junio C Hamano wrote on the Git mailing list (how to reply to this email):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Julia Evans" wrote on the Git mailing list (how to reply to this email):