threads / patch / 51325

patchshow --continue/skip etc. consistently in synopsis

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

## tl;dr

7 messages between Jun 16, 2019 and Jun 17, 2019. Diffs are folded; open one to read it.

replies: 6people: 3as markdown or json

Phillip Wood· Jun 16, 2019, 13:24 UTC · lore

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.
---
This patch is based on top of nd/merge-quit.
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(-)

Show changes to 2 files +2 −3

Documentation/git-merge.txt, Documentation/git-rebase.txt

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

-- 
2.22.0

Junio C Hamano· Jun 16, 2019, 22:33 UTC · re: Phillip Wood · lore

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

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

Phillip Wood· Jun 17, 2019, 09:15 UTC · re: Junio C Hamano · lore

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

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

Junio C Hamano· Jun 17, 2019, 22:35 UTC · re: Phillip Wood · lore

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

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

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

Good. Then please write these names in the proposed log message; the version I commented on looked a bit strange to single out "am", as if we are siding on a minority, but writing the names of its friends that share the convention would not give that wrong impression to the readers.

Thanks.

Elijah Newren· Jun 17, 2019, 02:02 UTC · re: Phillip Wood · lore

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

On Sun, Jun 16, 2019 at 6:29 AM Phillip Wood <phillip.wood123@gmail.com> wrote:

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

Thanks for working to make this more consistent.  One minor issue...

Show 20 quoted lines

> ---
> This patch is based on top of nd/merge-quit.
> 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)

merge --skip? I think you meant to just add --quit here, but copied from elsewhere and accidentally inserted --skip?

Phillip Wood· Jun 17, 2019, 09:11 UTC · re: Elijah Newren · lore

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

On 17/06/2019 03:02, Elijah Newren wrote:

Show 34 quoted lines

> On Sun, Jun 16, 2019 at 6:29 AM Phillip Wood <phillip.wood123@gmail.com> wrote:
>>
>> 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.
> 
> Thanks for working to make this more consistent.  One minor issue...
> 
>> ---
>> This patch is based on top of nd/merge-quit.
>> 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)
> 
> merge --skip?  I think you meant to just add --quit here, but copied
> from elsewhere and accidentally inserted --skip?

Thanks, you're right I got a bit carried away with copying and pasting.

Best Wishes

Phillip

Phillip Wood· Jun 17, 2019, 09:17 UTC · re: Phillip Wood · lore

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

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.

Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
---

Notes:
    This patch is based on top of nd/merge-quit.
    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(-)

Show changes to 2 files +2 −3

Documentation/git-merge.txt, Documentation/git-rebase.txt

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index b7d581fc76..926ea4f460 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 | --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
 -----------

-- 
2.21.0