Doc: add more detail for git-format-patch

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 1af85d404f5191c18a8c587df06e7c0620066236..0ac56f4b7080bc3d8718e7cad7dab4fedca0f670 100644 (file)
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -17,12 +17,13 @@ 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] [--notes[=<ref>]]
+                  [--[no-]cover-letter] [--quiet]
+                  [--no-notes | --notes[=<ref>]]
                   [--interdiff=<previous>]
                   [--range-diff=<previous> [--creation-factor=<percent>]]
                   [--progress]
@@ -158,9 +159,9 @@ 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
+       reply to the given <message id>, which avoids breaking threads to
        provide a new patch series.
 
 --ignore-if-in-upstream::
@@ -170,9 +171,9 @@ will want to ensure that threading is disabled for `git send-email`.
        patches being generated, and any patch that matches is
        ignored.
 
---subject-prefix=<Subject-Prefix>::
+--subject-prefix=<subject prefix>::
        Instead of the standard '[PATCH]' prefix in the subject
-       line, instead use '[<Subject-Prefix>]'. This
+       line, instead use '[<subject prefix>]'. This
        allows for useful naming of a patch series, and can be
        combined with the `--numbered` option.
 
@@ -263,6 +264,7 @@ material (this may change in the future).
        for details.
 
 --notes[=<ref>]::
+--no-notes::
        Append the notes (see linkgit:git-notes[1]) for the commit
        after the three-dash line.
 +
@@ -273,6 +275,9 @@ these explanations after `format-patch` has run but before sending,
 keeping them as Git notes allows them to be maintained between versions
 of the patch series (but see the discussion of the `notes.rewrite`
 configuration options in linkgit:git-notes[1] to use this workflow).
++
+The default is `--no-notes`, unless the `format.notes` configuration is
+set.
 
 --[no-]signature=<signature>::
        Add a signature to each message produced. Per RFC 3676 the signature
@@ -309,7 +314,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 "auto", a base commit is
+       automatically chosen.
 
 --root::
        Treat the revision argument as a <revision range>, even if it
@@ -325,8 +331,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]
@@ -338,7 +345,8 @@ attachments, and sign off patches with configuration variables.
        cc = <email>
        attach [ = mime-boundary-string ]
        signOff = true
-       coverletter = auto
+       outputDirectory = <directory>
+       coverLetter = auto
 ------------
 
 
@@ -421,8 +429,8 @@ One way to test if your MUA is set up correctly is:
 * Apply it:
 
     $ git fetch <project> master:test-apply
-    $ git checkout test-apply
-    $ git reset --hard
+    $ git switch test-apply
+    $ git restore --source=HEAD --staged --worktree :/
     $ git am a.patch
 
 If it does not apply correctly, there can be various reasons.