Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review. --- doc/man1/notmuch-address.rst | 174 +++++++++-------- doc/man1/notmuch-compact.rst | 20 +- doc/man1/notmuch-config.rst | 45 +++-- doc/man1/notmuch-count.rst | 71 ++++--- doc/man1/notmuch-dump.rst | 146 +++++++------- doc/man1/notmuch-emacs-mua.rst | 80 ++++---- doc/man1/notmuch-insert.rst | 100 +++++----- doc/man1/notmuch-new.rst | 67 ++++--- doc/man1/notmuch-reindex.rst | 47 ++--- doc/man1/notmuch-reply.rst | 117 +++++------ doc/man1/notmuch-restore.rst | 118 ++++++------ doc/man1/notmuch-search.rst | 234 +++++++++++----------- doc/man1/notmuch-show.rst | 343 +++++++++++++++++---------------- doc/man1/notmuch-tag.rst | 37 ++-- doc/man1/notmuch.rst | 44 +++-- 15 files changed, 874 insertions(+), 769 deletions(-) diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 9eae65cbae8f..7423b6295508 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -20,89 +20,97 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for Supported options for **address** include -``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) - Presents the results in either JSON, S-Expressions, newline - character separated plain-text (default), or null character - separated plain-text (compatible with :manpage:`xargs(1)` -0 - option where available). - -``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke :any:`notmuch(1)` internally. If - omitted, the latest supported version will be used. - -``--output=(sender|recipients|count|address)`` - Controls which information appears in the output. This option can - be given multiple times to combine different outputs. When - neither ``--output=sender`` nor ``--output=recipients`` is - given, ``--output=sender`` is implied. - - **sender** - Output all addresses from the *From* header. - - Note: Searching for **sender** should be much faster than - searching for **recipients**, because sender addresses are - cached directly in the database whereas other addresses need - to be fetched from message files. - - **recipients** - Output all addresses from the *To*, *Cc* and *Bcc* headers. - - **count** - Print the count of how many times was the address encountered - during search. - - Note: With this option, addresses are printed only after the - whole search is finished. This may take long time. - - **address** - Output only the email addresses instead of the full mailboxes - with names and email addresses. This option has no effect on - the JSON or S-Expression output formats. - -``--deduplicate=(no|mailbox|address)`` - Control the deduplication of results. - - **no** - Output all occurrences of addresses in the matching - messages. This is not applicable with ``--output=count``. - - **mailbox** - Deduplicate addresses based on the full, case sensitive name - and email address, or mailbox. This is effectively the same as - piping the ``--deduplicate=no`` output to **sort | uniq**, except - for the order of results. This is the default. - - **address** - Deduplicate addresses based on the case insensitive address - part of the mailbox. Of all the variants (with different name - or case), print the one occurring most frequently among the - matching messages. If ``--output=count`` is specified, include all - variants in the count. - -``--sort=``\ (**newest-first**\ \|\ **oldest-first**) - This option can be used to present results in either chronological - order (**oldest-first**) or reverse chronological order - (**newest-first**). - - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed first). - - However, if either ``--output=count`` or ``--deduplicate=address`` is - specified, this option is ignored and the order of the results is - unspecified. - -``--exclude=(true|false)`` - A message is called "excluded" if it matches at least one tag in - search.exclude\_tags that does not appear explicitly in the search - terms. This option specifies whether to omit excluded messages in - the search process. - - The default value, **true**, prevents excluded messages from - matching the search terms. - - **false** allows excluded messages to match search terms and - appear in displayed results. +.. program:: address + +.. option:: --format=(json|sexp|text|text0) + + Presents the results in either JSON, S-Expressions, newline + character separated plain-text (default), or null character + separated plain-text (compatible with :manpage:`xargs(1)` -0 + option where available). + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --output=(sender|recipients|count|address) + + Controls which information appears in the output. This option can + be given multiple times to combine different outputs. When + neither ``--output=sender`` nor ``--output=recipients`` is + given, ``--output=sender`` is implied. + + **sender** + Output all addresses from the *From* header. + + Note: Searching for **sender** should be much faster than + searching for **recipients**, because sender addresses are + cached directly in the database whereas other addresses need + to be fetched from message files. + + **recipients** + Output all addresses from the *To*, *Cc* and *Bcc* headers. + + **count** + Print the count of how many times was the address encountered + during search. + + Note: With this option, addresses are printed only after the + whole search is finished. This may take long time. + + **address** + Output only the email addresses instead of the full mailboxes + with names and email addresses. This option has no effect on + the JSON or S-Expression output formats. + +.. option:: --deduplicate=(no|mailbox|address) + + Control the deduplication of results. + + **no** + Output all occurrences of addresses in the matching + messages. This is not applicable with ``--output=count``. + + **mailbox** + Deduplicate addresses based on the full, case sensitive name + and email address, or mailbox. This is effectively the same as + piping the ``--deduplicate=no`` output to **sort | uniq**, except + for the order of results. This is the default. + + **address** + Deduplicate addresses based on the case insensitive address + part of the mailbox. Of all the variants (with different name + or case), print the one occurring most frequently among the + matching messages. If ``--output=count`` is specified, include all + variants in the count. + +.. option:: --sort=(newest-first|oldest-first) + + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). + + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). + + However, if either ``--output=count`` or ``--deduplicate=address`` is + specified, this option is ignored and the order of the results is + unspecified. + +.. option:: --exclude=(true|false) + + A message is called "excluded" if it matches at least one tag in + search.exclude\_tags that does not appear explicitly in the search + terms. This option specifies whether to omit excluded messages in + the search process. + + The default value, **true**, prevents excluded messages from + matching the search terms. + + **false** allows excluded messages to match search terms and + appear in displayed results. EXIT STATUS =========== diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst index 3e3e70c532ca..cb1c858b1e4a 100644 --- a/doc/man1/notmuch-compact.rst +++ b/doc/man1/notmuch-compact.rst @@ -26,14 +26,18 @@ process (which may be quite long) to protect data integrity. Supported options for **compact** include -``--backup=``\ <directory> - Save the current database to the given directory before replacing - it with the compacted database. The backup directory must not - exist and it must reside on the same mounted filesystem as the - current database. - -``--quiet`` - Do not report database compaction progress to stdout. +.. program:: compact + +.. option:: --backup=<directory> + + Save the current database to the given directory before replacing + it with the compacted database. The backup directory must not + exist and it must reside on the same mounted filesystem as the + current database. + +.. option:: --quiet + + Do not report database compaction progress to stdout. SEE ALSO ======== diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 129d4b810261..af126289a97f 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -19,32 +19,37 @@ DESCRIPTION The **config** command can be used to get or set settings in the notmuch configuration file and corresponding database. -**get** - The value of the specified configuration item is printed to - stdout. If the item has multiple values (it is a list), each value - is separated by a newline character. +.. program:: config -**set** - The specified configuration item is set to the given value. To - specify a multiple-value item (a list), provide each value as a - separate command-line argument. +.. option:: get - If no values are provided, the specified configuration item will - be removed from the configuration file. + The value of the specified configuration item is printed to + stdout. If the item has multiple values (it is a list), each value + is separated by a newline character. - With the `--database` option, updates configuration metadata - stored in the database, rather than the default (text) - configuration file. +.. option:: set -**list** - Every configuration item is printed to stdout, each on a separate - line of the form:: + The specified configuration item is set to the given value. To + specify a multiple-value item (a list), provide each value as a + separate command-line argument. - section.item=value + If no values are provided, the specified configuration item will + be removed from the configuration file. - No additional whitespace surrounds the dot or equals sign - characters. In a multiple-value item (a list), the values are - separated by semicolon characters. + With the `--database` option, updates configuration metadata + stored in the database, rather than the default (text) + configuration file. + +.. option:: list + + Every configuration item is printed to stdout, each on a separate + line of the form:: + + section.item=value + + No additional whitespace surrounds the dot or equals sign + characters. In a multiple-value item (a list), the values are + separated by semicolon characters. The available configuration items are described below. Non-absolute paths are presumed relative to `$HOME` for items in section diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst index 61686d359399..9a7e4bacf459 100644 --- a/doc/man1/notmuch-count.rst +++ b/doc/man1/notmuch-count.rst @@ -24,38 +24,45 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for Supported options for **count** include -``--output=(messages|threads|files)`` - **messages** - Output the number of matching messages. This is the default. - - **threads** - Output the number of matching threads. - - **files** - Output the number of files associated with matching - messages. This may be bigger than the number of matching - messages due to duplicates (i.e. multiple files having the - same message-id). - -``--exclude=(true|false)`` - Specify whether to omit messages matching search.exclude\_tags from - the count (the default) or not. - -``--batch`` - Read queries from a file (stdin by default), one per line, and - output the number of matching messages (or threads) to stdout, one - per line. On an empty input line the count of all messages (or - threads) in the database will be output. This option is not - compatible with specifying search terms on the command line. - -``--lastmod`` - Append lastmod (counter for number of database updates) and UUID - to the output. lastmod values are only comparable between - databases with the same UUID. - -``--input=``\ <filename> - Read input from given file, instead of from stdin. Implies - ``--batch``. +.. program:: count + +.. option:: --output=(messages|threads|files) + + **messages** + Output the number of matching messages. This is the default. + + **threads** + Output the number of matching threads. + + **files** + Output the number of files associated with matching + messages. This may be bigger than the number of matching + messages due to duplicates (i.e. multiple files having the + same message-id). + +.. option:: --exclude=(true|false) + + Specify whether to omit messages matching search.exclude\_tags from + the count (the default) or not. + +.. option:: --batch + + Read queries from a file (stdin by default), one per line, and + output the number of matching messages (or threads) to stdout, one + per line. On an empty input line the count of all messages (or + threads) in the database will be output. This option is not + compatible with specifying search terms on the command line. + +.. option:: --lastmod + + Append lastmod (counter for number of database updates) and UUID + to the output. lastmod values are only comparable between + databases with the same UUID. + +.. option:: --input=<filename> + + Read input from given file, instead of from stdin. Implies + ``--batch``. SEE ALSO ======== diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index 57c462979986..4319c5c31268 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -28,76 +28,82 @@ the remaining arguments are search terms. Supported options for **dump** include -``--gzip`` - Compress the output in a format compatible with :manpage:`gzip(1)`. - -``--format=(sup|batch-tag)`` - Notmuch restore supports two plain text dump formats, both with - one message-id per line, followed by a list of tags. - - **batch-tag** - The default **batch-tag** dump format is intended to more - robust against malformed message-ids and tags containing - whitespace or non-\ :manpage:`ascii(7)` characters. Each line - has the form:: - - +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ > - - Tags are hex-encoded by replacing every byte not matching the - regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two - digit hex encoding. The message ID is a valid Xapian query, - quoted using Xapian boolean term quoting rules: if the ID - contains whitespace or a close paren or starts with a double - quote, it must be enclosed in double quotes and double quotes - inside the ID must be doubled. The astute reader will notice - this is a special case of the batch input format for - :any:`notmuch-tag(1)`; note that the single message-id query is - mandatory for :any:`notmuch-restore(1)`. - - **sup** - The **sup** dump file format is specifically chosen to be - compatible with the format of files produced by - :manpage:`sup-dump(1)`. So if you've previously been using sup - for mail, then the :any:`notmuch-restore(1)` command provides - you a way to import all of your tags (or labels as sup calls - them). Each line has the following form:: - - <*message-id*\ > **(** <*tag*\ > ... **)** - - with zero or more tags are separated by spaces. Note that - (malformed) message-ids may contain arbitrary non-null - characters. Note also that tags with spaces will not be - correctly restored with this format. - -``--include=(config|properties|tags)`` - Control what kind of metadata is included in the output. - - **config** - Output configuration data stored in the database. Each line - starts with "#@ ", followed by a space separated key-value - pair. Both key and value are hex encoded if needed. - - **properties** - Output per-message (key,value) metadata. Each line starts - with "#= ", followed by a message id, and a space separated - list of key=value pairs. Ids, keys and values are hex encoded - if needed. See :any:`notmuch-properties(7)` for more details. - - **tags** - Output per-message boolean metadata, namely tags. See *format* above - for description of the output. - - The default is to include all available types of data. The option - can be specified multiple times to select some subset. As of - version 3 of the dump format, there is a header line of the - following form:: - - #notmuch-dump <*format*>:<*version*> <*included*> - - where <*included*> is a comma separated list of the above options. - -``--output=``\ <filename> - Write output to given file instead of stdout. +.. program:: dump + +.. option:: --gzip + + Compress the output in a format compatible with :manpage:`gzip(1)`. + +.. option:: --format=(sup|batch-tag) + + Notmuch restore supports two plain text dump formats, both with + one message-id per line, followed by a list of tags. + + **batch-tag** + The default **batch-tag** dump format is intended to more + robust against malformed message-ids and tags containing + whitespace or non-\ :manpage:`ascii(7)` characters. Each line + has the form:: + + +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ > + + Tags are hex-encoded by replacing every byte not matching the + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two + digit hex encoding. The message ID is a valid Xapian query, + quoted using Xapian boolean term quoting rules: if the ID + contains whitespace or a close paren or starts with a double + quote, it must be enclosed in double quotes and double quotes + inside the ID must be doubled. The astute reader will notice + this is a special case of the batch input format for + :any:`notmuch-tag(1)`; note that the single message-id query is + mandatory for :any:`notmuch-restore(1)`. + + **sup** + The **sup** dump file format is specifically chosen to be + compatible with the format of files produced by + :manpage:`sup-dump(1)`. So if you've previously been using sup + for mail, then the :any:`notmuch-restore(1)` command provides + you a way to import all of your tags (or labels as sup calls + them). Each line has the following form:: + + <*message-id*\ > **(** <*tag*\ > ... **)** + + with zero or more tags are separated by spaces. Note that + (malformed) message-ids may contain arbitrary non-null + characters. Note also that tags with spaces will not be + correctly restored with this format. + +.. option:: --include=(config|properties|tags) + + Control what kind of metadata is included in the output. + + **config** + Output configuration data stored in the database. Each line + starts with "#@ ", followed by a space separated key-value + pair. Both key and value are hex encoded if needed. + + **properties** + Output per-message (key,value) metadata. Each line starts + with "#= ", followed by a message id, and a space separated + list of key=value pairs. Ids, keys and values are hex encoded + if needed. See :any:`notmuch-properties(7)` for more details. + + **tags** + Output per-message boolean metadata, namely tags. See *format* above + for description of the output. + + The default is to include all available types of data. The option + can be specified multiple times to select some subset. As of + version 3 of the dump format, there is a header line of the + following form:: + + #notmuch-dump <*format*>:<*version*> <*included*> + + where <*included*> is a comma separated list of the above options. + +.. option:: --output=<filename> + + Write output to given file instead of stdout. SEE ALSO ======== diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst index c0d5b1a7c476..d8af08bda47a 100644 --- a/doc/man1/notmuch-emacs-mua.rst +++ b/doc/man1/notmuch-emacs-mua.rst @@ -17,50 +17,64 @@ subject, recipients, and message body, or mailto: URL. Supported options for **emacs-mua** include -``-h, --help`` - Display help. +.. program:: emacs-mua -``-s, --subject=``\ <subject> - Specify the subject of the message. +.. option:: -h, --help -``--to=``\ <to-address> - Specify a recipient (To). + Display help. -``-c, --cc=``\ <cc-address> - Specify a carbon-copy (Cc) recipient. +.. option:: -s, --subject=<subject> -``-b, --bcc=``\ <bcc-address> - Specify a blind-carbon-copy (Bcc) recipient. + Specify the subject of the message. -``-i, --body=``\ <file> - Specify a file to include into the body of the message. +.. option:: --to=<to-address> -``--hello`` - Go to the Notmuch hello screen instead of the message composition - window if no message composition parameters are given. + Specify a recipient (To). -``--no-window-system`` - Even if a window system is available, use the current terminal. +.. option:: -c, --cc=<cc-address> -``--client`` - Use :manpage:`emacsclient(1)`, rather than - :manpage:`emacs(1)`. For :manpage:`emacsclient(1)` to work, you - need an already running Emacs with a server, or use - ``--auto-daemon``. + Specify a carbon-copy (Cc) recipient. -``--auto-daemon`` - Automatically start Emacs in daemon mode, if the Emacs server is - not running. Applicable with ``--client``. Implies - ``--create-frame``. +.. option:: -b, --bcc=<bcc-address> -``--create-frame`` - Create a new frame instead of trying to use the current Emacs - frame. Applicable with ``--client``. This will be required when - Emacs is running (or automatically started with ``--auto-daemon``) - in daemon mode. + Specify a blind-carbon-copy (Bcc) recipient. -``--print`` - Output the resulting elisp to stdout instead of evaluating it. +.. option:: -i, --body=<file> + + Specify a file to include into the body of the message. + +.. option:: --hello + + Go to the Notmuch hello screen instead of the message composition + window if no message composition parameters are given. + +.. option:: --no-window-system + + Even if a window system is available, use the current terminal. + +.. option:: --client + + Use :manpage:`emacsclient(1)`, rather than + :manpage:`emacs(1)`. For :manpage:`emacsclient(1)` to work, you + need an already running Emacs with a server, or use + ``--auto-daemon``. + +.. option:: --auto-daemon + + Automatically start Emacs in daemon mode, if the Emacs server is + not running. Applicable with ``--client``. Implies + ``--create-frame``. + +.. option:: --create-frame + + Create a new frame instead of trying to use the current Emacs + frame. Applicable with ``--client``. This will be required when + Emacs is running (or automatically started with ``--auto-daemon``) + in daemon mode. + +.. option:: --print + + Output the resulting elisp to stdout instead of evaluating it. The supported positional parameters and short options are a compatible subset of the :manpage:`mutt(1)` MUA command-line options. The options diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index 67adf225ca9a..82c4a7a0b94e 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -33,52 +33,60 @@ more details on hooks. Option arguments must appear before any tag operation arguments. Supported options for **insert** include -``--folder=<``\ folder\ **>** - Deliver the message to the specified folder, relative to the - top-level directory given by the value of **database.path**. The - default is the empty string, which means delivering to the - top-level directory. - -``--create-folder`` - Try to create the folder named by the ``--folder`` option, if it - does not exist. Otherwise the folder must already exist for mail - delivery to succeed. - -``--keep`` - Keep the message file if indexing fails, and keep the message - indexed if applying tags or maildir flag synchronization - fails. Ignore these errors and return exit status 0 to indicate - successful mail delivery. - -``--no-hooks`` - Prevent hooks from being run. - -``--world-readable`` - When writing mail to the mailbox, allow it to be read by users - other than the current user. Note that this does not override - umask. By default, delivered mail is only readable by the current - user. - -``--decrypt=(true|nostash|auto|false)`` - If ``true`` and the message is encrypted, try to decrypt the - message while indexing, stashing any session keys discovered. If - ``auto``, and notmuch already knows about a session key for the - message, it will try decrypting using that session key but will - not try to access the user's secret keys. If decryption is - successful, index the cleartext itself. Either way, the message - is always stored to disk in its original form (ciphertext). - - ``nostash`` is the same as ``true`` except that it will not stash - newly-discovered session keys in the database. - - Be aware that the index is likely sufficient (and a stashed - session key is certainly sufficient) to reconstruct the cleartext - of the message itself, so please ensure that the notmuch message - index is adequately protected. DO NOT USE ``--decrypt=true`` or - ``--decrypt=nostash`` without considering the security of your - index. - - See also ``index.decrypt`` in :any:`notmuch-config(1)`. +.. program:: insert + +.. option:: --folder=<folder> + + Deliver the message to the specified folder, relative to the + top-level directory given by the value of **database.path**. The + default is the empty string, which means delivering to the + top-level directory. + +.. option:: --create-folder + + Try to create the folder named by the ``--folder`` option, if it + does not exist. Otherwise the folder must already exist for mail + delivery to succeed. + +.. option:: --keep + + Keep the message file if indexing fails, and keep the message + indexed if applying tags or maildir flag synchronization + fails. Ignore these errors and return exit status 0 to indicate + successful mail delivery. + +.. option:: --no-hooks + + Prevent hooks from being run. + +.. option:: --world-readable + + When writing mail to the mailbox, allow it to be read by users + other than the current user. Note that this does not override + umask. By default, delivered mail is only readable by the current + user. + +.. option:: --decrypt=(true|nostash|auto|false) + + If ``true`` and the message is encrypted, try to decrypt the + message while indexing, stashing any session keys discovered. If + ``auto``, and notmuch already knows about a session key for the + message, it will try decrypting using that session key but will + not try to access the user's secret keys. If decryption is + successful, index the cleartext itself. Either way, the message + is always stored to disk in its original form (ciphertext). + + ``nostash`` is the same as ``true`` except that it will not stash + newly-discovered session keys in the database. + + Be aware that the index is likely sufficient (and a stashed + session key is certainly sufficient) to reconstruct the cleartext + of the message itself, so please ensure that the notmuch message + index is adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in :any:`notmuch-config(1)`. EXIT STATUS =========== diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst index 1044d1cdd0f5..9cb4a54e7534 100644 --- a/doc/man1/notmuch-new.rst +++ b/doc/man1/notmuch-new.rst @@ -40,36 +40,43 @@ details on hooks. Supported options for **new** include -``--no-hooks`` - Prevents hooks from being run. - -``--quiet`` - Do not print progress or results. - -``--verbose`` - Print file names being processed. Ignored when combined with - ``--quiet``. - -``--decrypt=(true|nostash|auto|false)`` - If ``true``, when encountering an encrypted message, try to - decrypt it while indexing, and stash any discovered session keys. - If ``auto``, try to use any session key already known to belong to - this message, but do not attempt to use the user's secret keys. - If decryption is successful, index the cleartext of the message. - - Be aware that the index is likely sufficient (and the session key - is certainly sufficient) to reconstruct the cleartext of the - message itself, so please ensure that the notmuch message index is - adequately protected. DO NOT USE ``--decrypt=true`` or - ``--decrypt=nostash`` without considering the security of your - index. - - See also ``index.decrypt`` in :any:`notmuch-config(1)`. - -``--full-scan`` - By default notmuch-new uses directory modification times (mtimes) - to optimize the scanning of directories for new mail. This option turns - that optimization off. +.. program:: new + +.. option:: --no-hooks + + Prevents hooks from being run. + +.. option:: --quiet + + Do not print progress or results. + +.. option:: --verbose + + Print file names being processed. Ignored when combined with + ``--quiet``. + +.. option:: --decrypt=(true|nostash|auto|false) + + If ``true``, when encountering an encrypted message, try to + decrypt it while indexing, and stash any discovered session keys. + If ``auto``, try to use any session key already known to belong to + this message, but do not attempt to use the user's secret keys. + If decryption is successful, index the cleartext of the message. + + Be aware that the index is likely sufficient (and the session key + is certainly sufficient) to reconstruct the cleartext of the + message itself, so please ensure that the notmuch message index is + adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in :any:`notmuch-config(1)`. + +.. option:: --full-scan + + By default notmuch-new uses directory modification times (mtimes) + to optimize the scanning of directories for new mail. This option turns + that optimization off. EXIT STATUS =========== diff --git a/doc/man1/notmuch-reindex.rst b/doc/man1/notmuch-reindex.rst index 359def7ef798..85dad249b582 100644 --- a/doc/man1/notmuch-reindex.rst +++ b/doc/man1/notmuch-reindex.rst @@ -23,28 +23,31 @@ messages using the supplied options. Supported options for **reindex** include -``--decrypt=(true|nostash|auto|false)`` - If ``true``, when encountering an encrypted message, try to - decrypt it while reindexing, stashing any session keys discovered. - If ``auto``, and notmuch already knows about a session key for the - message, it will try decrypting using that session key but will - not try to access the user's secret keys. If decryption is - successful, index the cleartext itself. - - ``nostash`` is the same as ``true`` except that it will not stash - newly-discovered session keys in the database. - - If ``false``, notmuch reindex will also delete any stashed session - keys for all messages matching the search terms. - - Be aware that the index is likely sufficient (and a stashed - session key is certainly sufficient) to reconstruct the cleartext - of the message itself, so please ensure that the notmuch message - index is adequately protected. DO NOT USE ``--decrypt=true`` or - ``--decrypt=nostash`` without considering the security of your - index. - - See also ``index.decrypt`` in :any:`notmuch-config(1)`. +.. program:: reindex + +.. option:: --decrypt=(true|nostash|auto|false) + + If ``true``, when encountering an encrypted message, try to + decrypt it while reindexing, stashing any session keys discovered. + If ``auto``, and notmuch already knows about a session key for the + message, it will try decrypting using that session key but will + not try to access the user's secret keys. If decryption is + successful, index the cleartext itself. + + ``nostash`` is the same as ``true`` except that it will not stash + newly-discovered session keys in the database. + + If ``false``, notmuch reindex will also delete any stashed session + keys for all messages matching the search terms. + + Be aware that the index is likely sufficient (and a stashed + session key is certainly sufficient) to reconstruct the cleartext + of the message itself, so please ensure that the notmuch message + index is adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in :any:`notmuch-config(1)`. EXAMPLES ======== diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index 168c399c954f..4a78a90b2251 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -36,62 +36,67 @@ The resulting message template is output to stdout. Supported options for **reply** include -``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**) - **default** - Includes subject and quoted message body as an RFC 2822 - message. - - **json** - Produces JSON output containing headers for a reply message - and the contents of the original message. This output can be - used by a client to create a reply message intelligently. - - **sexp** - Produces S-Expression output containing headers for a reply - message and the contents of the original message. This output - can be used by a client to create a reply message - intelligently. - - **headers-only** - Only produces In-Reply-To, References, To, Cc, and Bcc - headers. - -``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke :any:`notmuch(1)` internally. If - omitted, the latest supported version will be used. - -``--reply-to=``\ (**all**\ \|\ **sender**) - **all** (default) - Replies to all addresses. - - **sender** - Replies only to the sender. If replying to user's own message - (Reply-to: or From: header is one of the user's configured - email addresses), try To:, Cc:, and Bcc: headers in this - order, and copy values from the first that contains something - other than only the user's addresses. - -``--decrypt=(false|auto|true)`` - - If ``true``, decrypt any MIME encrypted parts found in the - selected content (i.e., "multipart/encrypted" parts). Status - of the decryption will be reported (currently only supported - with ``--format=json`` and ``--format=sexp``), and on successful - decryption the multipart/encrypted part will be replaced by - the decrypted content. - - If ``auto``, and a session key is already known for the - message, then it will be decrypted, but notmuch will not try - to access the user's secret keys. - - Use ``false`` to avoid even automatic decryption. - - Non-automatic decryption expects a functioning - :manpage:`gpg-agent(1)` to provide any needed credentials. Without - one, the decryption will likely fail. - - Default: ``auto`` +.. program:: reply + +.. option:: --format=(default|json|sexp|headers-only) + + **default** + Includes subject and quoted message body as an RFC 2822 + message. + + **json** + Produces JSON output containing headers for a reply message + and the contents of the original message. This output can be + used by a client to create a reply message intelligently. + + **sexp** + Produces S-Expression output containing headers for a reply + message and the contents of the original message. This output + can be used by a client to create a reply message + intelligently. + + **headers-only** + Only produces In-Reply-To, References, To, Cc, and Bcc + headers. + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --reply-to=(all|sender) + + **all** (default) + Replies to all addresses. + + **sender** + Replies only to the sender. If replying to user's own message + (Reply-to: or From: header is one of the user's configured + email addresses), try To:, Cc:, and Bcc: headers in this + order, and copy values from the first that contains something + other than only the user's addresses. + +.. option:: --decrypt=(false|auto|true) + + If ``true``, decrypt any MIME encrypted parts found in the + selected content (i.e., "multipart/encrypted" parts). Status + of the decryption will be reported (currently only supported + with ``--format=json`` and ``--format=sexp``), and on successful + decryption the multipart/encrypted part will be replaced by + the decrypted content. + + If ``auto``, and a session key is already known for the + message, then it will be decrypted, but notmuch will not try + to access the user's secret keys. + + Use ``false`` to avoid even automatic decryption. + + Non-automatic decryption expects a functioning + :manpage:`gpg-agent(1)` to provide any needed credentials. Without + one, the decryption will likely fail. + + Default: ``auto`` See :any:`notmuch-search-terms(7)` for details of the supported syntax for <search-terms>. diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst index 7be348545c00..bd452475768d 100644 --- a/doc/man1/notmuch-restore.rst +++ b/doc/man1/notmuch-restore.rst @@ -18,62 +18,68 @@ The input is read from the given filename, if any, or from stdin. Supported options for **restore** include -``--accumulate`` - The union of the existing and new tags is applied, instead of - replacing each message's tags as they are read in from the dump - file. - -``--format=(sup|batch-tag|auto)`` - Notmuch restore supports two plain text dump formats, with each - line specifying a message-id and a set of tags. For details of the - actual formats, see :any:`notmuch-dump(1)`. - - **sup** - The **sup** dump file format is specifically chosen to be - compatible with the format of files produced by sup-dump. So - if you've previously been using sup for mail, then the - **notmuch restore** command provides you a way to import all - of your tags (or labels as sup calls them). - - **batch-tag** - The **batch-tag** dump format is intended to more robust - against malformed message-ids and tags containing whitespace - or non-\ **ascii(7)** characters. See :any:`notmuch-dump(1)` for - details on this format. - - **notmuch restore** updates the maildir flags according to tag - changes if the **maildir.synchronize\_flags** configuration - option is enabled. See :any:`notmuch-config(1)` for details. - - **auto** - This option (the default) tries to guess the format from the - input. For correctly formed input in either supported format, - this heuristic, based the fact that batch-tag format contains - no parentheses, should be accurate. - -``--include=(config|properties|tags)`` - Control what kind of metadata is restored. - - **config** - Restore configuration data to the database. Each configuration - line starts with "#@ ", followed by a space separated - key-value pair. Both key and value are hex encoded if needed. - - **properties** - Restore per-message (key,value) metadata. Each line starts - with "#= ", followed by a message id, and a space separated - list of key=value pairs. Ids, keys and values are hex encoded - if needed. See :any:`notmuch-properties(7)` for more details. - - **tags** - Restore per-message metadata, namely tags. See *format* above - for more details. - - The default is to restore all available types of data. The option - can be specified multiple times to select some subset. - -``--input=``\ <filename> - Read input from given file instead of stdin. +.. program:: restore + +.. option:: --accumulate + + The union of the existing and new tags is applied, instead of + replacing each message's tags as they are read in from the dump + file. + +.. option:: --format=(sup|batch-tag|auto) + + Notmuch restore supports two plain text dump formats, with each + line specifying a message-id and a set of tags. For details of the + actual formats, see :any:`notmuch-dump(1)`. + + **sup** + The **sup** dump file format is specifically chosen to be + compatible with the format of files produced by sup-dump. So + if you've previously been using sup for mail, then the + **notmuch restore** command provides you a way to import all + of your tags (or labels as sup calls them). + + **batch-tag** + The **batch-tag** dump format is intended to more robust + against malformed message-ids and tags containing whitespace + or non-\ **ascii(7)** characters. See :any:`notmuch-dump(1)` for + details on this format. + + **notmuch restore** updates the maildir flags according to tag + changes if the **maildir.synchronize\_flags** configuration + option is enabled. See :any:`notmuch-config(1)` for details. + + **auto** + This option (the default) tries to guess the format from the + input. For correctly formed input in either supported format, + this heuristic, based the fact that batch-tag format contains + no parentheses, should be accurate. + +.. option:: --include=(config|properties|tags) + + Control what kind of metadata is restored. + + **config** + Restore configuration data to the database. Each configuration + line starts with "#@ ", followed by a space separated + key-value pair. Both key and value are hex encoded if needed. + + **properties** + Restore per-message (key,value) metadata. Each line starts + with "#= ", followed by a message id, and a space separated + list of key=value pairs. Ids, keys and values are hex encoded + if needed. See :any:`notmuch-properties(7)` for more details. + + **tags** + Restore per-message metadata, namely tags. See *format* above + for more details. + + The default is to restore all available types of data. The option + can be specified multiple times to select some subset. + +.. option:: --input=<filename> + + Read input from given file instead of stdin. GZIPPED INPUT ============= diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index 689f027ab3df..2d9ca2d5abec 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -26,118 +26,128 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for Supported options for **search** include -``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) - Presents the results in either JSON, S-Expressions, newline - character separated plain-text (default), or null character - separated plain-text (compatible with :manpage:`xargs(1)` -0 - option where available). - -``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke :any:`notmuch(1)` internally. If - omitted, the latest supported version will be used. - -``--output=(summary|threads|messages|files|tags)`` - **summary** - Output a summary of each thread with any message matching the - search terms. The summary includes the thread ID, date, the - number of messages in the thread (both the number matched and - the total number), the authors of the thread and the - subject. In the case where a thread contains multiple files - for some messages, the total number of files is printed in - parentheses (see below for an example). - - **threads** - Output the thread IDs of all threads with any message matching - the search terms, either one per line (``--format=text``), - separated by null characters (``--format=text0``), as a JSON array - (``--format=json``), or an S-Expression list (``--format=sexp``). - - **messages** - Output the message IDs of all messages matching the search - terms, either one per line (``--format=text``), separated by null - characters (``--format=text0``), as a JSON array (``--format=json``), - or as an S-Expression list (``--format=sexp``). - - **files** - Output the filenames of all messages matching the search - terms, either one per line (``--format=text``), separated by null - characters (``--format=text0``), as a JSON array (``--format=json``), - or as an S-Expression list (``--format=sexp``). - - Note that each message may have multiple filenames associated - with it. All of them are included in the output (unless - limited with the ``--duplicate=N`` option). This may be - particularly confusing for **folder:** or **path:** searches - in a specified directory, as the messages may have duplicates - in other directories that are included in the output, although - these files alone would not match the search. - - **tags** - Output all tags that appear on any message matching the search - terms, either one per line (``--format=text``), separated by null - characters (``--format=text0``), as a JSON array (``--format=json``), - or as an S-Expression list (``--format=sexp``). - -``--sort=``\ (**newest-first**\ \|\ **oldest-first**) - This option can be used to present results in either chronological - order (**oldest-first**) or reverse chronological order - (**newest-first**). - - Note: The thread order will be distinct between these two options - (beyond being simply reversed). When sorting by **oldest-first** - the threads will be sorted by the oldest message in each thread, - but when sorting by **newest-first** the threads will be sorted by - the newest message in each thread. - - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed first). - -``--offset=[-]N`` - Skip displaying the first N results. With the leading '-', start - at the Nth result from the end. - -``--limit=N`` - Limit the number of displayed results to N. - -``--exclude=(true|false|all|flag)`` - A message is called "excluded" if it matches at least one tag in - search.exclude\_tags that does not appear explicitly in the search - terms. This option specifies whether to omit excluded messages in - the search process. - - **true** (default) - Prevent excluded messages from matching the search terms. - - **all** - Additionally prevent excluded messages from appearing in - displayed results, in effect behaving as though the excluded - messages do not exist. - - **false** - Allow excluded messages to match search terms and appear in - displayed results. Excluded messages are still marked in the - relevant outputs. - - **flag** - Only has an effect when ``--output=summary``. The output is - almost identical to **false**, but the "match count" is the - number of matching non-excluded messages in the thread, rather - than the number of matching messages. - -``--duplicate=N`` - For ``--output=files``, output the Nth filename associated with - each message matching the query (N is 1-based). If N is greater - than the number of files associated with the message, don't print - anything. - - For ``--output=messages``, only output message IDs of messages - matching the search terms that have at least N filenames - associated with them. - - Note that this option is orthogonal with the **folder:** search - prefix. The prefix matches messages based on filenames. This - option filters filenames of the matching messages. +.. program:: search + +.. option:: --format=(json|sexp|text|text0) + + Presents the results in either JSON, S-Expressions, newline + character separated plain-text (default), or null character + separated plain-text (compatible with :manpage:`xargs(1)` -0 + option where available). + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --output=(summary|threads|messages|files|tags) + + **summary** + Output a summary of each thread with any message matching the + search terms. The summary includes the thread ID, date, the + number of messages in the thread (both the number matched and + the total number), the authors of the thread and the + subject. In the case where a thread contains multiple files + for some messages, the total number of files is printed in + parentheses (see below for an example). + + **threads** + Output the thread IDs of all threads with any message matching + the search terms, either one per line (``--format=text``), + separated by null characters (``--format=text0``), as a JSON array + (``--format=json``), or an S-Expression list (``--format=sexp``). + + **messages** + Output the message IDs of all messages matching the search + terms, either one per line (``--format=text``), separated by null + characters (``--format=text0``), as a JSON array (``--format=json``), + or as an S-Expression list (``--format=sexp``). + + **files** + Output the filenames of all messages matching the search + terms, either one per line (``--format=text``), separated by null + characters (``--format=text0``), as a JSON array (``--format=json``), + or as an S-Expression list (``--format=sexp``). + + Note that each message may have multiple filenames associated + with it. All of them are included in the output (unless + limited with the ``--duplicate=N`` option). This may be + particularly confusing for **folder:** or **path:** searches + in a specified directory, as the messages may have duplicates + in other directories that are included in the output, although + these files alone would not match the search. + + **tags** + Output all tags that appear on any message matching the search + terms, either one per line (``--format=text``), separated by null + characters (``--format=text0``), as a JSON array (``--format=json``), + or as an S-Expression list (``--format=sexp``). + +.. option:: --sort=(newest-first|oldest-first) + + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). + + Note: The thread order will be distinct between these two options + (beyond being simply reversed). When sorting by **oldest-first** + the threads will be sorted by the oldest message in each thread, + but when sorting by **newest-first** the threads will be sorted by + the newest message in each thread. + + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). + +.. option:: --offset=[-]N + + Skip displaying the first N results. With the leading '-', start + at the Nth result from the end. + +.. option:: --limit=N + + Limit the number of displayed results to N. + +.. option:: --exclude=(true|false|all|flag) + + A message is called "excluded" if it matches at least one tag in + search.exclude\_tags that does not appear explicitly in the search + terms. This option specifies whether to omit excluded messages in + the search process. + + **true** (default) + Prevent excluded messages from matching the search terms. + + **all** + Additionally prevent excluded messages from appearing in + displayed results, in effect behaving as though the excluded + messages do not exist. + + **false** + Allow excluded messages to match search terms and appear in + displayed results. Excluded messages are still marked in the + relevant outputs. + + **flag** + Only has an effect when ``--output=summary``. The output is + almost identical to **false**, but the "match count" is the + number of matching non-excluded messages in the thread, rather + than the number of matching messages. + +.. option:: --duplicate=N + + For ``--output=files``, output the Nth filename associated with + each message matching the query (N is 1-based). If N is greater + than the number of files associated with the message, don't print + anything. + + For ``--output=messages``, only output message IDs of messages + matching the search terms that have at least N filenames + associated with them. + + Note that this option is orthogonal with the **folder:** search + prefix. The prefix matches messages based on filenames. This + option filters filenames of the matching messages. EXAMPLE ======= diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 1291884f61fd..fc6bec62ab26 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -25,172 +25,183 @@ post-processor (such as the emacs interface to notmuch). Supported options for **show** include -``--entire-thread=(true|false)`` - If true, **notmuch show** outputs all messages in the thread of - any message matching the search terms; if false, it outputs only - the matching messages. For ``--format=json`` and ``--format=sexp`` - this defaults to true. For other formats, this defaults to false. - -``--format=(text|json|sexp|mbox|raw)`` - **text** (default for messages) - The default plain-text format has all text-content MIME parts - decoded. Various components in the output, (**message**, - **header**, **body**, **attachment**, and MIME **part**), will - be delimited by easily-parsed markers. Each marker consists of - a Control-L character (ASCII decimal 12), the name of the - marker, and then either an opening or closing brace, ('{' or - '}'), to either open or close the component. For a multipart - MIME message, these parts will be nested. - - **json** - The output is formatted with Javascript Object Notation - (JSON). This format is more robust than the text format for - automated processing. The nested structure of multipart MIME - messages is reflected in nested JSON output. By default JSON - output includes all messages in a matching thread; that is, by - default, ``--format=json`` sets ``--entire-thread``. The - caller can disable this behaviour by setting - ``--entire-thread=false``. The JSON output is always encoded - as UTF-8 and any message content included in the output will - be charset-converted to UTF-8. - - **sexp** - The output is formatted as the Lisp s-expression (sexp) - equivalent of the JSON format above. Objects are formatted as - property lists whose keys are keywords (symbols preceded by a - colon). True is formatted as ``t`` and both false and null are - formatted as ``nil``. As for JSON, the s-expression output is - always encoded as UTF-8. - - **mbox** - All matching messages are output in the traditional, Unix mbox - format with each message being prefixed by a line beginning - with "From " and a blank line separating each message. Lines - in the message content beginning with "From " (preceded by - zero or more '>' characters) have an additional '>' character - added. This reversible escaping is termed "mboxrd" format and - described in detail here: - - http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html - - **raw** (default if ``--part`` is given) - Write the raw bytes of the given MIME part of a message to - standard out. For this format, it is an error to specify a - query that matches more than one message. - - If the specified part is a leaf part, this outputs the body of - the part after performing content transfer decoding (but no - charset conversion). This is suitable for saving attachments, - for example. - - For a multipart or message part, the output includes the part - headers as well as the body (including all child parts). No - decoding is performed because multipart and message parts - cannot have non-trivial content transfer encoding. Consumers - of this may need to implement MIME decoding and similar - functions. - -``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke :any:`notmuch(1)` internally. If - omitted, the latest supported version will be used. - -``--part=N`` - Output the single decoded MIME part N of a single message. The - search terms must match only a single message. Message parts are - numbered in a depth-first walk of the message MIME structure, and - are identified in the 'json', 'sexp' or 'text' output formats. - - Note that even a message with no MIME structure or a single body - part still has two MIME parts: part 0 is the whole message - (headers and body) and part 1 is just the body. - -``--verify`` - Compute and report the validity of any MIME cryptographic - signatures found in the selected content (e.g., "multipart/signed" - parts). Status of the signature will be reported (currently only - supported with ``--format=json`` and ``--format=sexp``), and the - multipart/signed part will be replaced by the signed data. - -``--decrypt=(false|auto|true|stash)`` - If ``true``, decrypt any MIME encrypted parts found in the - selected content (e.g., "multipart/encrypted" parts). Status of - the decryption will be reported (currently only supported - with ``--format=json`` and ``--format=sexp``) and on successful - decryption the multipart/encrypted part will be replaced by - the decrypted content. - - ``stash`` behaves like ``true``, but upon successful decryption it - will also stash the message's session key in the database, and - index the cleartext of the message, enabling automatic decryption - in the future. - - If ``auto``, and a session key is already known for the - message, then it will be decrypted, but notmuch will not try - to access the user's keys. - - Use ``false`` to avoid even automatic decryption. - - Non-automatic decryption (``stash`` or ``true``, in the absence of - a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to - provide any needed credentials. Without one, the decryption will - fail. - - Note: setting either ``true`` or ``stash`` here implies - ``--verify``. - - Here is a table that summarizes each of these policies: - - +------------------------+-------+------+------+-------+ - | | false | auto | true | stash | - +========================+=======+======+======+=======+ - | Show cleartext if | | X | X | X | - | session key is | | | | | - | already known | | | | | - +------------------------+-------+------+------+-------+ - | Use secret keys to | | | X | X | - | show cleartext | | | | | - +------------------------+-------+------+------+-------+ - | Stash any newly | | | | X | - | recovered session keys,| | | | | - | reindexing message if | | | | | - | found | | | | | - +------------------------+-------+------+------+-------+ - - Note: ``--decrypt=stash`` requires write access to the database. - Otherwise, ``notmuch show`` operates entirely in read-only mode. - - Default: ``auto`` - -``--exclude=(true|false)`` - Specify whether to omit threads only matching search.exclude\_tags - from the search results (the default) or not. In either case the - excluded message will be marked with the exclude flag (except when - output=mbox when there is nowhere to put the flag). - - If ``--entire-thread`` is specified then complete threads are returned - regardless (with the excluded flag being set when appropriate) but - threads that only match in an excluded message are not returned - when ``--exclude=true.`` - - The default is ``--exclude=true.`` - -``--body=(true|false)`` - If true (the default) **notmuch show** includes the bodies of the - messages in the output; if false, bodies are omitted. - ``--body=false`` is only implemented for the text, json and sexp - formats and it is incompatible with ``--part > 0.`` - - This is useful if the caller only needs the headers as body-less - output is much faster and substantially smaller. - -``--include-html`` - Include "text/html" parts as part of the output (currently - only supported with ``--format=text``, ``--format=json`` and - ``--format=sexp``). By default, unless ``--part=N`` is used to - select a specific part or ``--include-html`` is used to include all - "text/html" parts, no part with content type "text/html" is included - in the output. +.. program:: show + +.. option:: --entire-thread=(true|false) + + If true, **notmuch show** outputs all messages in the thread of + any message matching the search terms; if false, it outputs only + the matching messages. For ``--format=json`` and ``--format=sexp`` + this defaults to true. For other formats, this defaults to false. + +.. option:: --format=(text|json|sexp|mbox|raw) + + **text** (default for messages) + The default plain-text format has all text-content MIME parts + decoded. Various components in the output, (**message**, + **header**, **body**, **attachment**, and MIME **part**), will + be delimited by easily-parsed markers. Each marker consists of + a Control-L character (ASCII decimal 12), the name of the + marker, and then either an opening or closing brace, ('{' or + '}'), to either open or close the component. For a multipart + MIME message, these parts will be nested. + + **json** + The output is formatted with Javascript Object Notation + (JSON). This format is more robust than the text format for + automated processing. The nested structure of multipart MIME + messages is reflected in nested JSON output. By default JSON + output includes all messages in a matching thread; that is, by + default, ``--format=json`` sets ``--entire-thread``. The + caller can disable this behaviour by setting + ``--entire-thread=false``. The JSON output is always encoded + as UTF-8 and any message content included in the output will + be charset-converted to UTF-8. + + **sexp** + The output is formatted as the Lisp s-expression (sexp) + equivalent of the JSON format above. Objects are formatted as + property lists whose keys are keywords (symbols preceded by a + colon). True is formatted as ``t`` and both false and null are + formatted as ``nil``. As for JSON, the s-expression output is + always encoded as UTF-8. + + **mbox** + All matching messages are output in the traditional, Unix mbox + format with each message being prefixed by a line beginning + with "From " and a blank line separating each message. Lines + in the message content beginning with "From " (preceded by + zero or more '>' characters) have an additional '>' character + added. This reversible escaping is termed "mboxrd" format and + described in detail here: + + http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html + + **raw** (default if ``--part`` is given) + Write the raw bytes of the given MIME part of a message to + standard out. For this format, it is an error to specify a + query that matches more than one message. + + If the specified part is a leaf part, this outputs the body of + the part after performing content transfer decoding (but no + charset conversion). This is suitable for saving attachments, + for example. + + For a multipart or message part, the output includes the part + headers as well as the body (including all child parts). No + decoding is performed because multipart and message parts + cannot have non-trivial content transfer encoding. Consumers + of this may need to implement MIME decoding and similar + functions. + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --part=N + + Output the single decoded MIME part N of a single message. The + search terms must match only a single message. Message parts are + numbered in a depth-first walk of the message MIME structure, and + are identified in the 'json', 'sexp' or 'text' output formats. + + Note that even a message with no MIME structure or a single body + part still has two MIME parts: part 0 is the whole message + (headers and body) and part 1 is just the body. + +.. option:: --verify + + Compute and report the validity of any MIME cryptographic + signatures found in the selected content (e.g., "multipart/signed" + parts). Status of the signature will be reported (currently only + supported with ``--format=json`` and ``--format=sexp``), and the + multipart/signed part will be replaced by the signed data. + +.. option:: --decrypt=(false|auto|true|stash) + + If ``true``, decrypt any MIME encrypted parts found in the + selected content (e.g., "multipart/encrypted" parts). Status of + the decryption will be reported (currently only supported + with ``--format=json`` and ``--format=sexp``) and on successful + decryption the multipart/encrypted part will be replaced by + the decrypted content. + + ``stash`` behaves like ``true``, but upon successful decryption it + will also stash the message's session key in the database, and + index the cleartext of the message, enabling automatic decryption + in the future. + + If ``auto``, and a session key is already known for the + message, then it will be decrypted, but notmuch will not try + to access the user's keys. + + Use ``false`` to avoid even automatic decryption. + + Non-automatic decryption (``stash`` or ``true``, in the absence of + a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to + provide any needed credentials. Without one, the decryption will + fail. + + Note: setting either ``true`` or ``stash`` here implies + ``--verify``. + + Here is a table that summarizes each of these policies: + + +------------------------+-------+------+------+-------+ + | | false | auto | true | stash | + +========================+=======+======+======+=======+ + | Show cleartext if | | X | X | X | + | session key is | | | | | + | already known | | | | | + +------------------------+-------+------+------+-------+ + | Use secret keys to | | | X | X | + | show cleartext | | | | | + +------------------------+-------+------+------+-------+ + | Stash any newly | | | | X | + | recovered session keys,| | | | | + | reindexing message if | | | | | + | found | | | | | + +------------------------+-------+------+------+-------+ + + Note: ``--decrypt=stash`` requires write access to the database. + Otherwise, ``notmuch show`` operates entirely in read-only mode. + + Default: ``auto`` + +.. option:: --exclude=(true|false) + + Specify whether to omit threads only matching search.exclude\_tags + from the search results (the default) or not. In either case the + excluded message will be marked with the exclude flag (except when + output=mbox when there is nowhere to put the flag). + + If ``--entire-thread`` is specified then complete threads are returned + regardless (with the excluded flag being set when appropriate) but + threads that only match in an excluded message are not returned + when ``--exclude=true.`` + + The default is ``--exclude=true.`` + +.. option:: --body=(true|false) + + If true (the default) **notmuch show** includes the bodies of the + messages in the output; if false, bodies are omitted. + ``--body=false`` is only implemented for the text, json and sexp + formats and it is incompatible with ``--part > 0.`` + + This is useful if the caller only needs the headers as body-less + output is much faster and substantially smaller. + +.. option:: --include-html + + Include "text/html" parts as part of the output (currently + only supported with ``--format=text``, ``--format=json`` and + ``--format=sexp``). By default, unless ``--part=N`` is used to + select a specific part or ``--include-html`` is used to include all + "text/html" parts, no part with content type "text/html" is included + in the output. A common use of **notmuch show** is to display a single thread of email messages. For this, use a search term of "thread:<thread-id>" as diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst index 1da876c5c8cb..ae311a230f55 100644 --- a/doc/man1/notmuch-tag.rst +++ b/doc/man1/notmuch-tag.rst @@ -34,22 +34,27 @@ the **maildir.synchronize\_flags** configuration option is enabled. See Supported options for **tag** include -``--remove-all`` - Remove all tags from each message matching the search terms before - applying the tag changes appearing on the command line. This - means setting the tags of each message to the tags to be added. If - there are no tags to be added, the messages will have no tags. - -``--batch`` - Read batch tagging operations from a file (stdin by default). - This is more efficient than repeated **notmuch tag** - invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for - the input format. This option is not compatible with specifying - tagging on the command line. - -``--input=``\ <filename> - Read input from given file, instead of from stdin. Implies - ``--batch``. +.. program:: tag + +.. option:: --remove-all + + Remove all tags from each message matching the search terms before + applying the tag changes appearing on the command line. This + means setting the tags of each message to the tags to be added. If + there are no tags to be added, the messages will have no tags. + +.. option:: --batch + + Read batch tagging operations from a file (stdin by default). + This is more efficient than repeated **notmuch tag** + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for + the input format. This option is not compatible with specifying + tagging on the command line. + +.. option:: --input=<filename> + + Read input from given file, instead of from stdin. Implies + ``--batch``. TAG FILE FORMAT =============== diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 93135bdd6abb..e7adcfcd7ff5 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -43,25 +43,31 @@ OPTIONS Supported global options for ``notmuch`` include -``--help`` [command-name] - Print a synopsis of available commands and exit. With an optional - command name, show the man page for that subcommand. - -``--version`` - Print the installed version of notmuch, and exit. - -``--config=FILE`` - Specify the configuration file to use. This overrides any - configuration file specified by :envvar:`NOTMUCH_CONFIG`. The empty - string is a permitted and sometimes useful value of *FILE*, which - tells ``notmuch`` to use only configuration metadata from the database. - -``--uuid=HEX`` - Enforce that the database UUID (a unique identifier which persists - until e.g. the database is compacted) is HEX; exit with an error - if it is not. This is useful to detect rollover in modification - counts on messages. You can find this UUID using e.g. ``notmuch - count --lastmod`` +.. program:: notmuch + +.. option:: --help [command-name] + + Print a synopsis of available commands and exit. With an optional + command name, show the man page for that subcommand. + +.. option:: --version + + Print the installed version of notmuch, and exit. + +.. option:: --config=FILE + + Specify the configuration file to use. This overrides any + configuration file specified by :envvar:`NOTMUCH_CONFIG`. The empty + string is a permitted and sometimes useful value of *FILE*, which + tells ``notmuch`` to use only configuration metadata from the database. + +.. option:: --uuid=HEX + + Enforce that the database UUID (a unique identifier which persists + until e.g. the database is compacted) is HEX; exit with an error + if it is not. This is useful to detect rollover in modification + counts on messages. You can find this UUID using e.g. ``notmuch + count --lastmod`` All global options except ``--config`` can also be specified after the command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent -- 2.30.2 _______________________________________________ notmuch mailing list -- notmuch@notmuchmail.org To unsubscribe send an email to notmuch-leave@notmuchmail.org