Configuration options
=====================
B4 doesn't have a separate configuration file but uses
`git-config <https://git-scm.com/docs/git-config#_configuration_file>`__ to
retrieve a set of b4-specific settings. This means that you can have three
levels of b4 configuration:

- system-wide, in ``/etc/gitconfig``
- per-user, in ``$HOME/.gitconfig``
- per-repo, in ``somerepo/.git/config``

Since the purpose of b4 is to work with git repositories, this allows
the usual fall-through configuration, with local settings specified in
``.git/config`` overriding the global defaults.

You can also use the command-line switch ``-c/--config`` to override
specific options, for example::

    b4 --config b4.midmask=https://some.host/%s

Per-project defaults
~~~~~~~~~~~~~~~~~~~~
A project may ship their own b4 configuration file with some defaults,
located at the top-level of the git tree. If you're not sure where a
configuration option is coming from, see if there is a ``.b4-config``
file in the repository you're currently using.

Because a ``.b4-config`` file travels with the repository and may come
from a source you don't fully trust, b4 does **not** honor every setting
found there. Anything that could make b4 silently run a command on your
machine or redirect your outgoing email is ignored -- for example the
mail transport settings (``sendmail`` and any ``smtp*`` option), the
message-id command (``custom-msgid-cmd``), the pre-rewrite hook
(``prep-pre-rewrite-hook``), and the check commands b4 runs against
patches you received from others (``am-*-check-cmd`` and
``review-*-check-cmd``). The review check commands are excluded because
``b4 review`` applies the series under review into your working tree, so
its ``.b4-config`` -- and any command it names -- would otherwise be
under the control of whoever sent the series.

Only the settings below are accepted from ``.b4-config``; every other
configuration source (such as ``~/.gitconfig`` and ``.git/config``) is
unrestricted:

- ``prep-*-check-cmd`` -- the check commands run by ``b4 prep --check``
  on the series you are preparing yourself
- ``prep-pre-flight-checks`` -- which pre-flight checks are enabled
- ``send-*`` -- recipient and addressing options, such as
  ``send-series-to``, ``send-series-cc``, ``send-auto-to-cmd`` and
  ``send-auto-cc-cmd``
- ``*mask`` -- URL templates such as ``midmask`` and ``linkmask``
- ``*template*`` -- message templates
- ``trailer*`` -- trailer-handling options
- ``pw-*`` -- Patchwork integration options

The ``prep`` check and recipient-discovery commands are allowed because
they only run when you explicitly invoke a check or ``--auto-to-cc`` on a
series you are preparing yourself -- never on content you received from
someone else.

Configuration options
---------------------
All settings are under the ``b4`` section. For example, to set the
:term:`b4.midmask` option, add the following section to the relevant git
config file::

    [b4]
      midmask = https://some.host/%s

Core options
~~~~~~~~~~~~
These options control many of the core features of b4.

