Re: [PATCH] show --continue/skip etc. consistently in synopsis

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 16, 2019, 22:33 UTC
Message-ID: <xmqq36k9tb30.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20190616132457.19413-1-phillip.wood123@gmail.com>

Phillip Wood <phillip.wood123@gmail.com> writes:

Show 6 quoted lines

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> The synopsis for am shows the command mode options as
>     (--continue | --skip | --abort | --quit)
> They are on a single line and in parenthesis as they are not
> optional. Fix the merge and rebase docs to match this style.

Is it so clear-cut that it is more "correct" to have everything on a single line, as opposed to describing each one per line? I am not sure.

I would say both the above style and the style used by "git merge" documentation are correct. The "rebase" one is a different story and the change in this patch deserves to be called a "fix".

As long as the more concise "am" style is already prevalent (are there pages other than "am" you can cite?), I would agree with you that the change to "git merge" in this patch is a good idea for consistency's sake.

> ---
> This patch is based on top of nd/merge-quit.

Thanks for indicating where it should go. We need your sign-off, too.

Show 34 quoted lines

> The docs for cherry-pick/revert are updated to this style by
> https://public-inbox.org/git/20190616082040.9440-1-rohit.ashiwal265@gmail.com/T/#u
>
> Documentation/git-merge.txt  | 3 +--
>  Documentation/git-rebase.txt | 2 +-
>  2 files changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index b7d581fc76..07ca9fb78c 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -13,8 +13,7 @@ SYNOPSIS
>  	[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
>  	[--[no-]allow-unrelated-histories]
>  	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...]
> -'git merge' --abort
> -'git merge' --continue
> +'git merge' (--continue | --skip | --abort | --quit)
>  
>  DESCRIPTION
>  -----------
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 5629ba4c5d..a67d40596a 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -12,7 +12,7 @@ SYNOPSIS
>  	[<upstream> [<branch>]]
>  'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
>  	--root [<branch>]
> -'git rebase' --continue | --skip | --abort | --quit | --edit-todo | --show-current-patch
> +'git rebase' (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch)
>  
>  DESCRIPTION
>  -----------