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

From: Phillip Wood <phillip.wood123@gmail.com>
Date: Jun 17, 2019, 09:15 UTC
Message-ID: <991b0908-4ec5-2d19-4df3-df3eb28632c2@gmail.com>
In-Reply-To: <xmqq36k9tb30.fsf@gitster-ct.c.googlers.com>

On 16/06/2019 23:33, Junio C Hamano wrote:

Show 12 quoted lines

> Phillip Wood <phillip.wood123@gmail.com> writes:
> 
>> 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'm not sure I'd argue too hard one way or the other, but I do think the documentation for the various commands should try to be consistent and the am, cherry-pick, rebase and revert man pages all use a single line for these options (although rebase is missing the parentheses).

I'll re-roll with Elijah's correction and a sign off

Best Wishes

Phillip

Show 51 quoted lines

> 
> 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.>
> 
> 
>> 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
>>  -----------