.. glossary::
   :sorted:

   :term:`b4.cache-expire`
     B4 caches retrieved threads for 10 minutes. This option allows
     tweaking the time that the cache remains valid. Many commands also
     allow a ``--no-cache`` flag to force b4 to perform remote lookups.

     Default: ``10``

   :term:`b4.linkmask`
     B4 uses this setting to construct the URL in the ``Link:`` trailers.
     If you want a shorter option, you can also use
     ``https://msgid.link/%s``, which is an alias for lore.kernel.org.

     Default: ``https://lore.kernel.org/%s``

   :term:`b4.linktrailermask`
     Overrides the format of the ``Link:`` trailer, in case you want to
     call it something other than "Link". For example, some projects
     use "Message-ID" trailers instead::

         linktrailermask = Message-ID: <%s>

     The ``%s`` is the placeholder for the message-id.

     Default: ``Link: https://lore.kernel.org/%s``

     .. versionadded:: v0.13

     .. versionchanged:: v0.14
        You can now pass the ``-i`` command-line switch instead of ``-l`` to
        automatically insert the ``Message-ID`` trailer.

   :term:`b4.listid-preference`
     Sometimes messages with the same message-id can have different
     contents, because some servers modify message bodies to inject list
     subscription information. B4 attempts to de-duplicate the results
     using the ``List-Id`` header. You may use this parameter to specify
     the order of preference, using comma-separated strings with shell-style
     wildcard globbing.

     Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``

   :term:`b4.midmask`
     Specifies the server from where to retrieve the messages specified by
     their message-id.

     Default: ``https://lore.kernel.org/%s``

   :term:`b4.save-maildirs`
     The "mbox" file format is actually several incompatible standards,
     such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
     problems by saving retrieved threads as Maildirs.

     Default: ``no``

   :term:`b4.searchmask`
     B4 uses this setting to query and retrieve threads matching specific
     search terms. For example, it can retrieve trailer updates using the
     series ``change-id`` identifier.

     Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``

   :term:`b4.trailer-order`
     This lets you control the order of trailers that get added to your own
     custody section of the commit message. By default, b4 applies these
     trailers in the order received. However, if you want to list trailers
     in a specific order, you can try something like::

         trailer-order = link*,fixes*,acked*,reviewed*,tested*,*

     The "chain of custody" is an important concept in patch-based code
     review process. Each "Signed-off-by" trailer indicates where the
     custody section of previous reviewer ends and the new one starts. Your
     own custody section is always between the previous-to-last
     "Signed-off-by" trailer, if any, and the bottom of the trailer
     section. For example::

         Fixes: abcde (Commit info)
         Suggested-by: Alex Reporter <alex.reporter@example.com>
         Signed-off-by: Betty Developer <betty.developer@example.com>
         Acked-by: Chandra Acker <chandra.acker@example.com>
         Reviewed-by: Debby Reviewer <debby.reviewer@example.com>
         Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com>
         Link: https://msgid.link/some@thing.foo
         Tested-by: Finn Tester <finn.tester@example.com>
         Signed-off-by: Your Name <your.name@example.com>

     Your custody section is beneath "Ezri Submaintainer," so the only
     trailers considered for reordering are "Link" and "Tested-by". Your
     own Signed-off-by trailer is always at the bottom of your own custody
     section.

     Default: ``*``

   :term:`b4.trailers-ignore-from`
     A comma-separated list of addresses that b4 should always ignore
     when applying follow-up trailers. This is useful when dealing with
     reports generated by some automated bots. For example::

         trailers-ignore-from = lkp@intel.com, someotherbot@example.org

     Default: ``None``

.. _lore_settings:

Server failover settings
~~~~~~~~~~~~~~~~~~~~~~~~
B4 uses the `liblore <https://git.kernel.org/pub/scm/utils/liblore/liblore.git>`_
library for all access to public-inbox servers.  Liblore reads its own
settings from the ``[lore]`` section of git config (not ``[b4]``).  These
settings are shared by all tools that use liblore, so configuring them
once benefits b4 and any other liblore-based applications.

When one or more fallback origins are configured, liblore automatically
retries a request on the next origin whenever a connection error,
timeout, or HTTP 5xx response occurs.  HTTP 4xx errors are **not**
retried, since they indicate a missing resource rather than a server
problem.  Cache keys always use the canonical URL regardless of which
mirror actually served the response.

Example ``~/.gitconfig``::

    [lore]
        fallback = https://tor.lore.kernel.org
        fallback = https://sea.lore.kernel.org
        autoprobe = true
        useragentplus = 550e8400-e29b-41d4-a716-446655440000

