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
===========
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
========
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
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
========
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
========
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
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
===========
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
===========
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
========
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>.
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
=============
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
=======
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
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
===============
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