* git-merge: inconsistent manual page.
@ 2007-10-30 13:22 Sergei Organov
2007-10-30 18:39 ` Junio C Hamano
0 siblings, 1 reply; 5+ messages in thread
From: Sergei Organov @ 2007-10-30 13:22 UTC (permalink / raw)
To: git
Hello,
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.
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?
2. In the SYNOPSIS, there is no <head> that is described in the
OPTIONS.
Overall, it seems that either SYNOPSIS should be changed (see patch
below), or historical syntax should be wiped from the manual page.
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index bca4212..0ea7aea 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -10,7 +10,7 @@ SYNOPSIS
--------
[verse]
'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
- [-m <msg>] <remote> <remote>...
+ [[-m] <msg>] [<head>] <remote> <remote>...
DESCRIPTION
-----------
--
Sergei.
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: git-merge: inconsistent manual page.
2007-10-30 13:22 git-merge: inconsistent manual page Sergei Organov
@ 2007-10-30 18:39 ` Junio C Hamano
2007-10-30 18:54 ` Junio C Hamano
0 siblings, 1 reply; 5+ messages in thread
From: Junio C Hamano @ 2007-10-30 18:39 UTC (permalink / raw)
To: Sergei Organov; +Cc: git
Sergei Organov <osv@javad.com> writes:
> 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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git-merge: inconsistent manual page.
2007-10-30 18:39 ` Junio C Hamano
@ 2007-10-30 18:54 ` Junio C Hamano
2007-10-30 19:32 ` Sergei Organov
0 siblings, 1 reply; 5+ messages in thread
From: Junio C Hamano @ 2007-10-30 18:54 UTC (permalink / raw)
To: Sergei Organov; +Cc: git
Subject: git-merge: document but discourage the historical syntax
Historically "git merge" took its command line arguments in a
rather strange order. Document the historical syntax, and also
document clearly that it is not encouraged in new scripts.
There is no reason to deprecate the historical syntax, as the
current code can sanely tell which syntax the caller is using,
and existing scripts by people do use the historical syntax.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Junio C Hamano <gitster@pobox.com> writes:
> See above. We do not want to advertise the crazy syntax.
By the way, I kept saying "crazy" above, but the thing is that
when Linus did that "crazy" syntax, it was not crazy at all.
Simply it did not matter, as nobody was supposed to use "git
merge" from the command line.
Instead, when merging a local branch, you would just have said:
$ git pull . $my_other_branch
It became a "crazy historical syntax" only after people started
talking about using it from the command line, giving it other
command line options. And at that point, we introduced -m flag
and stopped requiring the second token 'HEAD'.
With that in mind, this might be a better alternative.
Documentation/git-merge.txt | 6 ++++++
1 files changed, 6 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index bca4212..a056b40 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -11,6 +11,7 @@ SYNOPSIS
[verse]
'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
[-m <msg>] <remote> <remote>...
+'git-merge' <msg> HEAD <remote>...
DESCRIPTION
-----------
@@ -43,6 +44,11 @@ If you tried a merge which resulted in a complex conflicts and
would want to start over, you can recover with
gitlink:git-reset[1].
+The second syntax (<msg> `HEAD` <remote>) is supported for
+historical reasons. Do not use it from the command line or in
+new scripts.
+
+
CONFIGURATION
-------------
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: git-merge: inconsistent manual page.
2007-10-30 18:54 ` Junio C Hamano
@ 2007-10-30 19:32 ` Sergei Organov
2007-10-31 0:05 ` Junio C Hamano
0 siblings, 1 reply; 5+ messages in thread
From: Sergei Organov @ 2007-10-30 19:32 UTC (permalink / raw)
To: git
Junio C Hamano <gitster@pobox.com> writes:
> Subject: git-merge: document but discourage the historical syntax
>
> Historically "git merge" took its command line arguments in a
> rather strange order. Document the historical syntax, and also
> document clearly that it is not encouraged in new scripts.
>
> There is no reason to deprecate the historical syntax, as the
> current code can sanely tell which syntax the caller is using,
> and existing scripts by people do use the historical syntax.
OK, your patch is better than what I've suggested. The only thing that
your patch seems to be missing is prepending -m to <msg>:: in the
OPTIONS section. Yeah, it could be more strict to just describe <msg>,
but if there were no historical syntax, then you'd put '-m <msg>'
description in, right? So the latter might be better anyway.
--
Sergei.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: git-merge: inconsistent manual page.
2007-10-30 19:32 ` Sergei Organov
@ 2007-10-31 0:05 ` Junio C Hamano
0 siblings, 0 replies; 5+ messages in thread
From: Junio C Hamano @ 2007-10-31 0:05 UTC (permalink / raw)
To: Sergei Organov; +Cc: git
Sergei Organov <osv@javad.com> writes:
> Junio C Hamano <gitster@pobox.com> writes:
>> Subject: git-merge: document but discourage the historical syntax
>>
>> Historically "git merge" took its command line arguments in a
>> rather strange order. Document the historical syntax, and also
>> document clearly that it is not encouraged in new scripts.
>>
>> There is no reason to deprecate the historical syntax, as the
>> current code can sanely tell which syntax the caller is using,
>> and existing scripts by people do use the historical syntax.
>
> OK, your patch is better than what I've suggested. The only thing that
> your patch seems to be missing is prepending -m to <msg>:: in the
> OPTIONS section. Yeah, it could be more strict to just describe <msg>,
> ...
Nah, you are absolutely right. We describe "-s <strategy>"
under the headline with the leading "-s".
Will fix.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2007-10-31 0:05 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-10-30 13:22 git-merge: inconsistent manual page Sergei Organov
2007-10-30 18:39 ` Junio C Hamano
2007-10-30 18:54 ` Junio C Hamano
2007-10-30 19:32 ` Sergei Organov
2007-10-31 0:05 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).