.. glossary::
   :sorted:

   :term:`lore.fallback`
     Origin URL prefix (``scheme://host``) of a mirror to try when the
     primary server is unreachable or returns a server error.  This
     option can be specified multiple times; mirrors are tried in the
     order listed before falling back to the canonical server.  Only
     the origin (scheme and host) is used — the path from the primary
     URL is preserved automatically.

     Example::

         [lore]
             fallback = https://tor.lore.kernel.org
             fallback = http://mymirror.local

     Default: ``None``

     .. versionadded:: v0.16

   :term:`lore.autoprobe`
     When set to ``true``, b4 probes all configured origins on the
     first HTTP request and reorders them by response latency, putting
     the fastest mirror first.  Probe results are cached to disk for
     :term:`lore.probettl` seconds so that subsequent runs are fast.
     Probing only makes sense when at least one :term:`lore.fallback`
     is configured.

     Default: ``false``

     .. versionadded:: v0.16

   :term:`lore.probetimeout`
     Per-origin timeout in seconds for latency probes.  Origins that
     do not respond within this time are treated as unreachable and
     moved to the end of the list.

     Default: ``5.0``

     .. versionadded:: v0.16

   :term:`lore.probettl`
     How long probe results stay valid, in seconds.  After this time
     the cached results expire and the next request that triggers a
     probe performs a fresh measurement.

     Default: ``3600``

     .. versionadded:: v0.16

   :term:`lore.requesttimeout`
     Per-request HTTP timeout in seconds.  Accepts a single float
     (applied to both the connect and read phase) or a
     ``connect,read`` pair for separate timeouts.  Lower the read
     value if you want faster failover to a mirror on slow connections;
     raise it if your network is consistently slow but eventually
     succeeds.  Set to ``0`` to disable the timeout entirely (not
     recommended — a stalled connection will hang indefinitely).

     Example::

         [lore]
             requesttimeout = 5,60

     Default: ``5.0,30.0`` (5 s connect, 30 s read)

     .. versionadded:: v0.16

   :term:`lore.useragentplus`
     A unique identifier appended to the ``User-Agent`` header as
     ``b4/version+IDENTIFIER``.  This allows server operators to
     identify and prioritize known installations.  Typically a UUID.

     Example::

         [lore]
             useragentplus = 550e8400-e29b-41d4-a716-446655440000

     Default: ``None``

     .. versionadded:: v0.16

.. _shazam_settings:

``am`` and ``shazam`` settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These settings control ``b4 am`` and ``b4 shazam`` behavior.

.. glossary::
   :sorted:

   :term:`b4.am-perpatch-check-cmd`
     The command to use when running ``--check``. The command is run once for each
     patch to check. The patch file to check is piped through stdin. If this
     config is defined multiple times, all commands will be run. If this config is
     not defined and 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``

     .. versionadded:: v0.14

   :term:`b4.shazam-am-flags`
     Additional flags to pass to ``git am`` when applying patches.

     Default: ``None``

   :term:`b4.shazam-merge-flags`
     Additional flags to pass to ``git merge`` when performing a merge with
     ``b4 shazam -M``.

     Default: ``--signoff``

   :term:`b4.shazam-merge-template`
     Path to a template to use when creating a merge commit. Take the following
     as example content for this file:

     .. literalinclude:: ../src/b4/templates/shazam-merge-template.example

     Default: ``None``

.. _attestation_settings:

Attestation settings
~~~~~~~~~~~~~~~~~~~~

.. glossary::
   :sorted:

   :term:`b4.attestation-check-dkim`
     Controls whether to perform DKIM attestation checks.

     Default: ``yes``

   :term:`b4.attestation-dns-resolvers`
     You can specify your own DNS servers if you are on a company network
     and your OS-provided resolvers aren't able to perform domain key
     lookups. For example, to use Google DNS servers::

         attestation-dns-resolvers = 8.8.8.8, 8.8.4.4

     Default: ``None``

     .. versionadded:: v0.14

   :term:`b4.attestation-gnupghome`
     Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
     GnuPG.

     Default: ``None``

   :term:`b4.attestation-policy`
     B4 supports domain-level and end-to-end attestation of patches using
     the `patatt`_ library. There are four different operation modes:

     * ``off``: don't bother checking attestation at all
     * ``softfail``: print green marks when attestation is passing and
       red marks when it's failing
     * ``hardfail``: exit with an error when any attestation checks fail

     Default: ``softfail``

   :term:`b4.attestation-staleness-days`
     Ignore attestation signatures that are more than this many days
     old. This helps avoid a class of attacks when someone re-sends old
     patches that contain known security bugs.

     Default: ``30``

   :term:`b4.gpgbin`
     Full path to a different binary to use for ``gpg``. B4 also checks the
     ``gpg.program`` setting, and uses that value, if found.

     Default: ``None``

   :term:`b4.keyringsrc`
     See `patatt`_ for details on how to configure keyrings. For example,
     you can clone the kernel.org pgp keys repository and use it for
     attestation::

         git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git

     Then set the following in your ``~/.gitconfig``::

         [b4]
           keyringsrc = ~/path/to/pgpkeys/.keyring

     Default: ``None``

.. _ty_settings:

``ty`` settings
~~~~~~~~~~~~~~~

.. glossary::
   :sorted:

   :term:`b4.email-exclude`
     A list of addresses to always exclude from the message recipients.
     Expects a comma-separated list with shell-style globbing. E.g.::

         email-exclude = *@codeaurora.org, *@obsolete.example.com

     Default: ``None``

   :term:`b4.sendemail-identity`
     The ``sendemail`` identity to use when sending mail directly with b4.
     This setting applies to ``b4 send`` and ``b4 ty``. See `man
     git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
     sendemail identities.

     Default: ``None``

   :term:`b4.thanks-am-template`
     Full paths to the templates to use when generating thank-you messages
     for contributors. Take the following as example content for this file:

     .. literalinclude:: ../src/b4/templates/thanks-am-template.example

     Default: ``None``

   :term:`b4.thanks-check-repo`
     The git URL of the public repository that queued thank-you messages
     are checked against before delivery. When processing the queue, b4
     runs ``git ls-remote`` against this repository and only delivers a
     thank-you once its commit is reachable from one of the advertised
     branches. For example::

         thanks-check-repo = https://git.kernel.org/pub/scm/linux/kernel/git/username/tree.git

     If not set, b4 uses the URL of the remote that the target branch
     tracks — the same remote the "Applied to" line in the thank-you
     message refers to, so having the commit reachable there is what
     qualifies as pushed. As a last resort, b4 attempts to derive the
     repository URL from the :term:`b4.thanks-commit-url-mask` value,
     which works for cgit-, github- and gitlab-style commit URLs, but
     not for the git.kernel.org ``/username/c/`` short URLs.

     If you push to multiple trees from the same repository, you can
     set this per-remote instead, which takes precedence over
     everything else::

         [remote "spi"]
             b4-check-repo = https://git.kernel.org/pub/scm/linux/kernel/git/username/spi.git

     See :ref:`queuing thanks <thanks_queue>` for details.

     Default: ``None``

   :term:`b4.thanks-commit-url-mask`
     Used when creating summaries for ``b4 ty`` and the review TUI
     thank-you flow. Can be a value like::

         thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s

     If not set, b4 falls back to using commit hashes.

     When this option is set, the review TUI's thank-you preview offers
     a **Queue** option that stores the message for delayed delivery.
     Queued messages are held until their commit is verified published,
     so you can push your commits before the thank-you is sent.
     See :ref:`queuing thanks <thanks_queue>` for details.

     .. note::

        See this page for more info on convenient git.kernel.org short URLs:
        https://korg.docs.kernel.org/git-url-shorteners.html

     Default: ``None``

   :term:`b4.thanks-from-email`
     The email to use in the ``From:`` header when sending thank-you notes.
     By default, b4 uses ``user.email``. For example::

         thanks-from-email = thanks-bot@example.com

     Default: ``None``

     .. versionadded:: v0.13

   :term:`b4.thanks-from-name`
     The name to use in the ``From:`` header when sending thank-you notes.
     By default, b4 uses ``user.name``. For example::

         thanks-from-name = Project Foo Thanks Bot

     Default: ``None``

     .. versionadded:: v0.13

   :term:`b4.thanks-pr-template`
     Full paths to the templates to use when generating thank-you messages
     for contributors. Take the following as example content for this file:

     .. literalinclude:: ../src/b4/templates/thanks-pr-template.example

     Default: ``None``

   :term:`b4.thanks-treename`
     Name of the tree to use in the thank-you templates.

     Default: ``None``

   :term:`b4.ty-send-email`
     When set, tells ``b4 ty`` to send email directly instead of writing
     out ``.thanks`` files.

     Default: ``no``

     .. versionadded:: v0.11

.. _review_settings:

``review`` settings (alpha)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
These settings control ``b4 review`` TUI behaviour.

.. warning::

   ``b4 review`` is a **technology preview**. These configuration options may
   change in incompatible ways between releases.

.. glossary::
   :sorted:

   :term:`b4.review-default-take-method`
     The default take method to pre-select in the Take dialog. Valid
     values are ``merge``, ``linear``, and ``cherry-pick``. If not set,
     b4 picks the default heuristically: ``merge`` for multi-patch
     series with a cover letter, and ``linear`` for single-patch series
     or series where the author provided no cover letter (a merge
     commit's message comes from the cover letter, so there is nothing
     to build it from). Setting this option overrides the heuristic.

     Default: ``None`` (heuristic)

     .. versionadded:: v0.15

     .. versionchanged:: v0.16
        Series without a cover letter now default to ``linear``.

   :term:`b4.review-thank-and-archive`
     When ``yes``, the *thank and archive on delivery* checkbox in the
     Take dialog starts checked, so a fully accepted take chains
     straight into the thank-you flow and the series is archived
     automatically once the thank-you message is actually delivered
     (immediately for a direct send, or when the queued message goes
     out). The checkbox can still be toggled per take. See
     :ref:`thank and archive in one motion <review_take_thank_archive>`.

     Default: ``no``

     .. versionadded:: v0.16

   :term:`b4.review-perpatch-check-cmd`
     Command to run once per patch when CI checks are triggered (``c`` in
     the tracking list). Each patch is piped to stdin as an RFC 2822
     message. The command must print a JSON array of result objects to
     stdout (see :ref:`ci_check_protocol`). If this option is defined
     multiple times, all commands are run. If it is not defined and b4
     finds ``scripts/checkpatch.pl`` at the top of your git tree,
     ``checkpatch.pl`` is used automatically. When Patchwork is
     configured (:term:`b4.pw-url` and :term:`b4.pw-project`), Patchwork
     CI results are also fetched automatically.

     The special value ``_builtin_checkpatch`` invokes the built-in
     checkpatch handler without forking a subprocess.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.review-series-check-cmd`
     Command to run once per series when CI checks are triggered (``c``
     in the tracking list). The cover letter (or first patch if there is
     no cover) is piped to stdin as an RFC 2822 message. Same JSON
     protocol as :term:`b4.review-perpatch-check-cmd`. If defined
     multiple times, all commands are run.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.review-target-branch`
     The default *destination* branch for taking patches — the branch a
     take lands on once you accept a series. This is also used in the
     notification shown when the TUI is launched from a review branch,
     to tell you which branch to switch to for the tracking list. If
     not set, b4 falls back to ``master`` or ``main``.

     This option supports multiple values. When multiple branches are
     configured (e.g. ``sound/for-next`` and ``regulator/for-next``),
     all of them appear in the suggestion list for the take dialog and
     the ``t`` keybinding in the tracking TUI. When exactly one value
     is configured, it is used as the automatic default; when two or
     more are configured, the per-series target (set via ``t``) takes
     priority instead.

     Note that this option does not choose the *base* the series is
     applied on when starting a review — use
     :term:`b4.review-apply-base` for that.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.review-apply-base`
     The base commit to pre-fill in the base selection dialog shown
     when starting a review or upgrading a tracked series to a newer
     revision. Accepts anything that resolves to a commit — ``HEAD``,
     a branch name, a tag, or a SHA::

         git config b4.review-apply-base HEAD

     When set and resolvable, this value takes priority over the base
     specified by the series itself and over b4's own guess; what b4
     would have picked automatically is still shown in the dialog
     hint, so no information is lost. When the configured value does
     not resolve to a commit in the repository, b4 warns in the hint
     and falls back to the automatic detection.

     This only controls the pre-filled suggestion — the dialog input
     remains editable and the base is validated when you confirm.

     Default: ``None``

     .. versionadded:: v0.16

   :term:`b4.review-reply-template`
     Path to a template file used to wrap outgoing review replies sent
     from the review TUI (both per-patch replies and the cover-letter
     reply). The template must contain the ``${reply}`` placeholder,
     which expands to the reply content itself — the quoted patch
     context, your comments, and any trailers. Substitution follows
     the same rules as the ``b4 ty`` thank-you templates
     (``string.Template`` syntax; lines starting with ``#`` are
     removed). Available placeholders: ``${reply}``, ``${fromname}``,
     ``${firstname}``, ``${fromemail}``, ``${subject}``,
     ``${sentdate}``, ``${msgid}``, ``${myname}``, ``${myemail}``,
     ``${signature}``. See ``review-reply-template.example`` shipped
     with b4 for a commented starting point.

     If the rendered reply does not already contain a signature
     delimiter (``-- `` on its own line), your email signature is
     still appended automatically, so most templates do not need
     ``${signature}``.

     Default: ``None``

     .. versionadded:: v0.16

   :term:`b4.review-no-patatt-sign`
     Instructs b4 not to patatt-sign outgoing review emails (review replies,
     follow-up replies, and thank-you messages). This mirrors the
     :term:`b4.send-no-patatt-sign` option for ``b4 send``. Can also be
     set per-session with the ``--no-sign`` flag on ``b4 review tui``.

     Default: ``no``

     .. versionadded:: v0.15

   :term:`b4.custom-msgid-cmd`
     Command whose stdout is used as the Message-Id for outgoing replies
     and notifications: review replies and follow-up replies (sent over
     SMTP from the review TUI, bypassing any ``sendemail-validate`` hook),
     and ``b4 ty`` thank-you notes. The surrounding angle brackets are
     optional. If the command is unset, produces no output, or fails, b4
     falls back to its built-in ``<...@b4>`` id::

         git config b4.custom-msgid-cmd ~/bin/my-msgid.py

     The command runs once per message, so it must emit a *unique* id each
     time, or threading will break. Patch series sent with
     ``b4 prep``/``b4 send`` are **not** affected -- they keep their own
     templated message-ids -- and neither do synthetic ``b4 pr`` GIT PULL
     messages, whose ids are deliberately derived from the pull request.

     Default: ``None``

     .. versionadded:: v0.16

   :term:`b4.review-tui-disable-mouse`
     Disable mouse support in the review TUI. When set, the terminal's
     native text selection works normally instead of being captured by the
     TUI. Can also be set per-session with ``--no-mouse`` on
     ``b4 review tui``.

     Default: ``no``

     .. versionadded:: v0.15

   :term:`b4.review-agent-command`
     The command to invoke for AI-assisted review (triggered by the ``a``
     keybinding). Both this option and :term:`b4.review-agent-prompt-path`
     must be set for the agent feature to be available.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.review-agent-prompt-path`
     Path to a file containing the prompt to use with the review agent.
     Both this option and :term:`b4.review-agent-command` must be set for
     the agent feature to be available. A sample prompt is included in
     ``misc/agent-reviewer.md`` in the b4 source tree and can be adapted
     to your project's review guidelines.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.sashiko-url`
     Base URL of a `sashiko.dev <https://sashiko.dev>`_ instance to use
     for AI-powered code review. When set, b4 automatically queries the
     sashiko API for review findings as part of CI checks and integrates
     sashiko inline review comments into the diff view. Inline comments
     appear attributed to ``sashiko.dev`` with a provenance link back to
     the sashiko web interface.

     Example::

         sashiko-url = https://sashiko.dev

     Default: ``None``

     .. versionadded:: v0.15

.. _patchwork_settings:

Patchwork integration settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your project uses a patchwork server, setting these allows you to
integrate your b4 workflow with patchwork.

.. glossary::
   :sorted:

   :term:`b4.pw-accept-state`
     Enabling this option makes ``b4 ty`` set the status of any applied patches
     to the specified state. For example::

         pw-accept-state = accepted

     Default: ``None``

   :term:`b4.pw-discard-state`
     Enabling this option makes ``b4 ty -d`` set the status of any matching
     patches to the specified state. For example::

         pw-discard-state = rejected

     Default: ``None``

   :term:`b4.pw-key`
     The API key from your user profile to use when authenticating with the
     patchwork server.

     Default: ``None``

   :term:`b4.pw-project`
     The name of the patchwork project, exactly as seen in the URL
     sub-path. For example::

         pw-project = linux-usb

     Default: ``None``

   :term:`b4.pw-review-state`
     Enabling this option makes ``b4 am`` or ``b4 shazam`` automatically set
     the review status of the retrieved patches. For example::

         pw-review-state = under-review

     Default: ``None``

   :term:`b4.pw-url`
     The URL of your patchwork server. Note, that this should point at the
     top-level of your patchwork installation and **not** at the project patch
     listing. For example::

         pw-url = https://patchwork.kernel.org/

     Default: ``None``

.. _contributor_settings:

Contributor-oriented settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. glossary::
   :sorted:

   :term:`b4.prep-cover-strategy`
     Alternative cover letter storage strategy to use, in case you don't
     want to use the default ``commit`` strategy. See
     :ref:`prep_cover_strategies`.

     Default: ``commit``

   :term:`b4.prep-cover-template`
     Path to the template to use for the cover letter. The template supports the
     following tokens:

     * ``${cover}``: the content of the cover letter itself
     * ``${shortlog}``: the ``git shortlog`` output for the series
     * ``${diffstat}``: the ``git diff --stat`` output for the series
     * ``${range_diff}``: the ``git range-diff`` output against the previous revision of the series
     * ``${base_commit}``: the base commit of the series
     * ``${change_id}``: the change-id of the series
     * ``${signature}``: your signature, either from ``~/.signature`` if found, or from your Git config

     Default: ``None``

   :term:`b4.prep-perpatch-check-cmd`
     The command to use when running ``--check``. The command is run once for each
     patch to check. The patch file to check is piped through stdin. If this
     config is defined multiple times, all commands will be run. If this config is
     not defined and 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``

     .. versionadded:: v0.14

   :term:`b4.prep-pre-flight-checks`
     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

     This setting may also be shipped in a project's ``.b4-config`` so the
     decision is shared with all contributors.

     .. versionadded:: v0.14

   :term:`b4.prep-pre-rewrite-hook`
     A command to run before any operation that rewrites history on a prep
     branch (e.g. updating the cover letter, applying trailers, or enrolling
     with the ``commit`` strategy).  If the command exits with a non-zero
     status, the operation is aborted.  This is useful for tools like Stacked
     Git that maintain their own branch state::

         [b4]
         prep-pre-rewrite-hook = stg commit --all

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.prep-post-rewrite-hook`
     A command to run after a successful history rewrite on a prep branch.  A
     non-zero exit status is logged as a warning but does not undo the
     rewrite::

         [b4]
         prep-post-rewrite-hook = stg repair

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.send-auto-cc-cmd`
     The command to use for obtaining the list of "Cc:" recipients. The command is
     run once for each patch in the series. Each patch file is piped through
     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
     it uses the command shown below by default.

     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``

   :term:`b4.send-auto-to-cmd`
     The command to use for obtaining the list of "To:" recipients. The command is
     run once for each patch in the series. Each patch file is piped through
     stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
     it uses the command shown below by default.

     Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``

   :term:`b4.send-endpoint-web`
     The web submission endpoint to use. See :ref:`web_endpoint`.

     Default: ``None``

   :term:`b4.send-no-patatt-sign`
     Instructs b4 not to sign patches with patatt before sending them. Note, that
     using the web submission endpoint requires using signed patches.

     Default: ``no``

   :term:`b4.send-me-too`
     Instructs b4 to include your own address when sending. Set by default,
     use ``no`` to suppress sending to yourself.

     Default: ``yes``

     .. versionadded:: v0.16

   :term:`b4.send-prefixes`
     Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).

     This setting can be replaced for a series with ``b4 prep --set-prefixes``.

     Default: ``None``

     .. versionadded:: v0.11

   :term:`b4.send-presubject`
     Identifiers to include before ``[PATCH]``. These **must** be enclosed
     with brackets. For example::

         [b4]
         send-presubject = "[myproject]"

     This setting can be replaced for a series with ``b4 prep --set-presubject``.

     Default: ``None``

     .. versionadded:: v0.15

   :term:`b4.send-same-thread`
     When sending a new version of a series, send it in the same thread as
     the previous version. The config supports the following values:

     * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
       reply to the previous version's cover letter.
     * ``shallow``: B4 sends the first message of the new series as a reply to the
       first version's cover letter.
     * ``no``: B4 does not send the new version of the series in the same thread
       as any previous version.

     Default: ``no``

     .. versionadded:: v0.13

     .. versionchanged:: v0.15
        Added ``shallow`` config value.

   :term:`b4.send-series-cc`
     A comma-separated list of addresses to always add to the "Cc:" header.
     See :ref:`prep_recipients`.

     Default: ``None``

   :term:`b4.send-series-to`
     A comma-separated list of addresses to always add to the "To:" header.
     See :ref:`prep_recipients`.

     Default: ``None``

To document
-----------

.. glossary::
   :sorted:

   :term:`b4.gh-api-key`
     Deliberately undocumented because the feature is incomplete and poorly
     tested.

.. _`patatt`: https://pypi.org/project/patatt/
