Re: [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull"

[Jonathan Nieder <jrnieder@gmail.com>]

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