| Message ID | 7619da962d1fc804392e3552fbd56bf4bc68ac38.1566182184.git.liu.denton@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | format-patch: teach --infer-cover-subject option | expand |
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", ...
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", ...
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.
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 ------------
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(-)