{"thread":{"id":"10528","subject":"git-merge: inconsistent manual page.","startedAt":"2007-10-30T13:22:31Z","lastAt":"2007-10-31T00:05:31Z","messageCount":5,"participants":["Sergei Organov","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"57571","messageId":"fg7b6o$k1f$1@ger.gmane.org","threadId":"10528","inReplyTo":null,"subject":"git-merge: inconsistent manual page.","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-10-30T13:22:31Z","receivedAt":"2007-10-30T13:22:31Z","isPatch":false,"sender":{"key":"osv@javad.com","avatar":null},"body":"Hello,\n\ngit-merge has inconsistent manual page:\n\n1. In the SYNOPSIS, there is [-m <msg>], but OPTIONS section lacks it.\n   The latter has just  description of <msg>, suggesting it could be\n   used without -m, but SYNOPSIS doesn't reflect this. \n\n   BTW, git-merge options are described in\n   Documentation/merge-options.txt that is also used fot git-pull\n   options, and it's not clear for me if git-pull supports [-m\n   <msg>]. Does it?\n\n2. In the SYNOPSIS, there is no <head> that is described in the\n   OPTIONS.\n\nOverall, it seems that either SYNOPSIS should be changed (see patch\nbelow), or historical syntax should be wiped from the manual page.\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex bca4212..0ea7aea 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...\n-\t[-m <msg>] <remote> <remote>...\n+\t[[-m] <msg>] [<head>] <remote> <remote>...\n \n DESCRIPTION\n -----------\n\n-- \nSergei.\n"},{"id":"57591","messageId":"7vsl3sla5q.fsf@gitster.siamese.dyndns.org","threadId":"10528","inReplyTo":"fg7b6o$k1f$1@ger.gmane.org","subject":"Re: git-merge: inconsistent manual page.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-10-30T18:39:13Z","receivedAt":"2007-10-30T18:39:13Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergei Organov <osv@javad.com> writes:\n\n> git-merge has inconsistent manual page:\n>\n> 1. In the SYNOPSIS, there is [-m <msg>], but OPTIONS section lacks it.\n>    The latter has just  description of <msg>, suggesting it could be\n>    used without -m, but SYNOPSIS doesn't reflect this. \n\nThis is not quite right, I am afraid.  \"git merge\" used to take\nits parameters in quite an exotic order, and we still do support\nit as we do not break people's existing setups:\n\n\tgit-merge \"$message\" HEAD $list_of_merged_refs\n\nwhere the second parameter is always HEAD.  This is the only\nform that accepts the message without -m (see ll.230- in the\ngit-merge script).\n\nBut we do not _want_ to advertise this funny syntax.  Humans and\nnewly written scripts should express the above as:\n\n\tgit merge -m \"$message\" $list_of_merged_refs\n\n\n>    BTW, git-merge options are described in\n>    Documentation/merge-options.txt that is also used fot git-pull\n>    options, and it's not clear for me if git-pull supports [-m\n>    <msg>]. Does it?\n\nIt shouldn't; the merge message is prepared by git-pull to\ndescribe what got merged from where for you (see the last few\nlines in the git-pull script).  \n\n> 2. In the SYNOPSIS, there is no <head> that is described in the\n>    OPTIONS.\n\nSee above.  We do not want to advertise the crazy syntax.\n"},{"id":"57593","messageId":"7vk5p4l9gs.fsf@gitster.siamese.dyndns.org","threadId":"10528","inReplyTo":"7vsl3sla5q.fsf@gitster.siamese.dyndns.org","subject":"Re: git-merge: inconsistent manual page.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-10-30T18:54:11Z","receivedAt":"2007-10-30T18:54:11Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Subject: git-merge: document but discourage the historical syntax\n\nHistorically \"git merge\" took its command line arguments in a\nrather strange order.  Document the historical syntax, and also\ndocument clearly that it is not encouraged in new scripts.\n\nThere is no reason to deprecate the historical syntax, as the\ncurrent code can sanely tell which syntax the caller is using,\nand existing scripts by people do use the historical syntax.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n  Junio C Hamano <gitster@pobox.com> writes:\n\n  > See above.  We do not want to advertise the crazy syntax.\n\n  By the way, I kept saying \"crazy\" above, but the thing is that\n  when Linus did that \"crazy\" syntax, it was not crazy at all.\n  Simply it did not matter, as nobody was supposed to use \"git\n  merge\" from the command line.\n\n  Instead, when merging a local branch, you would just have said:\n\n          $ git pull . $my_other_branch\n\n  It became a \"crazy historical syntax\" only after people started\n  talking about using it from the command line, giving it other\n  command line options.  And at that point, we introduced -m flag\n  and stopped requiring the second token 'HEAD'.\n\n  With that in mind, this might be a better alternative.\n\n Documentation/git-merge.txt |    6 ++++++\n 1 files changed, 6 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex bca4212..a056b40 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -11,6 +11,7 @@ SYNOPSIS\n [verse]\n 'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...\n \t[-m <msg>] <remote> <remote>...\n+'git-merge' <msg> HEAD <remote>...\n \n DESCRIPTION\n -----------\n@@ -43,6 +44,11 @@ If you tried a merge which resulted in a complex conflicts and\n would want to start over, you can recover with\n gitlink:git-reset[1].\n \n+The second syntax (<msg> `HEAD` <remote>) is supported for\n+historical reasons.  Do not use it from the command line or in\n+new scripts.\n+\n+\n CONFIGURATION\n -------------\n \n"},{"id":"57607","messageId":"87wst44cvb.fsf@osv.gnss.ru","threadId":"10528","inReplyTo":"7vk5p4l9gs.fsf@gitster.siamese.dyndns.org","subject":"Re: git-merge: inconsistent manual page.","fromName":"Sergei Organov","fromEmail":"osv@javad.com","sentAt":"2007-10-30T19:32:40Z","receivedAt":"2007-10-30T19:32:40Z","isPatch":false,"sender":{"key":"osv@javad.com","avatar":null},"body":"Junio C Hamano <gitster@pobox.com> writes:\n> Subject: git-merge: document but discourage the historical syntax\n>\n> Historically \"git merge\" took its command line arguments in a\n> rather strange order.  Document the historical syntax, and also\n> document clearly that it is not encouraged in new scripts.\n>\n> There is no reason to deprecate the historical syntax, as the\n> current code can sanely tell which syntax the caller is using,\n> and existing scripts by people do use the historical syntax.\n\nOK, your patch is better than what I've suggested. The only thing that\nyour patch seems to be missing is prepending -m to <msg>:: in the\nOPTIONS section. Yeah, it could be more strict to just describe <msg>,\nbut if there were no historical syntax, then you'd put '-m <msg>'\ndescription in, right? So the latter might be better anyway.\n\n-- \nSergei.\n"},{"id":"57629","messageId":"7v4pg8jghg.fsf@gitster.siamese.dyndns.org","threadId":"10528","inReplyTo":"87wst44cvb.fsf@osv.gnss.ru","subject":"Re: git-merge: inconsistent manual page.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-10-31T00:05:31Z","receivedAt":"2007-10-31T00:05:31Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergei Organov <osv@javad.com> writes:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n>> Subject: git-merge: document but discourage the historical syntax\n>>\n>> Historically \"git merge\" took its command line arguments in a\n>> rather strange order.  Document the historical syntax, and also\n>> document clearly that it is not encouraged in new scripts.\n>>\n>> There is no reason to deprecate the historical syntax, as the\n>> current code can sanely tell which syntax the caller is using,\n>> and existing scripts by people do use the historical syntax.\n>\n> OK, your patch is better than what I've suggested. The only thing that\n> your patch seems to be missing is prepending -m to <msg>:: in the\n> OPTIONS section. Yeah, it could be more strict to just describe <msg>,\n> ...\n\nNah, you are absolutely right.  We describe \"-s <strategy>\"\nunder the headline with the leading \"-s\".\n\nWill fix.\n"}]}