git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Jonathan Nieder <jrnieder@gmail.com>
Date
Jan 10, 2010, 04:13 UTC
Message-ID
<20100110041357.GF1083@progeny.tock>
In-Reply-To
<57bddb115331a23816af772172531fb56fceace4.1263081032.git.trast@student.ethz.ch>
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.

Show 19 quoted lines
> 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.

Show 5 quoted lines
> -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.
Show 12 quoted lines
> @@ -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.
Show 8 quoted lines
> @@ -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”?
Show 8 quoted lines
> @@ -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

Previous: Thomas RastNext: Thomas Rast
Message 9 of 46 in “Documentation/git-merge: reword references to "remote" and "pull"”
  1. 1/2 Documentation/git-merge: reword references to "remote" and "pull"Thomas Rast, Jan 7, 2010
  2. 2/2 Documentation: warn prominently against merging with dirty treesThomas Rast, Jan 7, 2010
  3. 3/2 Documentation/git-merge: format full commands in typewriter fontThomas Rast, Jan 7, 2010
  4. Jonathan NiederJan 7, 2010
  5. Junio C HamanoJan 7, 2010
  6. Junio C HamanoJan 7, 2010
  7. 0/4 Documentation style fixesThomas Rast, Jan 10, 2010
  8. 1/4 Documentation/git-merge: reword references to "remote" and "pull"Thomas Rast, Jan 10, 2010
  9. Jonathan NiederJan 10, 2010
  10. Thomas RastJan 10, 2010
  11. Documentation: merge: use MERGE_HEAD to refer to the remote branchJonathan Nieder, Jan 23, 2010
  12. 2/4 Documentation: warn prominently against merging with dirty treesThomas Rast, Jan 10, 2010
  13. Jonathan NiederJan 10, 2010
  14. Junio C HamanoJan 10, 2010
  15. Thomas RastJan 10, 2010
  16. Jonathan NiederJan 11, 2010
  17. Junio C HamanoJan 11, 2010
  18. Jonathan NiederJan 11, 2010
  19. 0/6 Re: Documentation: warn prominently against merging with dirty treesJonathan Nieder, Jan 11, 2010
  20. 1/6 Documentation: clarify one-line description for mergeJonathan Nieder, Jan 11, 2010
  21. 2/6 Documentation: merge: add an overviewJonathan Nieder, Jan 11, 2010
  22. Junio C HamanoJan 11, 2010
  23. 4/6 Documentation: emphasize when git merge terminates earlyJonathan Nieder, Jan 11, 2010
  24. Thomas RastJan 11, 2010
  25. 5/6 Documentation: merge: add a section about fast-forwardJonathan Nieder, Jan 11, 2010
  26. 6/6 Documentation: tweak How Merge WorksJonathan Nieder, Jan 11, 2010
  27. Thomas RastJan 11, 2010
  28. Petr BaudisJan 13, 2010
  29. Junio C HamanoJan 13, 2010
  30. 3/4 Documentation: format full commands in typewriter fontThomas Rast, Jan 10, 2010
  31. Jonathan NiederJan 10, 2010
  32. Thomas RastJan 10, 2010
  33. Thomas RastJan 10, 2010
  34. Junio C HamanoJan 10, 2010
  35. Thomas RastJan 10, 2010
  36. 1/2 More missed dashed 'git-cmd' formsThomas Rast, Jan 10, 2010
  37. 2/2 More missed `code snippets`Thomas Rast, Jan 10, 2010
  38. Documentation: show-files is now called git-ls-filesThomas Rast, Jan 10, 2010
  39. Junio C HamanoJan 18, 2010
  40. Thomas RastJan 19, 2010
  41. Jonathan NiederJan 19, 2010
  42. Junio C HamanoJan 10, 2010
  43. Jonathan NiederJan 10, 2010
  44. 1/2 Documentation: git gc packs refs by default nowJonathan Nieder, Jan 10, 2010
  45. 2/2 Documentation: tiny git config manual tweaksJonathan Nieder, Jan 10, 2010
  46. Thomas RastJan 10, 2010

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.