[2/3] Doc: add more detail for git-format-patch
diff mbox series

Message ID 7619da962d1fc804392e3552fbd56bf4bc68ac38.1566182184.git.liu.denton@gmail.com
State New
Headers show
Series
  • format-patch: teach --infer-cover-subject option
Related show

Commit Message

Denton Liu Aug. 19, 2019, 2:37 a.m. UTC
In git-format-patch.txt, we were missing some key user information.
First of all, using the `--to` and `--cc` options don't override
`format.to` and `format.cc` variables, respectively. They add on to each
other. Document this.

In addition, document the special value of `--base=auto`.

Next, while we're at it, surround option arguments with <>.

Finally, document the `format.outputDirectory` config and change
`format.coverletter` to use camelcase.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-format-patch.txt | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

Comments

Eric Sunshine Aug. 19, 2019, 5:09 p.m. UTC | #1
On Sun, Aug 18, 2019 at 10:37 PM Denton Liu <liu.denton@gmail.com> wrote:
> In git-format-patch.txt, we were missing some key user information.
> First of all, using the `--to` and `--cc` options don't override
> `format.to` and `format.cc` variables, respectively. They add on to each
> other. Document this.
>
> In addition, document the special value of `--base=auto`.
>
> Next, while we're at it, surround option arguments with <>.
>
> Finally, document the `format.outputDirectory` config and change
> `format.coverletter` to use camelcase.

I can't figure out if you typeset "camelcase" like that intentionally,
as opposed to "camelCase" or "camel case" or "camel-case".

> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
>  --to=<email>::
>         Add a `To:` header to the email headers. This is in addition
> -       to any configured headers, and may be used multiple times.
> +       to any configured headers, and may be used multiple times. The
> +       emails given will be used along with any emails given by
> +       `format.to` configurations.

Hmph. This seems redundant. The description already says "This is in
addition to...", so a new sentence saying "...used along with..." is
just parroting what was already stated.

>         The negated form `--no-to` discards all `To:` headers added so
>         far (from config or command line).
> @@ -314,7 +318,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
>  --base=<commit>::
>         Record the base tree information to identify the state the
>         patch series applies to.  See the BASE TREE INFORMATION section
> -       below for details.
> +       below for details. If <commit> is equal to "auto", a base commit
> +       is automatically chosen.

"is equal to" is unnecessarily technical-sounding. How about:

    If <commit> is "auto", ...
Denton Liu Aug. 19, 2019, 11:16 p.m. UTC | #2
On Mon, Aug 19, 2019 at 01:09:04PM -0400, Eric Sunshine wrote:
> On Sun, Aug 18, 2019 at 10:37 PM Denton Liu <liu.denton@gmail.com> wrote:
> > In git-format-patch.txt, we were missing some key user information.
> > First of all, using the `--to` and `--cc` options don't override
> > `format.to` and `format.cc` variables, respectively. They add on to each
> > other. Document this.
> >
> > In addition, document the special value of `--base=auto`.
> >
> > Next, while we're at it, surround option arguments with <>.
> >
> > Finally, document the `format.outputDirectory` config and change
> > `format.coverletter` to use camelcase.
> 
> I can't figure out if you typeset "camelcase" like that intentionally,
> as opposed to "camelCase" or "camel case" or "camel-case".

I thought that was how it's spelled but a quick Google search proves me
wrong.

> 
> > Signed-off-by: Denton Liu <liu.denton@gmail.com>
> > ---
> > diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> >  --to=<email>::
> >         Add a `To:` header to the email headers. This is in addition
> > -       to any configured headers, and may be used multiple times.
> > +       to any configured headers, and may be used multiple times. The
> > +       emails given will be used along with any emails given by
> > +       `format.to` configurations.
> 
> Hmph. This seems redundant. The description already says "This is in
> addition to...", so a new sentence saying "...used along with..." is
> just parroting what was already stated.
> 
> >         The negated form `--no-to` discards all `To:` headers added so
> >         far (from config or command line).
> > @@ -314,7 +318,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
> >  --base=<commit>::
> >         Record the base tree information to identify the state the
> >         patch series applies to.  See the BASE TREE INFORMATION section
> > -       below for details.
> > +       below for details. If <commit> is equal to "auto", a base commit
> > +       is automatically chosen.
> 
> "is equal to" is unnecessarily technical-sounding. How about:
> 
>     If <commit> is "auto", ...
Junio C Hamano Aug. 20, 2019, 7:01 p.m. UTC | #3
Denton Liu <liu.denton@gmail.com> writes:

