Re: [PATCH] git-merge: mutually match SYNOPSIS and "usage".
From: Junio C Hamano <hidden>
Date: 2016-06-15 23:02:39
Sergey Organov [off-list ref] writes:
SYNOPSIS section of the git-merge manual page had outdated explicit list of options. "usage" returned by 'git merge -h' didn't have "-m <msg>" that is one of essential distinctions between obsolete invocation form and the recent one. Signed-off-by: Sergey Organov <redacted> ---
Please do not do two unrelated things in a single change. It may be a clear and very welcome improvement to change from "explicitly list only often used options" to "just say [options] and have the list of options and their descriptions". I am not sure about the other change to single out "-m <msg>", especially marking it as optional by enclosing it inside "[-m <msg>]", makes much sense, as that is still not very easily distinguishable from "git merge [options] [<commit>...]". In other words, I agree with your motivation to call for attention that the command behaves differently with and without "-m", but I do not think that part of the change in this patch achieves it well.
quoted hunk
Documentation/git-merge.txt | 6 ++---- builtin/merge.c | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-)diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index cf2c374..e24a1d4 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt@@ -9,10 +9,8 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s <strategy>] [-X <strategy-option>] [-S[<key-id>]] - [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] -'git merge' <msg> HEAD <commit>... +'git merge' [options] [-m <msg>] [<commit>...] +'git merge' [options] <msg> HEAD <commit>... 'git merge' --abort DESCRIPTIONdiff --git a/builtin/merge.c b/builtin/merge.c index dff043d..086502f 100644 --- a/builtin/merge.c +++ b/builtin/merge.c@@ -40,7 +40,7 @@ struct strategy { }; static const char * const builtin_merge_usage[] = { - N_("git merge [options] [<commit>...]"), + N_("git merge [options] [-m <msg>] [<commit>...]"), N_("git merge [options] <msg> HEAD <commit>"), N_("git merge --abort"), NULL