From: Jonathan Nieder <jrnieder@gmail•com>
To: Thomas Rast <trast@student•ethz.ch>
Cc: git@vger•kernel.org, Junio C Hamano <gitster@pobox•com>
Subject: Re: [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull"
Date: Sat, 9 Jan 2010 22:13:57 -0600 [thread overview]
Message-ID: <20100110041357.GF1083@progeny.tock> (raw)
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.
> 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
next prev parent reply other threads:[~2010-01-10 4:13 UTC|newest]
Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-01-07 17:03 [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull" Thomas Rast
2010-01-07 17:03 ` [PATCH 2/2] Documentation: warn prominently against merging with dirty trees Thomas Rast
2010-01-07 17:03 ` [NON-PATCH 3/2] Documentation/git-merge: format full commands in typewriter font Thomas Rast
2010-01-07 20:25 ` Jonathan Nieder
2010-01-07 21:08 ` Junio C Hamano
2010-01-07 18:01 ` [PATCH 1/2] Documentation/git-merge: reword references to "remote" and "pull" Junio C Hamano
2010-01-10 0:02 ` [PATCH v2 0/4] Documentation style fixes Thomas Rast
2010-01-10 0:02 ` [PATCH v2 1/4] Documentation/git-merge: reword references to "remote" and "pull" Thomas Rast
2010-01-10 4:13 ` Jonathan Nieder [this message]
2010-01-10 12:24 ` Thomas Rast
2010-01-23 22:48 ` [PATCH] Documentation: merge: use MERGE_HEAD to refer to the remote branch Jonathan Nieder
2010-01-10 0:02 ` [PATCH v2 2/4] Documentation: warn prominently against merging with dirty trees Thomas Rast
2010-01-10 4:49 ` Jonathan Nieder
2010-01-10 6:31 ` Junio C Hamano
2010-01-10 12:16 ` Thomas Rast
2010-01-11 2:13 ` Jonathan Nieder
2010-01-11 2:30 ` Junio C Hamano
2010-01-11 4:13 ` Jonathan Nieder
2010-01-11 8:21 ` [PATCH 0/6] " Jonathan Nieder
2010-01-11 8:27 ` [PATCH/RFC 1/6] Documentation: clarify one-line description for merge Jonathan Nieder
2010-01-11 8:30 ` [PATCH 2/6] Documentation: merge: add an overview Jonathan Nieder
2010-01-11 10:09 ` Junio C Hamano
2010-01-11 8:37 ` [PATCH 4/6] Documentation: emphasize when git merge terminates early Jonathan Nieder
2010-01-11 23:11 ` Thomas Rast
2010-01-11 8:39 ` [PATCH 5/6] Documentation: merge: add a section about fast-forward Jonathan Nieder
2010-01-11 8:43 ` [PATCH 6/6] Documentation: tweak How Merge Works Jonathan Nieder
2010-01-11 23:11 ` Thomas Rast
2010-01-13 10:44 ` [PATCH 0/6] Re: Documentation: warn prominently against merging with dirty trees Petr Baudis
2010-01-13 6:55 ` [PATCH v2 2/4] " Junio C Hamano
2010-01-10 0:02 ` [PATCH v2 3/4] Documentation: format full commands in typewriter font Thomas Rast
2010-01-10 3:31 ` Jonathan Nieder
2010-01-10 0:07 ` [PATCH v2 0/4] Documentation style fixes Thomas Rast
2010-01-10 0:19 ` Thomas Rast
2010-01-10 6:34 ` Junio C Hamano
2010-01-10 12:10 ` Thomas Rast
2010-01-10 12:10 ` [PATCH 1/2] More missed dashed 'git-cmd' forms Thomas Rast
2010-01-10 12:10 ` [PATCH 2/2] More missed `code snippets` Thomas Rast
2010-01-10 12:11 ` [PATCH] Documentation: show-files is now called git-ls-files Thomas Rast
2010-01-18 1:18 ` [PATCH v2 0/4] Documentation style fixes Junio C Hamano
2010-01-19 17:29 ` Thomas Rast
2010-01-19 17:39 ` Jonathan Nieder
2010-01-10 7:12 ` Junio C Hamano
[not found] ` <9516c897017ec420403bb7f687fb8962de42cb7c.1263081032.git.trast@student.ethz.ch>
2010-01-10 2:56 ` [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout Jonathan Nieder
2010-01-10 2:59 ` [PATCH 1/2] Documentation: git gc packs refs by default now Jonathan Nieder
2010-01-10 3:01 ` [PATCH 2/2] Documentation: tiny git config manual tweaks Jonathan Nieder
2010-01-10 12:21 ` [PATCH v2 4/4] Documentation: spell 'git cmd' without dash throughout Thomas Rast
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20100110041357.GF1083@progeny.tock \
--to=jrnieder@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=trast@student$(echo .)ethz.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox