docs,man: document the --single-message flag

Add documentation for the --single-message flag.

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

5 files changed, 34 insertions, 2 deletions

diff --git a/b4/command.py b/b4/command.py
index 2bf6eb9..f4516b2 100644
--- a/b4/command.py
+++ b/b4/command.py
@@ -22,6 +22,8 @@ def cmd_retrieval_common_opts(sp):
                     help='When accepting messages on stdin, split using this pipe separator string')
     sp.add_argument('-C', '--no-cache', dest='nocache', action='store_true', default=False,
                     help='Do not use local cache')
+    sp.add_argument('--single-message', dest='singlemsg', action='store_true', default=False,
+                    help='Only retrieve the message matching the msgid and ignore the rest of the thread')
 
 
 def cmd_mbox_common_opts(sp):
@@ -34,8 +36,6 @@ def cmd_mbox_common_opts(sp):
                     help='Filename to name the mbox destination')
     sp.add_argument('-M', '--save-as-maildir', dest='maildir', action='store_true', default=False,
                     help='Save as maildir (avoids mbox format ambiguities)')
-    sp.add_argument('--single-message', dest='singlemsg', action='store_true', default=False,
-                    help='Only retrieve the message matching the msgid and ignore the rest of the thread')
 
 
 def cmd_am_common_opts(sp):
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index 9388c43..e6cfec6 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -79,6 +79,12 @@ The following flags are common to both commands:
   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.
+
 ``-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
diff --git a/docs/maintainer/mbox.rst b/docs/maintainer/mbox.rst
index dc55544..b4bba22 100644
--- a/docs/maintainer/mbox.rst
+++ b/docs/maintainer/mbox.rst
@@ -50,6 +50,12 @@ Option flags
   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.
+
 ``-o OUTDIR, --outdir OUTDIR``
   Instead of writing the .mbox file to the current directory, write it
   to this location instead. You can also pass a path to an existing
diff --git a/man/b4.5 b/man/b4.5
index 15dccd8..0263243 100644
--- a/man/b4.5
+++ b/man/b4.5
@@ -127,6 +127,9 @@ When accepting messages on stdin, split using this pipe separator string
 .B  \-C\fP,\fB  \-\-no\-cache
 Do not use local cache
 .TP
+.B  \-\-single\-message
+Only retrieve the message matching the msgid and ignore the rest of the thread
+.TP
 .BI \-o \ OUTDIR\fR,\fB \ \-\-outdir \ OUTDIR
 Output into this directory (or use \- to output mailbox contents to stdout)
 .TP
@@ -202,6 +205,9 @@ When accepting messages on stdin, split using this pipe separator string
 .B  \-C\fP,\fB  \-\-no\-cache
 Do not use local cache
 .TP
+.B  \-\-single\-message
+Only retrieve the message matching the msgid and ignore the rest of the thread
+.TP
 .BI \-o \ OUTDIR\fR,\fB \ \-\-outdir \ OUTDIR
 Output into this directory (or use \- to output mailbox contents to stdout)
 .TP
@@ -214,6 +220,9 @@ Filename to name the mbox destination
 .B  \-M\fP,\fB  \-\-save\-as\-maildir
 Save as maildir (avoids mbox format ambiguities)
 .TP
+.B  \-\-single\-message
+Only retrieve the message matching the msgid and ignore the rest of the thread
+.TP
 .BI \-v \ WANTVER\fR,\fB \ \-\-use\-version \ WANTVER
 Get a specific version of the patch/series
 .TP
@@ -308,6 +317,9 @@ When accepting messages on stdin, split using this pipe separator string
 .B  \-C\fP,\fB  \-\-no\-cache
 Do not use local cache
 .TP
+.B  \-\-single\-message
+Only retrieve the message matching the msgid and ignore the rest of the thread
+.TP
 .BI \-v \ WANTVER\fR,\fB \ \-\-use\-version \ WANTVER
 Get a specific version of the patch/series
 .TP
diff --git a/man/b4.5.rst b/man/b4.5.rst
index 6622fb9..8cff248 100644
--- a/man/b4.5.rst
+++ b/man/b4.5.rst
@@ -81,6 +81,8 @@ options:
                         When accepting messages on stdin, split using this pipe separator string
   -C, --no-cache
                         Do not use local cache
+  --single-message
+                        Only retrieve the message matching the msgid and ignore the rest of the thread
   -o OUTDIR, --outdir OUTDIR
                         Output into this directory (or use - to output mailbox contents to stdout)
   -c, --check-newer-revisions
@@ -134,6 +136,8 @@ options:
                         When accepting messages on stdin, split using this pipe separator string
   -C, --no-cache
                         Do not use local cache
+  --single-message
+                        Only retrieve the message matching the msgid and ignore the rest of the thread
   -o OUTDIR, --outdir OUTDIR
                         Output into this directory (or use - to output mailbox contents to stdout)
   -c, --check-newer-revisions
@@ -142,6 +146,8 @@ options:
                         Filename to name the mbox destination
   -M, --save-as-maildir
                         Save as maildir (avoids mbox format ambiguities)
+  --single-message
+                        Only retrieve the message matching the msgid and ignore the rest of the thread
   -v WANTVER, --use-version WANTVER
                         Get a specific version of the patch/series
   -t, --apply-cover-trailers
@@ -208,6 +214,8 @@ options:
   --stdin-pipe-sep STDIN_PIPE_SEP
                         When accepting messages on stdin, split using this pipe separator string
   -C, --no-cache        Do not use local cache
+  --single-message
+                        Only retrieve the message matching the msgid and ignore the rest of the thread
   -v WANTVER, --use-version WANTVER
                         Get a specific version of the patch/series
   -t, --apply-cover-trailers