[PATCH] core-tutorial: git-merge uses -m for commit messages

[PATCH] core-tutorial: git-merge uses -m for commit messages

[Matthias Lederhofer]

Signed-off-by: Matthias Lederhofer <matled@gmx.net>
---
 Documentation/core-tutorial.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index 9c28bea..6f30e0a 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -894,11 +894,11 @@ script called `git merge`, which wants to know which branches you want
 to resolve and what the merge is all about:
 
 ------------
-$ git merge "Merge work in mybranch" HEAD mybranch
+$ git merge -m "Merge work in mybranch" HEAD mybranch
 ------------
 
-where the first argument is going to be used as the commit message if
-the merge can be resolved automatically.
+The `-m` options specifies the commit message to be used for the merge commit
+(in case it is created).
 
 Now, in this case we've intentionally created a situation where the
 merge will need to be fixed up by hand, though, so git will do as much
@@ -981,7 +981,7 @@ resolve to get the "upstream changes" back to your branch.
 
 ------------
 $ git checkout mybranch
-$ git merge "Merge upstream changes." HEAD master
+$ git merge -m "Merge upstream changes." HEAD master
 ------------
 
 This outputs something like this (the actual commit object names
@@ -1623,8 +1623,8 @@ in both of them.  You could merge in 'diff-fix' first and then
 'commit-fix' next, like this:
 
 ------------
-$ git merge 'Merge fix in diff-fix' master diff-fix
-$ git merge 'Merge fix in commit-fix' master commit-fix
+$ git merge -m 'Merge fix in diff-fix' master diff-fix
+$ git merge -m 'Merge fix in commit-fix' master commit-fix
 ------------
 
 Which would result in:
-- 
1.5.0.rc3.544.g79b8

Re: [PATCH] core-tutorial: git-merge uses -m for commit messages

[Junio C Hamano]

Matthias Lederhofer <matled@gmx.net> writes:

> Signed-off-by: Matthias Lederhofer <matled@gmx.net>
> ---
>  Documentation/core-tutorial.txt |   12 ++++++------
>  1 files changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
> index 9c28bea..6f30e0a 100644
> --- a/Documentation/core-tutorial.txt
> +++ b/Documentation/core-tutorial.txt
> @@ -894,11 +894,11 @@ script called `git merge`, which wants to know which branches you want
>  to resolve and what the merge is all about:
>  
>  ------------
> -$ git merge "Merge work in mybranch" HEAD mybranch
> +$ git merge -m "Merge work in mybranch" HEAD mybranch
>  ------------

Unfortunately it needs more than that.

The funny command argument order in the original example was the
command line format that has been in use internally for a long
time:  merge <msg> HEAD <other commit>.

The human-accessible form that uses -m in front of <msg> does
not need the second argument that always must match the current
commit (it always must match so there is no point saying it).

The original examples work perfectly Ok, and you broke it -- if
you are doing '-m' you need to remove HEAD (and master in later
ones) from the command line.

Re: [PATCH] core-tutorial: git-merge uses -m for commit messages

[Matthias Lederhofer]

Junio C Hamano <junkio@cox.net> wrote:
> The original examples work perfectly Ok, [..]
Ah, so the man page is incomplete?  But without HEAD (git merge -m
"message" mybranch) the command is ok?  It seems to work anyway
because merging HEAD just prints "Already up-to-date with <commit>".

Re: [PATCH] core-tutorial: git-merge uses -m for commit messages

[Junio C Hamano]

Matthias Lederhofer <matled@gmx.net> writes:

> Junio C Hamano <junkio@cox.net> wrote:
>> The original examples work perfectly Ok, [..]
> Ah, so the man page is incomplete?

Perhaps, but the older format is not something we would want to
recommend to humans, so...

> But without HEAD (git merge -m
> "message" mybranch) the command is ok?

Yes, but ;-).

Humans are encouraged to say "git merge <that-branch>" and let
fmt-merge-msg to figure out what message to use.

If I were updating the end-user tutorial, I would probably
recommend people to use the newer format that does not force you
to say HEAD.  core-tutorial however is meant to talk about how
Porcelain scripts do things, and in that sense it makes some
sense to demonstrate the use of funny "<msg> HEAD <commit>"
order, only because it is how git-pull invokes "git merge".

> It seems to work anyway
> because merging HEAD just prints "Already up-to-date with <commit>".

Invoking with -m <msg>, like this:

	git merge -m "$msg" HEAD $commit

it would try to make an octopus that has the current HEAD (this
is given always when you are merging), the HEAD you gave from
the command line, and the other $commit.  The octopus merge
strategy is intelligent enough to notice that the second HEAD is
the same as the current HEAD so resulting commit would only have
two parents.  So it may happen to work, but it is never a good
practice.