Conversation
|
There is an issue in commit 7dee697:
|
|
There is an issue in commit 3a9e01d:
|
|
There is an issue in commit c96ce90:
|
|
There are issues in commit a340474:
|
|
There is an issue in commit 67302e7:
|
|
There are issues in commit 241bf3e:
|
9058e0a to
420858b
Compare
|
The (edit: I think it's in |
Yep: see e.g. https://github.com/git/git/blob/v2.55.0/.gitattributes#L16 |
Introduce a new page, `gitmergeconflicts`, that explains the process of
handling a merge conflict in a way that addresses the following issues,
which came from feedback from Git users on the current explanation of
merge conflicts in the `git merge` man page:
- The process for resolving a merge conflict is only explained in the
`git merge` man page, even though there are several other commands
which can result in conflicts
- Sometimes we use "ours" and "theirs" to refer to the two sides of
the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should
be consistent. Also the terms "ours" and "theirs" are not explained.
Similarly, it says "The part before the `=======` is typically your
side...", but doesn't explain what "typically" means.
- It introduces the merge format using an analogy to RCS, which very few
Git users have ever used
- In "The only clean-ups you need are to reset the index file to the
`HEAD` commit to reverse 2. and to clean up working tree changes made
by 2. and 3.", it's not clear to users what "2" and "3" are supposed
to mean
- It uses a cultural reference ("Conflict resolution is hard; let's go
shopping.") which is confusing or unfamiliar to some people. I think it
would be clearer for users to use a code example instead.
- It doesn't explain the difference between diff3 and zdiff3
- It sometimes uses the term "area" and sometimes uses the term "hunk"
Also document the unified `--abort`, `--continue` workflow in one
place, since it's a really nice example of a place Git has a consistent
interface between similar commands.
Co-Authored-By: Marie Claire LeBlanc Flanagan
Signed-off-by: Julia Evans <julia@jvns.ca>
All of the info about merge conflicts has been moved to the new guide Signed-off-by: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
Signed-off-by: Julia Evans <julia@jvns.ca>
Remove the discussion of merge conflicts and replace it with a link to the guide. Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Julia Evans <julia@jvns.ca>
Signed-off-by: Julia Evans <julia@jvns.ca>
31c5eec to
96ec49e
Compare
|
Not sure what's going on with the debian-12 test failure but I'm planning to ignore it for now. |
|
thanks, appreciate your work on testing! |
|
/preview |
|
Preview email sent as pull.2237.git.1790185498.gitgitgadget@gmail.com |
2 participants
This patch series introduces a new manual page,
gitmergeconflicts, which explains the process of explaining a merge conflict with examples. It also links to that new page from the commands which can cause merge conflicts, instead of trying to reexplain the process every time.As usual the process I used to write this was to collect comments from Git users on the existing documentation, and then address those issues. Those issues I'm aiming to solve in the first commit message.
Some things I'm still considering:
git commitdoes the same thing asgit merge --continueduring agit merge, but I'm not sure if that's always true.git merge,git revert,git rebase,git cherry-pick, andgit pullas commands that can cause merge conflicts. I believe thatgit applyandgit amcan also result in conflicts when applying a patch, though it's a bit complicated because applying a patch is a different operation than doing a 3-way merge and the tools available for dealing with it are a different. My thought right now is to avoid the issue of applying patches for now (because it's a whole can of worms) and instead just try to not imply that this is necessarily an exhaustive list. Also if/when thegit rebase --squashchanges land, then we'd need to addgit historyto this list.git rebase,git merge, etc. Merge conflict resolution is complex and it's very useful to be able to include examples: this version ended up at ~300 lines and I think that's too big of an include, especially for short man pages likecherry-pick_HEADreferences. It's hard for me to know exactly where they belong because I personally have never usedMERGE_HEAD,REBASE_HEAD,ORIG_HEAD,CHERRY_PICK_HEADetc, and I don't know how they're meant to be used. From some quick unscientific polling (at https://social.jvns.ca/@b0rk/117320011885941855), it seems like most Git users have never used them either (and folks who do use a*_HEADreference mainly seem to useFETCH_HEADwhich isn't relevant here), so from that perspective it seems important to avoid emphasizing them too much. Thegit revertman page doesn't mentionREVERT_HEADandgit rebaseonly mentionsREBASE_HEADin passing. Of course they're all explained in gitrevisions(7) which might be the best place for them.SYNOPSISsection is for in a "guide" man page which is not about a specific Git command (what is the user intended to use it for?). I tried to leave it out but the CI said it was required.Thanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih, and about 10 others who gave feedback on both the original
git mergeman page, as well as the proposed improvements.CC: ps@pks.im