{"thread":{"id":"37680","subject":"[PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","startedAt":"2014-10-07T11:54:58Z","lastAt":"2014-10-08T10:12:00Z","messageCount":5,"participants":["Sergey Organov","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"250279","messageId":"87wq8cnla9.fsf@osv.gnss.ru","threadId":"37680","inReplyTo":null,"subject":"[PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-10-07T11:54:58Z","receivedAt":"2014-10-07T11:54:58Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"SYNOPSIS section of the git-merge manual page had outdated explicit\nlist of options.\n\n\"usage\" returned by 'git merge -h' didn't have \"-m \" that is one\nof essential distinctions between obsolete invocation form and the\nrecent one.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/git-merge.txt | 6 ++----\n builtin/merge.c | 2 +-\n 2 files changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex cf2c374..e24a1d4 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -9,10 +9,8 @@ git-merge - Join two or more development histories together\n SYNOPSIS\n --------\n [verse]\n-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n-\t[-s ] [-X ] [-S[]]\n-\t[--[no-]rerere-autoupdate] [-m ] [...]\n-'git merge' HEAD ...\n+'git merge' [options] [-m ] [...]\n+'git merge' [options] HEAD ...\n 'git merge' --abort\n \n DESCRIPTION\ndiff --git a/builtin/merge.c b/builtin/merge.c\nindex dff043d..086502f 100644\n--- a/builtin/merge.c\n+++ b/builtin/merge.c\n@@ -40,7 +40,7 @@ struct strategy {\n };\n \n static const char * const builtin_merge_usage[] = {\n-\tN_(\"git merge [options] [...]\"),\n+\tN_(\"git merge [options] [-m ] [...]\"),\n \tN_(\"git merge [options] HEAD \"),\n \tN_(\"git merge --abort\"),\n \tNULL\n-- \n1.9.3\n"},{"id":"250294","messageId":"xmqq4mvfg24e.fsf@gitster.dls.corp.google.com","threadId":"37680","inReplyTo":"87wq8cnla9.fsf@osv.gnss.ru","subject":"Re: [PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-07T18:34:41Z","receivedAt":"2014-10-07T18:34:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> SYNOPSIS section of the git-merge manual page had outdated explicit\n> list of options.\n>\n> \"usage\" returned by 'git merge -h' didn't have \"-m \" that is one\n> of essential distinctions between obsolete invocation form and the\n> recent one.\n>\n> Signed-off-by: Sergey Organov \n> ---\n\nPlease do not do two unrelated things in a single change.\n\nIt may be a clear and very welcome improvement to change from\n\"explicitly list only often used options\" to \"just say [options] and\nhave the list of options and their descriptions\".\n\nI am not sure about the other change to single out \"-m \",\nespecially marking it as optional by enclosing it inside \"[-m\n]\", makes much sense, as that is still not very easily\ndistinguishable from \"git merge [options] [...]\". In other\nwords, I agree with your motivation to call for attention that the\ncommand behaves differently with and without \"-m\", but I do not\nthink that part of the change in this patch achieves it well.\n\n> Documentation/git-merge.txt | 6 ++----\n> builtin/merge.c | 2 +-\n> 2 files changed, 3 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index cf2c374..e24a1d4 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -9,10 +9,8 @@ git-merge - Join two or more development histories together\n> SYNOPSIS\n> --------\n> [verse]\n> -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]\n> -\t[-s ] [-X ] [-S[]]\n> -\t[--[no-]rerere-autoupdate] [-m ] [...]\n> -'git merge' HEAD ...\n> +'git merge' [options] [-m ] [...]\n> +'git merge' [options] HEAD ...\n> 'git merge' --abort\n> \n> DESCRIPTION\n> diff --git a/builtin/merge.c b/builtin/merge.c\n> index dff043d..086502f 100644\n> --- a/builtin/merge.c\n> +++ b/builtin/merge.c\n> @@ -40,7 +40,7 @@ struct strategy {\n> };\n> \n> static const char * const builtin_merge_usage[] = {\n> -\tN_(\"git merge [options] [...]\"),\n> +\tN_(\"git merge [options] [-m ] [...]\"),\n> \tN_(\"git merge [options] HEAD \"),\n> \tN_(\"git merge --abort\"),\n> \tNULL\n"},{"id":"250313","messageId":"87bnpnsjrw.fsf@osv.gnss.ru","threadId":"37680","inReplyTo":"xmqq4mvfg24e.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-10-07T20:32:35Z","receivedAt":"2014-10-07T20:32:35Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> SYNOPSIS section of the git-merge manual page had outdated explicit\n>> list of options.\n>>\n>> \"usage\" returned by 'git merge -h' didn't have \"-m \" that is one\n>> of essential distinctions between obsolete invocation form and the\n>> recent one.\n>>\n>> Signed-off-by: Sergey Organov \n>> ---\n>\n> Please do not do two unrelated things in a single change.\n\nWell, I thought they are related, sorry.\n\n> It may be a clear and very welcome improvement to change from\n> \"explicitly list only often used options\" to \"just say [options] and\n> have the list of options and their descriptions\".\n\nOK, noticed.\n\n> I am not sure about the other change to single out \"-m \",\n> especially marking it as optional by enclosing it inside \"[-m\n> ]\", makes much sense, as that is still not very easily\n> distinguishable from \"git merge [options] [...]\".\n\nI was looking at the merge.c code, and that's how it seems to work. You\ncan get new semantics without -m, and you can't get old semantics with\n-m, isn't it? It looks like the set of descriptions I produced is\nformally correct.\n\n> In other words, I agree with your motivation to call for attention\n> that the command behaves differently with and without \"-m\", but I do\n> not think that part of the change in this patch achieves it well.\n\nAny particular suggestion?\n\nThanks.\n\n-- \nSergey.\n"},{"id":"250320","messageId":"xmqq1tqjefd8.fsf@gitster.dls.corp.google.com","threadId":"37680","inReplyTo":"87bnpnsjrw.fsf@osv.gnss.ru","subject":"Re: [PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-10-07T21:31:31Z","receivedAt":"2014-10-07T21:31:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Junio C Hamano writes:\n> ...\n> I was looking at the merge.c code, and that's how it seems to work. You\n> can get new semantics without -m, and you can't get old semantics with\n> -m, isn't it? It looks like the set of descriptions I produced is\n> formally correct.\n\nThe thing is, with \"-m \" we will never fall into the\ntraditional syntax, hence \"git merge -m HEAD \"\nappear to be allowed with \"git merge [options] HEAD\n...\", but it is not.\n\nAnd the inverse is not true (an obvious example is \"git merge\n$branch\", even though it does not have \"-m \" it uses the modern\n& common.\n\nSo the updated SYNOPSIS is not really helping.\n\n>> In other words, I agree with your motivation to call for attention\n>> that the command behaves differently with and without \"-m\", but I do\n>> not think that part of the change in this patch achieves it well.\n>\n> Any particular suggestion?\n\nI was going to suggest \"explain how the traditional syntax is\ntriggered in the DESCRIPTION section\", but it turns out that we\nalready do that.\n\n The second syntax ( HEAD ...) is supported for\n historical reasons. Do not use it from the command line or in\n new scripts. It is the same as git merge -m ....\n\nStrictly speaking, I think it is not qute \"the same\"---I recall\nvaguely that it broke tests if you replace the traditional-style\ninvocation in 'git pull' with the -m syntax, but I do not have\ndetails handy; you may want to try it out if you are interested.\n\nSo I would think\n\n\tSYNOPSIS\n \tgit merge [options] ...\n\t\tgit merge [options] HEAD ...\n git merge --abort\n\nshould be sufficient, possibly with some clarification on \"The\nsecond syntax\" paragraph in the DESCRIPTION section.\n"},{"id":"250350","messageId":"87h9zeg9an.fsf@osv.gnss.ru","threadId":"37680","inReplyTo":"xmqq1tqjefd8.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-merge: mutually match SYNOPSIS and \"usage\".","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2014-10-08T10:12:00Z","receivedAt":"2014-10-08T10:12:00Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> Junio C Hamano writes:\n>> ...\n>> I was looking at the merge.c code, and that's how it seems to work. You\n>> can get new semantics without -m, and you can't get old semantics with\n>> -m, isn't it? It looks like the set of descriptions I produced is\n>> formally correct.\n>\n> The thing is, with \"-m \" we will never fall into the\n> traditional syntax, hence \"git merge -m HEAD \"\n> appear to be allowed with \"git merge [options] HEAD\n> ...\", but it is not.\n\nNo. When you see:\n\n git merge [options] [-m ] ...\n\nIsn't it obvious that 'options' don't include \"-m \", so\n \n git merge [options] HEAD ...\n\nform will never apply when you have \"-m \" in the command, exaclty\nbecause 'options' don't include \"-m \n> And the inverse is not true (an obvious example is \"git merge\n> $branch\", even though it does not have \"-m \" it uses the modern\n> & common.\n\nSure, and this is covered as well.\n\n> So the updated SYNOPSIS is not really helping.\n\nI disagree, see above.\n\nI still think that for somewhat messy historical situation, the\nsuggested syntax description is good enough.\n\n-- \nSergey.\n"}]}