> Next, while we're at it, surround option arguments with <>.
> ...
>  		   [--start-number <n>] [--numbered-files]
> -		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
> +		   [--in-reply-to=<Message-Id>] [--suffix=.<sfx>]
>  		   [--ignore-if-in-upstream]
> -		   [--rfc] [--subject-prefix=Subject-Prefix]
> +		   [--rfc] [--subject-prefix=<Subject-Prefix>]
> ...
> ---in-reply-to=Message-Id::
> +--in-reply-to=<Message-Id>::

That is a good change, but if we are making this change while are at
it, I think we should fix it to read <message id>.  "Message-Id" is
a good spelling iff we are talking about the label on the left hand
side of colon in e-mail header, but in this context, we are talking
about the value to be placed on that header.

All the other multi-word placeholders in the SYNOPSIS section spell
the words as normal multiple words separated with whitespace in
lower case.  You'd also want to fix the spelling of Subject-Prefix
to <subject prefix> for consistency.

Thanks.

Patch
diff mbox series

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index b9b97e63ae..0e2dd59c0f 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -17,9 +17,9 @@  SYNOPSIS
 		   [--signature-file=<file>]
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
-		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
+		   [--in-reply-to=<Message-Id>] [--suffix=.<sfx>]
 		   [--ignore-if-in-upstream]
-		   [--rfc] [--subject-prefix=Subject-Prefix]
+		   [--rfc] [--subject-prefix=<Subject-Prefix>]
 		   [(--reroll-count|-v) <n>]
 		   [--to=<email>] [--cc=<email>]
 		   [--[no-]cover-letter] [--quiet]
@@ -159,7 +159,7 @@  Beware that the default for 'git send-email' is to thread emails
 itself.  If you want `git format-patch` to take care of threading, you
 will want to ensure that threading is disabled for `git send-email`.
 
---in-reply-to=Message-Id::
+--in-reply-to=<Message-Id>::
 	Make the first mail (or all the mails with `--no-thread`) appear as a
 	reply to the given Message-Id, which avoids breaking threads to
 	provide a new patch series.
@@ -193,13 +193,17 @@  will want to ensure that threading is disabled for `git send-email`.
 
 --to=<email>::
 	Add a `To:` header to the email headers. This is in addition
-	to any configured headers, and may be used multiple times.
+	to any configured headers, and may be used multiple times. The
+	emails given will be used along with any emails given by
+	`format.to` configurations.
 	The negated form `--no-to` discards all `To:` headers added so
 	far (from config or command line).
 
 --cc=<email>::
 	Add a `Cc:` header to the email headers. This is in addition
-	to any configured headers, and may be used multiple times.
+	to any configured headers, and may be used multiple times. The
+	emails given will be used along with any emails given by
+	`format.cc` configurations.
 	The negated form `--no-cc` discards all `Cc:` headers added so
 	far (from config or command line).
 
@@ -314,7 +318,8 @@  you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 --base=<commit>::
 	Record the base tree information to identify the state the
 	patch series applies to.  See the BASE TREE INFORMATION section
-	below for details.
+	below for details. If <commit> is equal to "auto", a base commit
+	is automatically chosen.
 
 --root::
 	Treat the revision argument as a <revision range>, even if it
@@ -330,8 +335,9 @@  CONFIGURATION
 -------------
 You can specify extra mail header lines to be added to each message,
 defaults for the subject prefix and file suffix, number patches when
-outputting more than one patch, add "To" or "Cc:" headers, configure
-attachments, and sign off patches with configuration variables.
+outputting more than one patch, add "To:" or "Cc:" headers, configure
+attachments, change the patch output directory, and sign off patches
+with configuration variables.
 
 ------------
 [format]
@@ -343,7 +349,8 @@  attachments, and sign off patches with configuration variables.
 	cc = <email>
 	attach [ = mime-boundary-string ]
 	signOff = true
-	coverletter = auto
+	outputDirectory = <directory>
+	coverLetter = auto
 ------------