Re: [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull"
From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:47:59
Thomas Rast wrote:
The git-merge manpage was written in terms of merging a "remote", which is no longer the case: you merge local or remote-tracking branches; pull is for actual remotes.
Right.
Adjust the manpage accordingly. We refer to the arguments as "commits", and change instances of "remote" to "other" (where branches are concerned) or "theirs" (where conflict sides are concerned).
Makes sense. It might be nice to emphasize the metaphor of merging
another branch’s history into the current branch, but <commit>
really does seem clearer than ‘{ <branch> | <commit> }’ or any other
alternative I can come up with.
quoted hunk ↗ jump to hunk
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e886c2e..4896587 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt@@ -10,17 +10,17 @@ SYNOPSIS -------- [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... - [-m <msg>] <remote>... -'git merge' <msg> HEAD <remote>... + [-m <msg>] <commit>... +'git merge' <msg> HEAD <commit>... DESCRIPTION ----------- -This is the top-level interface to the merge machinery -which drives multiple merge strategy scripts. +Merges the history specified by <commit> into HEAD, optionally using a +specific merge strategy.
Perhaps just | Rejoins two or more diverging branches of development. would be simpler. The ability to choose a merge strategy seems more like a detail for later.
-The second syntax (<msg> `HEAD` <remote>) is supported for +The second syntax (<msg> `HEAD` <commit>...) is supported for historical reasons. Do not use it from the command line or in -new scripts. It is the same as `git merge -m <msg> <remote>`. +new scripts. It is the same as `git merge -m <msg> <commit>...`.
Technically, they are not entirely the same: ‘merge -m <msg>’ will warn that the log message is ignored when the merge results in a fast-forward, whereas ‘merge <msg> HEAD’ will not. See commit 77c29b4a (Revert recent "git merge <msg> HEAD <commit>..." deprecation, 2009-12-08). So should this say | Use `git merge -m <msg> <commit>...` instead. to side-step the issue? Not sure.
quoted hunk ↗ jump to hunk
@@ -33,10 +33,10 @@ include::merge-options.txt[] used to give a good default for automated 'git merge' invocations. -<remote>...:: - Other branch heads to merge into our branch. You need at - least one <remote>. Specifying more than one <remote> - obviously means you are trying an Octopus. +<commit>...:: + Commits, usually other branch heads, to merge into our branch. + You need at least one <commit>. Specifying more than one + <commit> obviously means you are trying an Octopus.
Nice.
quoted hunk ↗ jump to hunk
@@ -96,8 +96,8 @@ file matches exactly the current `HEAD` commit; otherwise we will write out your local changes already registered in your index file along with the merge result, which is not good. Because 1. involves only those paths differing between your -branch and the remote branch you are pulling from during the -merge (which is typically a fraction of the whole tree), you can +branch and the branch you are merging +(which is typically a fraction of the whole tree), you can
Hmm. The old wording distinguishes nicely between the HEAD and MERGE_HEAD that will be parents for the new HEAD. From some points of view, the new wording does not: both are branches you are merging (though only one is an argument to 'git merge'). Sadly, I have not come up with a good expression for “the other commit whose history is to be incorporated into the current branch”. Maybe we should punt and just say “the other branch”?
quoted hunk ↗ jump to hunk
@@ -202,15 +202,15 @@ You can work through the conflict with a number of tools: mergetool which will work you through the merge. * Look at the diffs. 'git diff' will show a three-way diff, - highlighting changes from both the HEAD and remote versions. + highlighting changes from both the HEAD and their versions. * Look at the diffs on their own. 'git log --merge -p <path>'
This is a bit awkward, since 'they' is playing two roles. Also, the context does not make it obvious what 'our' and 'their' versions are. Maybe: | * Look at the diffs. 'git diff' will show a three-way diff, | highlighting changes from both the HEAD and MERGE_HEAD | versions. | | * 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. Thanks for looking into this, Jonathan