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

7 messages from 2007-11-04 to 2007-11-06. Participants: David Symonds, Junio C Hamano, Andreas Ericsson, Jon Loeliger.
Thread: https://gitlist.dev/t/10656

## David Symonds, 2007-11-04 22:27

Subject: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <119421522591-git-send-email-dsymonds@gmail.com>
URL: https://gitlist.dev/e/119421522591-git-send-email-dsymonds%40gmail.com

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

```

## Junio C Hamano, 2007-11-05 21:22

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <7vtzo0o09u.fsf@gitster.siamese.dyndns.org>
URL: https://gitlist.dev/e/7vtzo0o09u.fsf%40gitster.siamese.dyndns.org
In-Reply-To: <119421522591-git-send-email-dsymonds@gmail.com>

```
Thanks

```

## David Symonds, 2007-11-05 22:32

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <ee77f5c20711051432w284cf22dx71192c145d25dced@mail.gmail.com>
URL: https://gitlist.dev/e/ee77f5c20711051432w284cf22dx71192c145d25dced%40mail.gmail.com
In-Reply-To: <119421522591-git-send-email-dsymonds@gmail.com>

```
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, 2007-11-05 22:48

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <472F9DC6.8020607@op5.se>
URL: https://gitlist.dev/e/472F9DC6.8020607%40op5.se
In-Reply-To: <ee77f5c20711051432w284cf22dx71192c145d25dced@mail.gmail.com>

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

```

## David Symonds, 2007-11-05 22:56

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <ee77f5c20711051456i1bbd0d58j43490c55e0be9664@mail.gmail.com>
URL: https://gitlist.dev/e/ee77f5c20711051456i1bbd0d58j43490c55e0be9664%40mail.gmail.com
In-Reply-To: <472F9DC6.8020607@op5.se>

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

```

## Jon Loeliger, 2007-11-06 15:01

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <473081C2.7060106@freescale.com>
URL: https://gitlist.dev/e/473081C2.7060106%40freescale.com
In-Reply-To: <ee77f5c20711051432w284cf22dx71192c145d25dced@mail.gmail.com>

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

```

## David Symonds, 2007-11-06 21:08

Subject: Re: [PATCH] Rearrange git-format-patch synopsis to improve clarity.
Message-ID: <ee77f5c20711061308p11c091f7h730b93c9b49542df@mail.gmail.com>
URL: https://gitlist.dev/e/ee77f5c20711061308p11c091f7h730b93c9b49542df%40mail.gmail.com
In-Reply-To: <473081C2.7060106@freescale.com>

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

```