docs: document b4 am --check and related config changes

Also appease vale by using wording that makes it happy.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

3 files changed, 154 insertions, 116 deletions

diff --git a/docs/config.rst b/docs/config.rst
index f03bf58..cd3d151 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -135,9 +135,9 @@ These options control many of the core features of b4.
 
 .. _shazam_settings:
 
-``shazam`` settings
-~~~~~~~~~~~~~~~~~~~
-These settings control how ``b4 shazam`` applies patches to your tree.
+``am`` and ``shazam`` settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These settings control ``b4 am`` and ``b4 shazam`` behavior.
 
 ``b4.shazam-am-flags``
   Additional flags to pass to ``git am`` when applying patches.
@@ -156,6 +156,13 @@ These settings control how ``b4 shazam`` applies patches to your tree.
 
   Default: ``None``
 
+``b4.am-perpatch-check-cmd`` (v0.14+)
+  The command to use when running with ``--check``. If b4 finds
+  ``scripts/checkpatch.pl`` at the top of your git tree, it uses the
+  command shown below by default.
+
+  Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+
 .. _attestation_settings:
 
 Attestation settings
@@ -407,6 +414,26 @@ Contributor-oriented settings
 
   Default: ``None``
 
+``b4.prep-perpatch-check-cmd`` (v0.14+)
+  The command to use when running ``--check``. If b4 finds
+  ``scripts/checkpatch.pl`` at the top of your git tree, it uses the
+  command shown below by default.
+
+  Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile```
+
+``b4.prep-pre-flight-checks`` (v0.14+)
+  You can use this to turn off some or all pre-flight checks that b4 runs
+  prior to sending out patches. To cancel all checks::
+
+      [b4]
+      prep-pre-flight-checks = disable-all
+
+  To turn off specific checks, list each one of them, separated by
+  comma::
+
+      [b4]
+      prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+
 
 To document
 -----------
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index e0ecaed..2d672c3 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -1,22 +1,23 @@
 am,shazam: retrieving and applying patches
 ==========================================
-Most commonly, b4 is used to retrieve, prepare, and apply patches sent
-via distribution lists. The base functionality is similar to that of
-``b4 mbox``::
+The most common use of b4 is to retrieve, prepare, and apply patches
+sent via distribution lists. For example, you can use it to retrieve a
+set of patches using the ``Message-ID``::
 
     b4 am 20200313231252.64999-1-keescook@chromium.org
 
-This will do the following:
+This does the following:
 
-1. look up if that message-id is known on the specified public-inbox
-   server (e.g. lore.kernel.org)
-2. retrieve the full thread containing that message-id
-3. process all replies to collect code review trailers and apply them to
-   the relevant patch commit messages
-4. perform attestation checks on patches and code review follow-ups
-5. put all patches in the correct order and prepare for "git am"
-6. write out the resulting mailbox so it is ready to be applied to a git
-   tree
+1. Looks up that Message-ID on the specified public-inbox server, using
+   lore.kernel.org by default.
+2. Retrieves the full thread containing that message-id.
+3. Processes all replies to collect code review trailers and apply them
+   to the corresponding commit messages.
+4. Performs attestation checks on patches and follow-ups containing
+   code-review trailers.
+5. Puts all patches in the correct order and prepares them for "git am"
+6. Writes out the resulting mailbox so it is ready to be applied to a
+   git tree.
 
 For example::
 
@@ -36,33 +37,28 @@ For example::
      Base: not specified
            git am ./v2_20200313_keescook_selftests_harness_handle_timeouts_cleanly.mbx
 
-
 b4 am vs. b4 shazam
 -------------------
-.. note::
-
-   ``b4 shazam`` was added in version v0.9.
+The two commands are similar -- the main distinction is that ``b4 am``
+prepares the patch series so you can ``git am`` the resulting mbox file,
+but it doesn't make any actual modifications to your current branch.
 
-The two commands are very similar -- the main distinction is that ``b4
-am`` will prepare the patch series for application to the git tree, but
-will not make any modifications to your current branch.
-
-The ``b4 shazam`` command will do the same as ``b4 am`` *and* will apply
-the patch series to the current branch (if it is possible to do so
-cleanly).
+The ``b4 shazam`` command dos the same as ``b4 am`` *and* actually
+applies the patch series to the current branch (if it's possible to do
+so cleanly).
 
 Common flags
 ------------
 The following flags are common to both commands:
 
 ``-m LOCALMBOX, --use-local-mbox LOCALMBOX``
-  By default, b4 will retrieve threads from remote public-inbox servers,
-  but it can also use a local mailbox/maildir. This is useful if you
-  have a tool like ``mbsync`` or ``lei`` copying remote messages locally
-  and you need to do some work while offline. You can pass ``-`` to read
+  By default, b4 retrieves threads from remote public-inbox servers, but
+  it can also use a local mailbox/maildir. This is useful if you have a
+  tool like ``mbsync`` or ``lei`` copying remote messages locally and
+  you need to do some work while offline. You can pass ``-`` to read
   messages from stdin.
 
-``--stdin-pipe-sep STDIN_PIPE_SEP`` **(0.11+)**
+``--stdin-pipe-sep STDIN_PIPE_SEP``
   When reading input from stdin, split messages using the string passed
   as parameter. Otherwise, b4 expects stdin to be a single message or a
   valid mbox.
@@ -75,27 +71,28 @@ The following flags are common to both commands:
   Then invoke b4 with ``-m - --stdin-pipe-sep='\n---randomstr---\n'``
 
 ``-C, --no-cache``
-  By default, b4 will cache the retrieved threads for about 10 minutes.
+  By default, b4 caches the retrieved threads for about 10 minutes.
   This lets you force b4 to ignore cache and retrieve the latest
   results.
 
 ``--single-message`` **(0.13+)**
-  By default, b4 will retrieve the entire thread, but sometimes you
-  really just want a single message. This helps when someone posts a
-  patch in the middle of a long thread and you just want that patch and
-  ignore the rest of what is going on.
+  By default, b4 retrieves the entire thread, but sometimes you really
+  just want a single message. This helps when someone posts a patch in
+  the middle of a long thread and you just want that patch and ignore
+  the rest of the messages.
 
 ``-v WANTVER, --use-version WANTVER``
   If a thread (or threads, when used with ``-c``) contains multiple
-  patch series revisions, b4 will automatically pick the highest
-  numbered version. This switch lets you pick a different revision.
+  patch series revisions, b4 automatically picks the highest numbered
+  version. This switch lets you pick a different revision.
 
 ``-S, --sloppy-trailers``
-  B4 tries to be careful when collecting code review trailers and will
-  refuse to consider the trailers where the email address in the From:
-  header does not patch the address in the trailer itself.
+  B4 tries to be careful when collecting code review trailers and
+  refuses to consider the trailers where the email address in the
+  ``From:`` header doesn't match the address in the trailer itself.
 
-  For example, the following message will not be processed::
+  For example, this follow-up trailer doesn't match and b4 ignores it by
+  default::
 
       From: Alice Maintainer <alice@personalemail.org>
       Subject: Re: [PATCH v3 3/3] Some patch title
@@ -103,9 +100,9 @@ The following flags are common to both commands:
       > [...]
       Reviewed-by: Alice Maintainer <alice.maintainer@workemail.com>
 
-  In such situations, b4 will print a warning and refuse to apply the
-  trailer due to the email address mismatch. You can override this by
-  passing the ``-S`` flag.
+  When b4 encounters such situations, it prints a warning and refuses to
+  apply the trailer due to the email address mismatch. You can override
+  this behavior by passing the ``-S`` flag.
 
 ``-T, --no-add-trailers``
   This tells b4 to ignore any follow-up trailers and just save the
@@ -116,47 +113,62 @@ The following flags are common to both commands:
 
 ``-l, --add-link``
   Adds a ``Link:`` trailer with the URL of the retrieved message using
-  the ``linkmask`` template. Note, that such trailers may be considered
-  redundant by the upstream maintainer.
+  the ``linkmask`` template.
 
 ``-P CHERRYPICK, --cherry-pick CHERRYPICK``
   This allows you to select a subset of patches from a larger series.
   Here are a few examples.
 
-  This will pick patches 1, 3, 5, 6, 7, 9 and any others that follow::
+  This picks patches 1, 3, 5, 6, 7, 9, and any others that follow::
 
       b4 am -P 1,3,5-7,9- <msgid>
 
-  This will pick just the patch that matches the exact message-id
+  This picks just the patch that matches the exact message-id
   provided::
 
       b4 am -P _ <msgid>
 
-  This will pick all patches where the subject matches "iscsi"::
+  This picks all patches where the subject matches "iscsi"::
 
       b4 am -P *iscsi*
 
 ``--cc-trailers``
-  Copies all addresses found in the message Cc's into ``Cc:`` commit
-  trailers.
+  Copies all addresses found in the message ``Cc`` headers into ``Cc:``
+  commit trailers.
 
 ``--no-parent``
-  Break thread at the msgid specified and ignore any parent messages.
-  This is handy with very convoluted threads, for example when someone
-  replies with a different patch series in the middle of a larger
-  conversation and b4 gets confused about which patch series is being
-  requested.
+  Break thread at the message-id specified and ignore any parent
+  messages. This is handy with long convoluted threads, for example when
+  someone replies with a different patch series in the middle of a
+  larger conversation and b4 gets confused about which patch series you
+  are requesting.
 
 ``--allow-unicode-control-chars``
-  There are some clever tricks that can be accomplished with unicode
-  control chars that make the code as printed on the screen (and
-  reviewed by a human) to actually do something totally different when
-  processed by a compiler. Such unicode control chars are almost never
-  legitimately useful in the code, so b4 will print a warning and bail
-  out when it finds them. However, just in case there are legitimate
-  reasons for these characters to be in the code (e.g. as part of
-  documentation translated into LTR languages), this behaviour can be
-  overridden.
+  There are malicious tricks that someone can do with unicode control
+  chars that make the code as printed on the screen and reviewed by a
+  human do something totally different when processed by a compiler.
+  Such unicode control chars are almost never legitimately useful in the
+  code, so b4 prints a warning and bails out when it finds them.
+  However, just in case there are legitimate reasons for these
+  characters to be in the code, for example, as part of documentation
+  translated into left-to-right languages), you can override the default
+  behavior with this switch.
+
+``--check`` **(0.14+)**
+  Tells b4 to run a series of local checks on each patch of the series
+  and display any problems. When b4 finds a valid patchwork project
+  definition in the configuration settings, it also looks up the CI
+  status of each patch.
+
+  For the Linux kernel tree, b4 runs the following checkpatch command::
+
+      ./scripts/checkpatch.pl -q --terse --no-summary --mailback
+
+  You can specify a different command to run by setting the
+  ``b4.am-perpatch-check-cmd`` configuration setting, e.g.::
+
+      [b4]
+      am-perpatch-check-cmd = ./scripts/checkpatch.pl -q --terse --no-summary --mailback --strict
 
 Flags only valid for ``b4 am``
 ------------------------------
@@ -168,52 +180,51 @@ The following flags only make sense for ``b4 am``:
   mbox or maildir location to have the results appended to that mailbox
   instead (see also the ``-f`` flag below).
 
-  When ``-`` is specified, the output is dumped to stdout.
+  When ``-`` is specified, the output goes to stdout.
 
 ``-c, --check-newer-revisions``
-  When retrieving patch series, check if a newer revision is available.
-  For example, if you are trying to retrieve a series titled ``[PATCH v2
-  0/3]``, b4 will use a number of mechanisms to check if a ``v3`` or
-  later revision is also available and will add these results to the
-  retrieved thread.
+  When retrieving a patch series, perform a lookup to see if a newer
+  revision is available. For example, if you are trying to retrieve a
+  series titled ``[PATCH v2 0/3]``, b4 tries a number of mechanisms to
+  look up if a ``v3`` or later revision exists and adds these results to
+  the retrieved thread.
 
 ``-n WANTNAME, --mbox-name WANTNAME``
-  By default, the resulting mailbox file will use the message-id as the
+  By default, the resulting mailbox file uses the message-id as the
   basis for its filename. This option lets you override this behaviour.
 
 ``-M, --save-as-maildir``
-  By default, the retrieved thread will be saved as an mbox file.
-  However, due to subtle incompatibilities between various mbox formats
-  ("mboxo" vs "mboxrd", etc), you may want to instead save the results
-  as a Maildir directory.
+  By default, b4 saves the retrieved thread as an mbox file. However,
+  due to subtle incompatibilities between various mbox formats ("mboxo"
+  vs "mboxrd", etc), you may instead want to save the results as a
+  Maildir directory.
 
 ``-Q, --quilt-ready``
-  Saves the patches as a folder that can be fed directly to quilt. If
+  Saves the patches as a folder that you can pass directly to quilt. If
   you don't know what quilt is, you don't really need to worry about
   this option.
 
 ``-b GUESSBRANCH [...], --guess-branch GUESSBRANCH [...]``
-  When using ``--guess-base``, you can restrict which branch(es) b4 will
-  use to find the match. If not specified, b4 will use the entire tree
-  history.
+  When using ``--guess-base``, you can restrict which branch(es) b4 uses
+  to find the match. If not specified, b4 uses the entire tree history.
 
 ``--guess-lookback GUESSDAYS``
   When using ``--guess-base``, you can specify how far back b4 should
   look *from the date of the patch* to find the base commit. By default,
-  b4 will only consider the last 14 days prior to the date of the patch,
-  but you can expand or shrink it as necessary.
+  b4 only considers the last 14 days prior to the date of the patch,
+  but you can expand or shrink this range as necessary.
 
 ``-3, --prep-3way``
-  This will try to prepare your tree for a 3-way merge by doing some
-  behind the scenes git magic and preparing some fake loose commits.
+  This tries to prepare your tree for a 3-way merge by doing some
+  behind-the-scenes git magic and preparing some fake loose commits.
 
 ``--no-cover``
-  By default, b4 will save the cover letter as a separate file in the
-  output directory specified. This flag turns it off (this is also the
-  default when used with ``-o -``).
+  By default, b4 saves the cover letter as a separate file in the output
+  directory specified. This flag turns it off. This is also the default
+  when used with ``-o -``.
 
 ``--no-partial-reroll``
-  For minor changes, it is common practice for contributors to send
+  For minor changes, it's common practice for contributors to send
   follow-ups to just the patches they have modified. For example::
 
       [PATCH v1 1/3] foo: add foo to bar
@@ -221,41 +232,41 @@ The following flags only make sense for ``b4 am``:
        \- [PATCH v2 2/3] bar: add bar to baz
       [PATCH v1 3/3] baz: add baz to quux
 
-  In this case, b4 will properly create a v2 of the entire series by
-  reusing ``[PATCH v1 1/3]`` and ``[PATCH v1 3/3]``. However, sometimes
-  that is not the right thing to do, so you can turn off this feature
-  using ``--no-partial-reroll``.
+  When b4 encounters this situation, it properly creates a v2 of the
+  entire series by reusing ``[PATCH v1 1/3]`` and ``[PATCH v1 3/3]``.
+  However, sometimes that isn't the right thing to do, so you can turn
+  off this feature using ``--no-partial-reroll``.
 
 
 Flags only valid for ``b4 shazam``
 ----------------------------------
-By default, ``b4 shazam`` will apply the patch series directly to the
-git tree where the command is being executed. However, instead of
-just running ``git am`` and applying the patches directly on top of the
-current branch, it can also treat the series similar to a git pull
-request and either prepare a ``FETCH_HEAD`` that you can merge manually,
-or even automatically merge the series using the series cover letter as
-the basis for the merge commit.
+By default, ``b4 shazam`` applies the patch series directly to the
+current git tree and the current branch in the directory where you run
+it. However, instead of just running ``git am`` and applying the patches
+directly, it can also treat the series as if it were a git pull request
+and either prepare a ``FETCH_HEAD`` that you can merge manually, or even
+automatically merge the series using the cover letter as the basis for
+the merge commit.
 
 ``-H, --make-fetch-head``
-  This will prepare the series and place it into the ``FETCH_HEAD`` that
-  can then be merged just as if it were a pull request:
-
-  1. b4 will prepare a temporary sparse worktree
-  2. b4 will apply the series to that worktree
-  3. if ``git am`` completed successfully, b4 will fetch that tree into
-     your current tree's ``FETCH_HEAD`` (and get rid of the temporary
-     tree)
-  4. b4 will place the cover letter into ``.git/b4-cover``
-  5. b4 will offer the command you can run to merge the change into your
+  This prepares the series and places it into the ``FETCH_HEAD`` that
+  you can merge just as if it were a pull request:
+
+  1. b4 prepares a temporary sparse worktree
+  2. b4 applies the series to that worktree
+  3. if ``git am`` completes successfully, b4 fetches that tree into
+     your current tree's ``FETCH_HEAD``, and then gets rid of the
+     temporary tree
+  4. b4 places the cover letter into ``.git/b4-cover``
+  5. b4 suggests the command you can run to merge the change into your
      current branch, e.g.::
 
          git merge --no-ff -F .git/b4-cover --edit FETCH_HEAD --signoff
 
-  Generally, this command is also a good test for "will this patch
-  series apply cleanly to my tree." You can perform any actions with the
-  ``FETCH_HEAD`` as you normally would, e.g. run ``git diff``, make a
-  new branch out of it using ``git checkout``, etc.
+  Generally, this command is also a good test to see if a patch series
+  is going to apply cleanly to a tree. You can perform any actions with
+  the ``FETCH_HEAD`` as you normally would, such as run ``git diff``,
+  make a new branch out of it using ``git checkout``, etc.
 
 ``-M, --merge``
   Exactly the same as ``--make-fetch-head``, but will actually execute
diff --git a/plan.otl b/plan.otl
index 3af5f1a..67b5eaf 100644
--- a/plan.otl
+++ b/plan.otl
@@ -26,7 +26,7 @@ v0.14
 	[X] prep --check-deps
 	[X] Pre-flight checks overview
 	[X] How to turn off pre-flight checks
-	[_] Document config file changes (am-perpatch-check-cmd, prep-perpatch-check-cmd, etc)
+	[X] Document config file changes (am-perpatch-check-cmd, prep-perpatch-check-cmd, etc)
 	[_] Update manpages
 
 v0.15