threads / patch / 10656

patchRearrange git-format-patch synopsis to improve clarity.

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

## tl;dr

7 messages between Nov 4, 2007 and Nov 6, 2007. Diffs are folded; open one to read it.

replies: 6people: 4as markdown or json

David Symonds· Nov 4, 2007, 22:27 UTC · lore
Signed-off-by: David Symonds <dsymonds@gmail.com>
---
 Documentation/git-format-patch.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)
Show changes to Documentation/git-format-patch.txt +3 −2
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
David Symonds· Nov 5, 2007, 22:32 UTC · re: David Symonds · lore

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

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.
Andreas Ericsson· Nov 5, 2007, 22:48 UTC · re: David Symonds · lore

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

David Symonds wrote:
Show 15 quoted lines
> 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
David Symonds· Nov 5, 2007, 22:56 UTC · re: Andreas Ericsson · lore

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

On 11/6/07, Andreas Ericsson <ae@op5.se> wrote:
Show 22 quoted lines
> 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.
Jon Loeliger· Nov 6, 2007, 15:01 UTC · re: David Symonds · lore

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

David Symonds wrote:
Show 14 quoted lines
> 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

David Symonds· Nov 6, 2007, 21:08 UTC · re: Jon Loeliger · lore

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

On 11/7/07, Jon Loeliger <jdl@freescale.com> wrote:
Show 13 quoted lines
> 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.

← back to recent threads