[PATCH] Rearrange git-format-patch synopsis to improve clarity.

[PATCH] Rearrange git-format-patch synopsis to improve clarity.

[David Symonds]

Signed-off-by: David Symonds <dsymonds@gmail.com>
---
 Documentation/git-format-patch.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 92c0ab6..d8a89a1 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -9,10 +9,11 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git-format-patch' [-n | -N | -k] [-o <dir> | --stdout] [--thread]
+'git-format-patch' [-k] [-o <dir> | --stdout] [--thread]
                    [--attach[=<boundary>] | --inline[=<boundary>]]
                    [-s | --signoff] [<common diff options>]
-                   [--start-number <n>] [--numbered-files]
+                   [-n | --numbered-files | -N | --no-numbered]
+                   [--start-number <n>]
                    [--in-reply-to=Message-Id] [--suffix=.<sfx>]
                    [--ignore-if-in-upstream]
                    [--subject-prefix=Subject-Prefix]
-- 
1.5.3.1

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[Junio C Hamano]

Thanks

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[David Symonds]

On 11/5/07, David Symonds <dsymonds@gmail.com> wrote:
>                     [-s | --signoff] [<common diff options>]
> -                   [--start-number <n>] [--numbered-files]
> +                   [-n | --numbered-files | -N | --no-numbered]
> +                   [--start-number <n>]

Now that I look at it again, it seems the long options look quite
inconsistent. I think it should be either
--numbered-files/--no-numbered-files or --numbered/--no-numbered. My
preference is with the latter (for brevity), but that breaks
backward-compatibility.

Would you accept a patch that changed --numbered-files to --numbered,
and kept the former as a synonym?


Dave.

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[Andreas Ericsson]

David Symonds wrote:
> On 11/5/07, David Symonds <dsymonds@gmail.com> wrote:
>>                     [-s | --signoff] [<common diff options>]
>> -                   [--start-number <n>] [--numbered-files]
>> +                   [-n | --numbered-files | -N | --no-numbered]
>> +                   [--start-number <n>]
> 
> Now that I look at it again, it seems the long options look quite
> inconsistent. I think it should be either
> --numbered-files/--no-numbered-files or --numbered/--no-numbered. My
> preference is with the latter (for brevity), but that breaks
> backward-compatibility.
> 
> Would you accept a patch that changed --numbered-files to --numbered,
> and kept the former as a synonym?
> 

I thought files were always numbered, but the [PATCH m/n] wasn't. Have I
missed something?

If your --numbered-files is supposed to affect only file-numbering, I'd
suggest *not* using --numbered, as it's ambiguous with "number-subject".

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[David Symonds]

On 11/6/07, Andreas Ericsson <ae@op5.se> wrote:
> David Symonds wrote:
> > On 11/5/07, David Symonds <dsymonds@gmail.com> wrote:
> >>                     [-s | --signoff] [<common diff options>]
> >> -                   [--start-number <n>] [--numbered-files]
> >> +                   [-n | --numbered-files | -N | --no-numbered]
> >> +                   [--start-number <n>]
> >
> > Now that I look at it again, it seems the long options look quite
> > inconsistent. I think it should be either
> > --numbered-files/--no-numbered-files or --numbered/--no-numbered. My
> > preference is with the latter (for brevity), but that breaks
> > backward-compatibility.
> >
> > Would you accept a patch that changed --numbered-files to --numbered,
> > and kept the former as a synonym?
> >
>
> I thought files were always numbered, but the [PATCH m/n] wasn't. Have I
> missed something?
>
> If your --numbered-files is supposed to affect only file-numbering, I'd
> suggest *not* using --numbered, as it's ambiguous with "number-subject".

You're right. There's both --numbered ([PATCH n/m] stuff) and
--numbered-files (0001.patch instead of 0001-subject-line.patch). I'll
revise my patch to clarify this.


Dave.

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[Jon Loeliger]

David Symonds wrote:
> On 11/5/07, David Symonds <dsymonds@gmail.com> wrote:
>>                     [-s | --signoff] [<common diff options>]
>> -                   [--start-number <n>] [--numbered-files]
>> +                   [-n | --numbered-files | -N | --no-numbered]
>> +                   [--start-number <n>]
> 
> Now that I look at it again, it seems the long options look quite
> inconsistent. I think it should be either
> --numbered-files/--no-numbered-files or --numbered/--no-numbered. My
> preference is with the latter (for brevity), but that breaks
> backward-compatibility.
> 
> Would you accept a patch that changed --numbered-files to --numbered,
> and kept the former as a synonym?

There are two forms of numbered file output names:
the traditional "0001-Foo-the-bar" and just "1" styles.
Please don't break that.  Both are needed.

Thanks,
jdl

Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.

[David Symonds]

On 11/7/07, Jon Loeliger <jdl@freescale.com> wrote:
> David Symonds wrote:
> > Now that I look at it again, it seems the long options look quite
> > inconsistent. I think it should be either
> > --numbered-files/--no-numbered-files or --numbered/--no-numbered. My
> > preference is with the latter (for brevity), but that breaks
> > backward-compatibility.
> >
> > Would you accept a patch that changed --numbered-files to --numbered,
> > and kept the former as a synonym?
>
> There are two forms of numbered file output names:
> the traditional "0001-Foo-the-bar" and just "1" styles.
> Please don't break that.  Both are needed.

Oh, I certainly wasn't proposing removing any functionality; merely
renaming the option to select it so as to be consistent.


Dave.