diff options
Diffstat (limited to 'man/b4.5.rst')
| -rw-r--r-- | man/b4.5.rst | 211 |
1 files changed, 157 insertions, 54 deletions
diff --git a/man/b4.5.rst b/man/b4.5.rst index 997b947..6df33bd 100644 --- a/man/b4.5.rst +++ b/man/b4.5.rst @@ -5,15 +5,15 @@ Work with code submissions in a public-inbox archive ---------------------------------------------------- :Author: mricon@kernel.org -:Date: 2020-11-20 +:Date: 2022-06-16 :Copyright: The Linux Foundation and contributors :License: GPLv2+ -:Version: 0.7.0 +:Version: 0.9.0 :Manual section: 5 SYNOPSIS -------- -b4 {mbox,am,attest,pr,ty,diff} [options] +b4 {mbox,am,shazam,pr,diff,ty,kr} [options] DESCRIPTION ----------- @@ -27,74 +27,103 @@ precursor to Lore and Data in the Star Trek universe. SUBCOMMANDS ----------- -* *b4 mbox*: Download a thread as an mbox file -* *b4 am*: Create an mbox file that is ready to git-am -* *b4 pr*: Work with pull requests -* *b4 diff*: Show range-diff style diffs between patch versions -* *b4 ty*: Create templated replies for processed patches and pull requests -* *b4 attest*: (EXPERIMENTAL) Add cryptographic attestation to patches -* *b4 kr* (EXPERIMENTAL) Operate on patatt-compatible keyrings +* *mbox*: Download a thread as an mbox file +* *am*: Create an mbox file that is ready to git-am +* *shazam*: Apply patch series to git repositories +* *pr*: Work with pull requests +* *diff*: Show range-diff style diffs between patch versions +* *ty*: Create templated replies for processed patches and pull requests +* *kr* (EXPERIMENTAL) Operate on patatt-compatible keyrings OPTIONS ------- -h, --help show this help message and exit -d, --debug Add more debugging info to the output (default: False) -q, --quiet Output critical information only (default: False) +-n, --no-interactive Do not ask any interactive questions (default: False) SUBCOMMAND OPTIONS ------------------ + b4 mbox ~~~~~~~ + +This command allows retrieving entire threads from a remote public-inbox +instance. The resulting mbox file can then be opened with most MUA +clients for actions like replying to conversations or reviewing patch +submissions. + usage: - b4 mbox [-h] [-o OUTDIR] [-p USEPROJECT] [-c] [-n WANTNAME] [-m LOCALMBOX] [msgid] + b4 mbox [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c] [-n WANTNAME] [-M] [-f] [msgid] positional arguments: msgid Message ID to process, or pipe a raw message -optional arguments: +options: -h, --help show this help message and exit + -p USEPROJECT, --use-project USEPROJECT + Use a specific project instead of default (linux-mm, linux-hardening, etc) + -m LOCALMBOX, --use-local-mbox LOCALMBOX + Instead of grabbing a thread from lore, process this mbox file (or - for stdin) + -C, --no-cache + Do not use local cache -o OUTDIR, --outdir OUTDIR Output into this directory (or use - to output mailbox contents to stdout) - -p USEPROJECT, --use-project USEPROJECT - Use a specific project instead of guessing (linux-mm, linux-hardening, etc) -c, --check-newer-revisions Check if newer patch revisions exist -n WANTNAME, --mbox-name WANTNAME - Filename to name the mbox file - -m LOCALMBOX, --use-local-mbox LOCALMBOX - Instead of grabbing a thread from lore, process this mbox file - (or use - for stdin) - -C, --no-cache Do not use local cache - -f, --filter-dupes When adding messages to existing maildir, filter out duplicates + Filename to name the mbox destination -M, --save-as-maildir Save as maildir (avoids mbox format ambiguities) + -f, --filter-dupes + When adding messages to existing maildir, filter out duplicates + *Example*: b4 mbox 20200313231252.64999-1-keescook@chromium.org b4 am ~~~~~ + +This command allows retrieving threads from a public-inbox instance and +preparing them for applying to a git repository using the "git am" +command. It will automatically perform the following operations: + +* pick the latest submitted version of the series (it can check for + newer threads using ``-c`` as well) +* check DKIM signatures and patatt attestation on all patches and code + review messages +* collate all submitted code-review trailers (Reviewed-by, Acked-by, + etc) and put them into the commit message +* add your own Signed-off-by trailer (with ``-s``) +* reroll series from partial updates (e.g. someone submits a v2 of a + single patch instead of rerolling the entire series) +* guess where in the tree history the patches belong, if the exact + commit-base is not specified (with ``-g``) +* prepare the tree for a 3-way merge (with ``-3``) +* cherry-pick a subset of patches from a large series (with ``-P``) + usage: - b4 am [-h] [-o OUTDIR] [-p USEPROJECT] [-c] [-n WANTNAME] [-m LOCALMBOX] [-v WANTVER] [-t] [-T] [-s] [-l] [-Q] [msgid] + b4 am [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-o OUTDIR] [-c] [-n WANTNAME] [-M] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-control-chars] [-Q] [-g] [-b GUESSBRANCH [GUESSBRANCH ...]] [--guess-lookback GUESSDAYS] [-3] [--no-cover] [--no-partial-reroll] [msgid] positional arguments: msgid Message ID to process, or pipe a raw message -optional arguments: +options: -h, --help show this help message and exit + -p USEPROJECT, --use-project USEPROJECT + Use a specific project instead of default (linux-mm, linux-hardening, etc) + -m LOCALMBOX, --use-local-mbox LOCALMBOX + Instead of grabbing a thread from lore, process this mbox file (or - for stdin) + -C, --no-cache + Do not use local cache -o OUTDIR, --outdir OUTDIR Output into this directory (or use - to output mailbox contents to stdout) - -p USEPROJECT, --use-project USEPROJECT - Use a specific project instead of guessing (linux-mm, linux-hardening, etc) -c, --check-newer-revisions Check if newer patch revisions exist -n WANTNAME, --mbox-name WANTNAME - Filename to name the mbox file - -m LOCALMBOX, --use-local-mbox LOCALMBOX - Instead of grabbing a thread from lore, process this mbox file - (or use - for stdin) + Filename to name the mbox destination -M, --save-as-maildir Save as maildir (avoids mbox format ambiguities) - -C, --no-cache Do not use local cache -v WANTVER, --use-version WANTVER Get a specific version of the patch/series -t, --apply-cover-trailers @@ -103,36 +132,92 @@ optional arguments: Apply trailers without email address match checking -T, --no-add-trailers Do not add or sort any trailers - -s, --add-my-sob Add your own signed-off-by to every patch - -l, --add-link Add a lore.kernel.org/r/ link to every patch - -Q, --quilt-ready Save patches in a quilt-ready folder + -s, --add-my-sob + Add your own signed-off-by to every patch + -l, --add-link + Add a Link: with message-id lookup URL to every patch -P CHERRYPICK, --cherry-pick CHERRYPICK - Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P _" to use just the msgid specified, or "-P \*globbing\*" to match on commit subject) + Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P _" to use just the msgid specified, or "-P *globbing*" to match on commit subject) + --cc-trailers + Copy all Cc'd addresses into Cc: trailers + --no-parent + Break thread at the msgid specified and ignore any parent messages + --allow-unicode-control-chars + Allow unicode control characters (very rarely legitimate) + -Q, --quilt-ready + Save patches in a quilt-ready folder -g, --guess-base Try to guess the base of the series (if not specified) + + -b GUESSBRANCH [GUESSBRANCH ...], --guess-branch GUESSBRANCH [GUESSBRANCH ...] + When guessing base, restrict to this branch (use with -g) + + --guess-lookback GUESSDAYS + When guessing base, go back this many days from the patch date (default: 2 weeks) -3, --prep-3way Prepare for a 3-way merge (tries to ensure that all index blobs exist by making a fake commit range) - --cc-trailers - Copy all Cc'd addresses into Cc: trailers, if not already present --no-cover Do not save the cover letter (on by default when using -o -) --no-partial-reroll Do not reroll partial series when detected - *Example*: b4 am 20200313231252.64999-1-keescook@chromium.org -b4 attest +b4 shazam ~~~~~~~~~ -usage: b4 attest [-h] patchfile [patchfile ...] + +This is very similar to **b4 am**, but will also apply patches +directly to the current git tree using ``git am``. Alternatively, when +used with ``-H``, it can fetch the patch series into ``FETCH_HEAD`` as +if it were a pull request, so it can be reviewed and merged. In this +case, the cover letter is used as a template for the merge commit. + +If you want to automatically invoke git-merge, you can use ``-M`` +instead of ``-H``. + +usage: + b4 shazam [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [-v WANTVER] [-t] [-S] [-T] [-s] [-l] [-P CHERRYPICK] [--cc-trailers] [--no-parent] [--allow-unicode-control-chars] [-H | -M] [--guess-lookback GUESSDAYS] [msgid] positional arguments: - patchfile Patches to attest + msgid Message ID to process, or pipe a raw message -*Example*: b4 attest outgoing/\*.patch +options: + -h, --help show this help message and exit + -p USEPROJECT, --use-project USEPROJECT + Use a specific project instead of default (linux-mm, linux-hardening, etc) + -m LOCALMBOX, --use-local-mbox LOCALMBOX + Instead of grabbing a thread from lore, process this mbox file (or - for stdin) + -C, --no-cache Do not use local cache + -v WANTVER, --use-version WANTVER + Get a specific version of the patch/series + -t, --apply-cover-trailers + Apply trailers sent to the cover letter to all patches + -S, --sloppy-trailers + Apply trailers without email address match checking + -T, --no-add-trailers + Do not add or sort any trailers + -s, --add-my-sob Add your own signed-off-by to every patch + -l, --add-link Add a Link: with message-id lookup URL to every patch + -P CHERRYPICK, --cherry-pick CHERRYPICK + Cherry-pick a subset of patches (e.g. "-P 1-2,4,6-", "-P _" to use just the msgid specified, or "-P *globbing*" to match on commit subject) + --cc-trailers Copy all Cc'd addresses into Cc: trailers + --no-parent Break thread at the msgid specified and ignore any parent messages + --allow-unicode-control-chars + Allow unicode control characters (very rarely legitimate) + -H, --make-fetch-head + Attempt to treat series as a pull request and fetch it into FETCH_HEAD + -M, --merge + Attempt to merge series as if it were a pull request (execs git-merge) + --guess-lookback GUESSDAYS + (use with -H or -M) When guessing base, go back this many days from the patch date (default: 3 weeks) + +*Example*: b4 shazam -H 20200313231252.64999-1-keescook@chromium.org b4 pr ~~~~~ +This command is for working with pull requests submitted using +``git-request-pull``. + usage: command.py pr [-h] [-g GITDIR] [-b BRANCH] [-c] [-e] [-o OUTMBOX] [msgid] @@ -158,7 +243,7 @@ optional arguments: b4 ty ~~~~~ usage: - b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-s SEND [SEND ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since SINCE] + b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-t THANK_FOR [THANK_FOR ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since SINCE] [-S] [--dry-run] optional arguments: -h, --help show this help message and exit @@ -167,19 +252,29 @@ optional arguments: -o OUTDIR, --outdir OUTDIR Write thanks files into this dir (default=.) -l, --list List pull requests and patch series you have retrieved - -s SEND, --send SEND Generate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or "all") + -t THANK_FOR, --thank-for THANK_FOR + Generate thankyous for specific entries from -l (e.g.: 1,3-5,7-; or "all") -d DISCARD, --discard DISCARD Discard specific messages from -l (e.g.: 1,3-5,7-; or "all") - -a, --auto Use the Auto-Thankanator to figure out what got applied/merged + -a, --auto Use the Auto-Thankanator gun to figure out what got applied/merged -b BRANCH, --branch BRANCH The branch to check against, instead of current --since SINCE The --since option to use when auto-matching patches (default=1.week) + -S, --send-email Send email instead of writing out .thanks files + --dry-run Print out emails instead of sending them -*Example*: b4 ty --auto +.. note:: + + To send mails directly using -S, you should have a configured + [sendemail] section somewhere in your applicable git configuration + files (global or in-tree). + +*Example*: b4 ty -aS --dry-run b4 diff ~~~~~~~ -usage: b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid] +usage: + b4 diff [-h] [-g GITDIR] [-p USEPROJECT] [-C] [-v WANTVERS [WANTVERS ...]] [-n] [-o OUTDIFF] [-c] [-m AMBOX AMBOX] [msgid] positional arguments: msgid Message ID to process, pipe a raw message, or use -m @@ -211,7 +306,8 @@ optional arguments: b4 kr ~~~~~ -usage: b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys] [msgid] +usage: + b4 kr [-h] [-p USEPROJECT] [-m LOCALMBOX] [-C] [--show-keys] [msgid] positional arguments: msgid Message ID to process, or pipe a raw message @@ -254,13 +350,6 @@ Default configuration, with explanations:: # public-inbox, python, and git save-maildirs = no # - # When processing thread trailers, sort them in this order. - # Can use shell-globbing and must end with ,* - # Some sorting orders: - #trailer-order=link*,fixes*,cc*,reported*,suggested*,original*,co-*,tested*,reviewed*,acked*,signed-off*,* - #trailer-order = fixes*,reported*,suggested*,original*,co-*,signed-off*,tested*,reviewed*,acked*,cc*,link*,* - trailer-order = _preserve_ - # # Attestation-checking configuration parameters # off: do not bother checking attestation # check: print an attaboy when attestation is found @@ -298,7 +387,21 @@ Default configuration, with explanations:: thanks-pr-template = None # See thanks-am-template.example. If not set, a default template will be used. thanks-am-template = None - + # additional flags to pass to "git am" when we run "b4 shazam" + shazam-am-flags = None + # additional flags to pass to "git merge" when we run "b4 shazam -M" + shazam-merge-flags = --signoff + # Used when preparing merge messages from cover letters. See shazam-merge-template.example + shazam-merge-template = None + # Use to exclude certain mail addresses from ever being added to auto-generated mail + # Separate multiple entries using comma (spaces are ignored), shell-style globbing accepted + email-exclude = *@codeaurora.org, example@example.com + +PROXYING REQUESTS +----------------- +Commands making remote HTTP requests may be configured to use a proxy by +setting the **HTTPS_PROXY** environment variable, as described in +https://docs.python-requests.org/en/latest/user/advanced/#proxies. SUPPORT ------- |