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.
> 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.
> @@ -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.
> @@ -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”?
> @@ -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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html