Re: git-merge: inconsistent manual page.

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 30, 2007, 18:39 UTC
Message-ID: <7vsl3sla5q.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <fg7b6o$k1f$1@ger.gmane.org>

Sergei Organov <osv@javad.com> writes:

Show 5 quoted lines

> git-merge has inconsistent manual page:
>
> 1. In the SYNOPSIS, there is [-m <msg>], but OPTIONS section lacks it.
>    The latter has just  description of <msg>, suggesting it could be
>    used without -m, but SYNOPSIS doesn't reflect this.

This is not quite right, I am afraid. "git merge" used to take its parameters in quite an exotic order, and we still do support it as we do not break people's existing setups:

	git-merge "$message" HEAD $list_of_merged_refs

where the second parameter is always HEAD. This is the only form that accepts the message without -m (see ll.230- in the git-merge script).

But we do not _want_ to advertise this funny syntax. Humans and newly written scripts should express the above as:

	git merge -m "$message" $list_of_merged_refs

>    BTW, git-merge options are described in
>    Documentation/merge-options.txt that is also used fot git-pull
>    options, and it's not clear for me if git-pull supports [-m
>    <msg>]. Does it?

It shouldn't; the merge message is prepared by git-pull to describe what got merged from where for you (see the last few lines in the git-pull script).

> 2. In the SYNOPSIS, there is no <head> that is described in the
>    OPTIONS.

See above.  We do not want to advertise the crazy syntax.