debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-25 04:18:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: use program and option directives to document options

Browse source 
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.
This commit is contained in:
Jani Nikula 2021-05-21 23:44:12 +03:00 committed by David Bremner
parent 574b2436ee
commit f2e2f2aa96
15 changed files with 740 additions and 635 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

138
doc/man1/notmuch-address.rst
View file

@ -20,89 +20,97 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
Supported options for **address** include Supported options for **address** include
``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) .. program:: address
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`` .. option:: --format=(json|sexp|text|text0)
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)`` Presents the results in either JSON, S-Expressions, newline
Controls which information appears in the output. This option can character separated plain-text (default), or null character
be given multiple times to combine different outputs. When separated plain-text (compatible with :manpage:`xargs(1)` -0
neither ``--output=sender`` nor ``--output=recipients`` is option where available).
given, ``--output=sender`` is implied.
**sender** .. option:: --format-version=N
Output all addresses from the *From* header.
Note: Searching for **sender** should be much faster than Use the specified structured output format version. This is
searching for **recipients**, because sender addresses are intended for programs that invoke :any:`notmuch(1)` internally. If
cached directly in the database whereas other addresses need omitted, the latest supported version will be used.
to be fetched from message files.
**recipients** .. option:: --output=(sender|recipients|count|address)
Output all addresses from the *To*, *Cc* and *Bcc* headers.
**count** Controls which information appears in the output. This option can
Print the count of how many times was the address encountered be given multiple times to combine different outputs. When
during search. neither ``--output=sender`` nor ``--output=recipients`` is
given, ``--output=sender`` is implied.
Note: With this option, addresses are printed only after the **sender**
whole search is finished. This may take long time. Output all addresses from the *From* header.
**address** Note: Searching for **sender** should be much faster than
Output only the email addresses instead of the full mailboxes searching for **recipients**, because sender addresses are
with names and email addresses. This option has no effect on cached directly in the database whereas other addresses need
the JSON or S-Expression output formats. to be fetched from message files.
``--deduplicate=(no|mailbox|address)`` **recipients**
Control the deduplication of results. Output all addresses from the *To*, *Cc* and *Bcc* headers.
**no** **count**
Output all occurrences of addresses in the matching Print the count of how many times was the address encountered
messages. This is not applicable with ``--output=count``. during search.
**mailbox** Note: With this option, addresses are printed only after the
Deduplicate addresses based on the full, case sensitive name whole search is finished. This may take long time.
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** **address**
Deduplicate addresses based on the case insensitive address Output only the email addresses instead of the full mailboxes
part of the mailbox. Of all the variants (with different name with names and email addresses. This option has no effect on
or case), print the one occurring most frequently among the the JSON or S-Expression output formats.
matching messages. If ``--output=count`` is specified, include all
variants in the count.
``--sort=``\ (**newest-first**\ \|\ **oldest-first**) .. option:: --deduplicate=(no|mailbox|address)
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 Control the deduplication of results.
order, (that is, the newest results will be displayed first).
However, if either ``--output=count`` or ``--deduplicate=address`` is **no**
specified, this option is ignored and the order of the results is Output all occurrences of addresses in the matching
unspecified. messages. This is not applicable with ``--output=count``.
``--exclude=(true|false)`` **mailbox**
A message is called "excluded" if it matches at least one tag in Deduplicate addresses based on the full, case sensitive name
search.exclude\_tags that does not appear explicitly in the search and email address, or mailbox. This is effectively the same as
terms. This option specifies whether to omit excluded messages in piping the ``--deduplicate=no`` output to **sort | uniq**, except
the search process. for the order of results. This is the default.
The default value, **true**, prevents excluded messages from **address**
matching the search terms. 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.
**false** allows excluded messages to match search terms and .. option:: --sort=(newest-first|oldest-first)
appear in displayed results.
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 EXIT STATUS
=========== ===========

18
doc/man1/notmuch-compact.rst
View file

@ -26,14 +26,18 @@ process (which may be quite long) to protect data integrity.
Supported options for **compact** include Supported options for **compact** include
``--backup=``\ <directory> .. program:: compact
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`` .. option:: --backup=<directory>
Do not report database compaction progress to stdout.
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 SEE ALSO
======== ========

45
doc/man1/notmuch-config.rst
View file

@ -19,32 +19,37 @@ DESCRIPTION
The **config** command can be used to get or set settings in the notmuch The **config** command can be used to get or set settings in the notmuch
configuration file and corresponding database. configuration file and corresponding database.
**get** .. program:: config
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.
**set** .. option:: get
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.
If no values are provided, the specified configuration item will The value of the specified configuration item is printed to
be removed from the configuration file. 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 .. option:: set
stored in the database, rather than the default (text)
configuration file.
**list** The specified configuration item is set to the given value. To
Every configuration item is printed to stdout, each on a separate specify a multiple-value item (a list), provide each value as a
line of the form:: 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 With the `--database` option, updates configuration metadata
characters. In a multiple-value item (a list), the values are stored in the database, rather than the default (text)
separated by semicolon characters. 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 The available configuration items are described below. Non-absolute
paths are presumed relative to `$HOME` for items in section paths are presumed relative to `$HOME` for items in section

59
doc/man1/notmuch-count.rst
View file

@ -24,38 +24,45 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
Supported options for **count** include Supported options for **count** include
``--output=(messages|threads|files)`` .. program:: count
**messages**
Output the number of matching messages. This is the default.
**threads** .. option:: --output=(messages|threads|files)
Output the number of matching threads.
**files** **messages**
Output the number of files associated with matching Output the number of matching messages. This is the default.
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)`` **threads**
Specify whether to omit messages matching search.exclude\_tags from Output the number of matching threads.
the count (the default) or not.
``--batch`` **files**
Read queries from a file (stdin by default), one per line, and Output the number of files associated with matching
output the number of matching messages (or threads) to stdout, one messages. This may be bigger than the number of matching
per line. On an empty input line the count of all messages (or messages due to duplicates (i.e. multiple files having the
threads) in the database will be output. This option is not same message-id).
compatible with specifying search terms on the command line.
``--lastmod`` .. option:: --exclude=(true|false)
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> Specify whether to omit messages matching search.exclude\_tags from
Read input from given file, instead of from stdin. Implies the count (the default) or not.
``--batch``.
.. 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 SEE ALSO
======== ========

116
doc/man1/notmuch-dump.rst
View file

@ -28,76 +28,82 @@ the remaining arguments are search terms.
Supported options for **dump** include Supported options for **dump** include
``--gzip`` .. program:: dump
Compress the output in a format compatible with :manpage:`gzip(1)`.
``--format=(sup|batch-tag)`` .. option:: --gzip
Notmuch restore supports two plain text dump formats, both with
one message-id per line, followed by a list of tags.
**batch-tag** Compress the output in a format compatible with :manpage:`gzip(1)`.
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*\ > .. option:: --format=(sup|batch-tag)
Tags are hex-encoded by replacing every byte not matching the Notmuch restore supports two plain text dump formats, both with
regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two one message-id per line, followed by a list of tags.
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** **batch-tag**
The **sup** dump file format is specifically chosen to be The default **batch-tag** dump format is intended to more
compatible with the format of files produced by robust against malformed message-ids and tags containing
:manpage:`sup-dump(1)`. So if you've previously been using sup whitespace or non-\ :manpage:`ascii(7)` characters. Each line
for mail, then the :any:`notmuch-restore(1)` command provides has the form::
you a way to import all of your tags (or labels as sup calls
them). Each line has the following form::
<*message-id*\ > **(** <*tag*\ > ... **)** +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ >
with zero or more tags are separated by spaces. Note that Tags are hex-encoded by replacing every byte not matching the
(malformed) message-ids may contain arbitrary non-null regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
characters. Note also that tags with spaces will not be digit hex encoding. The message ID is a valid Xapian query,
correctly restored with this format. 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)`.
``--include=(config|properties|tags)`` **sup**
Control what kind of metadata is included in the output. 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::
**config** <*message-id*\ > **(** <*tag*\ > ... **)**
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** with zero or more tags are separated by spaces. Note that
Output per-message (key,value) metadata. Each line starts (malformed) message-ids may contain arbitrary non-null
with "#= ", followed by a message id, and a space separated characters. Note also that tags with spaces will not be
list of key=value pairs. Ids, keys and values are hex encoded correctly restored with this format.
if needed. See :any:`notmuch-properties(7)` for more details.
**tags** .. option:: --include=(config|properties|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 Control what kind of metadata is included in the output.
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*> **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.
where <*included*> is a comma separated list of the above options. **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.
``--output=``\ <filename> **tags**
Write output to given file instead of stdout. 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 SEE ALSO
======== ========

80
doc/man1/notmuch-emacs-mua.rst
View file

@ -17,50 +17,64 @@ subject, recipients, and message body, or mailto: URL.
Supported options for **emacs-mua** include Supported options for **emacs-mua** include
``-h, --help`` .. program:: emacs-mua
Display help.
``-s, --subject=``\ <subject> .. option:: -h, --help
Specify the subject of the message.
``--to=``\ <to-address> Display help.
Specify a recipient (To).
``-c, --cc=``\ <cc-address> .. option:: -s, --subject=<subject>
Specify a carbon-copy (Cc) recipient.
``-b, --bcc=``\ <bcc-address> Specify the subject of the message.
Specify a blind-carbon-copy (Bcc) recipient.
``-i, --body=``\ <file> .. option:: --to=<to-address>
Specify a file to include into the body of the message.
``--hello`` Specify a recipient (To).
Go to the Notmuch hello screen instead of the message composition
window if no message composition parameters are given.
``--no-window-system`` .. option:: -c, --cc=<cc-address>
Even if a window system is available, use the current terminal.
``--client`` Specify a carbon-copy (Cc) recipient.
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``.
``--auto-daemon`` .. option:: -b, --bcc=<bcc-address>
Automatically start Emacs in daemon mode, if the Emacs server is
not running. Applicable with ``--client``. Implies
``--create-frame``.
``--create-frame`` Specify a blind-carbon-copy (Bcc) recipient.
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.
``--print`` .. option:: -i, --body=<file>
Output the resulting elisp to stdout instead of evaluating it.
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 The supported positional parameters and short options are a compatible
subset of the :manpage:`mutt(1)` MUA command-line options. The options subset of the :manpage:`mutt(1)` MUA command-line options. The options

84
doc/man1/notmuch-insert.rst
View file

@ -33,52 +33,60 @@ more details on hooks.
Option arguments must appear before any tag operation arguments. Option arguments must appear before any tag operation arguments.
Supported options for **insert** include Supported options for **insert** include
``--folder=<``\ folder\ **>** .. program:: insert
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`` .. option:: --folder=<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`` Deliver the message to the specified folder, relative to the
Keep the message file if indexing fails, and keep the message top-level directory given by the value of **database.path**. The
indexed if applying tags or maildir flag synchronization default is the empty string, which means delivering to the
fails. Ignore these errors and return exit status 0 to indicate top-level directory.
successful mail delivery.
``--no-hooks`` .. option:: --create-folder
Prevent hooks from being run.
``--world-readable`` Try to create the folder named by the ``--folder`` option, if it
When writing mail to the mailbox, allow it to be read by users does not exist. Otherwise the folder must already exist for mail
other than the current user. Note that this does not override delivery to succeed.
umask. By default, delivered mail is only readable by the current
user.
``--decrypt=(true|nostash|auto|false)`` .. option:: --keep
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 Keep the message file if indexing fails, and keep the message
newly-discovered session keys in the database. indexed if applying tags or maildir flag synchronization
fails. Ignore these errors and return exit status 0 to indicate
successful mail delivery.
Be aware that the index is likely sufficient (and a stashed .. option:: --no-hooks
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)`. 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 EXIT STATUS
=========== ===========

55
doc/man1/notmuch-new.rst
View file

@ -40,36 +40,43 @@ details on hooks.
Supported options for **new** include Supported options for **new** include
``--no-hooks`` .. program:: new
Prevents hooks from being run.
``--quiet`` .. option:: --no-hooks
Do not print progress or results.
``--verbose`` Prevents hooks from being run.
Print file names being processed. Ignored when combined with
``--quiet``.
``--decrypt=(true|nostash|auto|false)`` .. option:: --quiet
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 Do not print progress or results.
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:: --verbose
``--full-scan`` Print file names being processed. Ignored when combined with
By default notmuch-new uses directory modification times (mtimes) ``--quiet``.
to optimize the scanning of directories for new mail. This option turns
that optimization off. .. 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 EXIT STATUS
=========== ===========

39
doc/man1/notmuch-reindex.rst
View file

@ -23,28 +23,31 @@ messages using the supplied options.
Supported options for **reindex** include Supported options for **reindex** include
``--decrypt=(true|nostash|auto|false)`` .. program:: reindex
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 .. option:: --decrypt=(true|nostash|auto|false)
newly-discovered session keys in the database.
If ``false``, notmuch reindex will also delete any stashed session If ``true``, when encountering an encrypted message, try to
keys for all messages matching the search terms. 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.
Be aware that the index is likely sufficient (and a stashed ``nostash`` is the same as ``true`` except that it will not stash
session key is certainly sufficient) to reconstruct the cleartext newly-discovered session keys in the database.
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)`. 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 EXAMPLES
======== ========

93
doc/man1/notmuch-reply.rst
View file

@ -36,62 +36,67 @@ The resulting message template is output to stdout.
Supported options for **reply** include Supported options for **reply** include
``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**) .. program:: reply
**default**
Includes subject and quoted message body as an RFC 2822
message.
**json** .. option:: --format=(default|json|sexp|headers-only)
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** **default**
Produces S-Expression output containing headers for a reply Includes subject and quoted message body as an RFC 2822
message and the contents of the original message. This output message.
can be used by a client to create a reply message
intelligently.
**headers-only** **json**
Only produces In-Reply-To, References, To, Cc, and Bcc Produces JSON output containing headers for a reply message
headers. and the contents of the original message. This output can be
used by a client to create a reply message intelligently.
``--format-version=N`` **sexp**
Use the specified structured output format version. This is Produces S-Expression output containing headers for a reply
intended for programs that invoke :any:`notmuch(1)` internally. If message and the contents of the original message. This output
omitted, the latest supported version will be used. can be used by a client to create a reply message
intelligently.
``--reply-to=``\ (**all**\ \|\ **sender**) **headers-only**
**all** (default) Only produces In-Reply-To, References, To, Cc, and Bcc
Replies to all addresses. headers.
**sender** .. option:: --format-version=N
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)`` 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.
If ``true``, decrypt any MIME encrypted parts found in the .. option:: --reply-to=(all|sender)
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 **all** (default)
message, then it will be decrypted, but notmuch will not try Replies to all addresses.
to access the user's secret keys.
Use ``false`` to avoid even automatic decryption. **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.
Non-automatic decryption expects a functioning .. option:: --decrypt=(false|auto|true)
:manpage:`gpg-agent(1)` to provide any needed credentials. Without
one, the decryption will likely fail.
Default: ``auto`` 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 See :any:`notmuch-search-terms(7)` for details of the supported syntax for
<search-terms>. <search-terms>.

96
doc/man1/notmuch-restore.rst
View file

@ -18,62 +18,68 @@ The input is read from the given filename, if any, or from stdin.
Supported options for **restore** include Supported options for **restore** include
``--accumulate`` .. program:: restore
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)`` .. option:: --accumulate
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 union of the existing and new tags is applied, instead of
The **sup** dump file format is specifically chosen to be replacing each message's tags as they are read in from the dump
compatible with the format of files produced by sup-dump. So file.
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** .. option:: --format=(sup|batch-tag|auto)
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 Notmuch restore supports two plain text dump formats, with each
changes if the **maildir.synchronize\_flags** configuration line specifying a message-id and a set of tags. For details of the
option is enabled. See :any:`notmuch-config(1)` for details. actual formats, see :any:`notmuch-dump(1)`.
**auto** **sup**
This option (the default) tries to guess the format from the The **sup** dump file format is specifically chosen to be
input. For correctly formed input in either supported format, compatible with the format of files produced by sup-dump. So
this heuristic, based the fact that batch-tag format contains if you've previously been using sup for mail, then the
no parentheses, should be accurate. **notmuch restore** command provides you a way to import all
of your tags (or labels as sup calls them).
``--include=(config|properties|tags)`` **batch-tag**
Control what kind of metadata is restored. 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.
**config** **notmuch restore** updates the maildir flags according to tag
Restore configuration data to the database. Each configuration changes if the **maildir.synchronize\_flags** configuration
line starts with "#@ ", followed by a space separated option is enabled. See :any:`notmuch-config(1)` for details.
key-value pair. Both key and value are hex encoded if needed.
**properties** **auto**
Restore per-message (key,value) metadata. Each line starts This option (the default) tries to guess the format from the
with "#= ", followed by a message id, and a space separated input. For correctly formed input in either supported format,
list of key=value pairs. Ids, keys and values are hex encoded this heuristic, based the fact that batch-tag format contains
if needed. See :any:`notmuch-properties(7)` for more details. no parentheses, should be accurate.
**tags** .. option:: --include=(config|properties|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 Control what kind of metadata is restored.
can be specified multiple times to select some subset.
``--input=``\ <filename> **config**
Read input from given file instead of stdin. 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 GZIPPED INPUT
============= =============

194
doc/man1/notmuch-search.rst
View file

@ -26,118 +26,128 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
Supported options for **search** include Supported options for **search** include
``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) .. program:: search
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`` .. option:: --format=(json|sexp|text|text0)
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)`` Presents the results in either JSON, S-Expressions, newline
**summary** character separated plain-text (default), or null character
Output a summary of each thread with any message matching the separated plain-text (compatible with :manpage:`xargs(1)` -0
search terms. The summary includes the thread ID, date, the option where available).
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** .. option:: --format-version=N
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** Use the specified structured output format version. This is
Output the message IDs of all messages matching the search intended for programs that invoke :any:`notmuch(1)` internally. If
terms, either one per line (``--format=text``), separated by null omitted, the latest supported version will be used.
characters (``--format=text0``), as a JSON array (``--format=json``),
or as an S-Expression list (``--format=sexp``).
**files** .. option:: --output=(summary|threads|messages|files|tags)
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 **summary**
with it. All of them are included in the output (unless Output a summary of each thread with any message matching the
limited with the ``--duplicate=N`` option). This may be search terms. The summary includes the thread ID, date, the
particularly confusing for **folder:** or **path:** searches number of messages in the thread (both the number matched and
in a specified directory, as the messages may have duplicates the total number), the authors of the thread and the
in other directories that are included in the output, although subject. In the case where a thread contains multiple files
these files alone would not match the search. for some messages, the total number of files is printed in
parentheses (see below for an example).
**tags** **threads**
Output all tags that appear on any message matching the search Output the thread IDs of all threads with any message matching
terms, either one per line (``--format=text``), separated by null the search terms, either one per line (``--format=text``),
characters (``--format=text0``), as a JSON array (``--format=json``), separated by null characters (``--format=text0``), as a JSON array
or as an S-Expression list (``--format=sexp``). (``--format=json``), or an S-Expression list (``--format=sexp``).
``--sort=``\ (**newest-first**\ \|\ **oldest-first**) **messages**
This option can be used to present results in either chronological Output the message IDs of all messages matching the search
order (**oldest-first**) or reverse chronological order terms, either one per line (``--format=text``), separated by null
(**newest-first**). characters (``--format=text0``), as a JSON array (``--format=json``),
or as an S-Expression list (``--format=sexp``).
Note: The thread order will be distinct between these two options **files**
(beyond being simply reversed). When sorting by **oldest-first** Output the filenames of all messages matching the search
the threads will be sorted by the oldest message in each thread, terms, either one per line (``--format=text``), separated by null
but when sorting by **newest-first** the threads will be sorted by characters (``--format=text0``), as a JSON array (``--format=json``),
the newest message in each thread. or as an S-Expression list (``--format=sexp``).
By default, results will be displayed in reverse chronological Note that each message may have multiple filenames associated
order, (that is, the newest results will be displayed first). 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.
``--offset=[-]N`` **tags**
Skip displaying the first N results. With the leading '-', start Output all tags that appear on any message matching the search
at the Nth result from the end. 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``).
``--limit=N`` .. option:: --sort=(newest-first|oldest-first)
Limit the number of displayed results to N.
``--exclude=(true|false|all|flag)`` This option can be used to present results in either chronological
A message is called "excluded" if it matches at least one tag in order (**oldest-first**) or reverse chronological order
search.exclude\_tags that does not appear explicitly in the search (**newest-first**).
terms. This option specifies whether to omit excluded messages in
the search process.
**true** (default) Note: The thread order will be distinct between these two options
Prevent excluded messages from matching the search terms. (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.
**all** By default, results will be displayed in reverse chronological
Additionally prevent excluded messages from appearing in order, (that is, the newest results will be displayed first).
displayed results, in effect behaving as though the excluded
messages do not exist.
**false** .. option:: --offset=[-]N
Allow excluded messages to match search terms and appear in
displayed results. Excluded messages are still marked in the
relevant outputs.
**flag** Skip displaying the first N results. With the leading '-', start
Only has an effect when ``--output=summary``. The output is at the Nth result from the end.
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`` .. option:: --limit=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 Limit the number of displayed results to N.
matching the search terms that have at least N filenames
associated with them.
Note that this option is orthogonal with the **folder:** search .. option:: --exclude=(true|false|all|flag)
prefix. The prefix matches messages based on filenames. This
option filters filenames of the matching messages. 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 EXAMPLE
======= =======

287
doc/man1/notmuch-show.rst
View file

@ -25,172 +25,183 @@ post-processor (such as the emacs interface to notmuch).
Supported options for **show** include Supported options for **show** include
``--entire-thread=(true|false)`` .. program:: show
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)`` .. option:: --entire-thread=(true|false)
**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** If true, **notmuch show** outputs all messages in the thread of
The output is formatted with Javascript Object Notation any message matching the search terms; if false, it outputs only
(JSON). This format is more robust than the text format for the matching messages. For ``--format=json`` and ``--format=sexp``
automated processing. The nested structure of multipart MIME this defaults to true. For other formats, this defaults to false.
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** .. option:: --format=(text|json|sexp|mbox|raw)
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** **text** (default for messages)
All matching messages are output in the traditional, Unix mbox The default plain-text format has all text-content MIME parts
format with each message being prefixed by a line beginning decoded. Various components in the output, (**message**,
with "From " and a blank line separating each message. Lines **header**, **body**, **attachment**, and MIME **part**), will
in the message content beginning with "From " (preceded by be delimited by easily-parsed markers. Each marker consists of
zero or more '>' characters) have an additional '>' character a Control-L character (ASCII decimal 12), the name of the
added. This reversible escaping is termed "mboxrd" format and marker, and then either an opening or closing brace, ('{' or
described in detail here: '}'), to either open or close the component. For a multipart
MIME message, these parts will be nested.
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html **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.
**raw** (default if ``--part`` is given) **sexp**
Write the raw bytes of the given MIME part of a message to The output is formatted as the Lisp s-expression (sexp)
standard out. For this format, it is an error to specify a equivalent of the JSON format above. Objects are formatted as
query that matches more than one message. 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.
If the specified part is a leaf part, this outputs the body of **mbox**
the part after performing content transfer decoding (but no All matching messages are output in the traditional, Unix mbox
charset conversion). This is suitable for saving attachments, format with each message being prefixed by a line beginning
for example. 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:
For a multipart or message part, the output includes the part http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
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`` **raw** (default if ``--part`` is given)
Use the specified structured output format version. This is Write the raw bytes of the given MIME part of a message to
intended for programs that invoke :any:`notmuch(1)` internally. If standard out. For this format, it is an error to specify a
omitted, the latest supported version will be used. query that matches more than one message.
``--part=N`` If the specified part is a leaf part, this outputs the body of
Output the single decoded MIME part N of a single message. The the part after performing content transfer decoding (but no
search terms must match only a single message. Message parts are charset conversion). This is suitable for saving attachments,
numbered in a depth-first walk of the message MIME structure, and for example.
are identified in the 'json', 'sexp' or 'text' output formats.
Note that even a message with no MIME structure or a single body For a multipart or message part, the output includes the part
part still has two MIME parts: part 0 is the whole message headers as well as the body (including all child parts). No
(headers and body) and part 1 is just the body. 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.
``--verify`` .. option:: --format-version=N
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)`` Use the specified structured output format version. This is
If ``true``, decrypt any MIME encrypted parts found in the intended for programs that invoke :any:`notmuch(1)` internally. If
selected content (e.g., "multipart/encrypted" parts). Status of omitted, the latest supported version will be used.
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 .. option:: --part=N
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 Output the single decoded MIME part N of a single message. The
message, then it will be decrypted, but notmuch will not try search terms must match only a single message. Message parts are
to access the user's keys. numbered in a depth-first walk of the message MIME structure, and
are identified in the 'json', 'sexp' or 'text' output formats.
Use ``false`` to avoid even automatic decryption. 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.
Non-automatic decryption (``stash`` or ``true``, in the absence of .. option:: --verify
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 Compute and report the validity of any MIME cryptographic
``--verify``. 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.
Here is a table that summarizes each of these policies: .. option:: --decrypt=(false|auto|true|stash)
+------------------------+-------+------+------+-------+ If ``true``, decrypt any MIME encrypted parts found in the
| | false | auto | true | stash | selected content (e.g., "multipart/encrypted" parts). Status of
+========================+=======+======+======+=======+ the decryption will be reported (currently only supported
| Show cleartext if | | X | X | X | with ``--format=json`` and ``--format=sexp``) and on successful
| session key is | | | | | decryption the multipart/encrypted part will be replaced by
| already known | | | | | the decrypted content.
+------------------------+-------+------+------+-------+
| 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. ``stash`` behaves like ``true``, but upon successful decryption it
Otherwise, ``notmuch show`` operates entirely in read-only mode. will also stash the message's session key in the database, and
index the cleartext of the message, enabling automatic decryption
in the future.
Default: ``auto`` 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.
``--exclude=(true|false)`` Use ``false`` to avoid even automatic decryption.
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 Non-automatic decryption (``stash`` or ``true``, in the absence of
regardless (with the excluded flag being set when appropriate) but a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to
threads that only match in an excluded message are not returned provide any needed credentials. Without one, the decryption will
when ``--exclude=true.`` fail.
The default is ``--exclude=true.`` Note: setting either ``true`` or ``stash`` here implies
``--verify``.
``--body=(true|false)`` Here is a table that summarizes each of these policies:
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. | | 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 | | | | |
+------------------------+-------+------+------+-------+
``--include-html`` Note: ``--decrypt=stash`` requires write access to the database.
Include "text/html" parts as part of the output (currently Otherwise, ``notmuch show`` operates entirely in read-only mode.
only supported with ``--format=text``, ``--format=json`` and
``--format=sexp``). By default, unless ``--part=N`` is used to Default: ``auto``
select a specific part or ``--include-html`` is used to include all
"text/html" parts, no part with content type "text/html" is included .. option:: --exclude=(true|false)
in the output.
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 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 email messages. For this, use a search term of "thread:<thread-id>" as

33
doc/man1/notmuch-tag.rst
View file

@ -34,22 +34,27 @@ the **maildir.synchronize\_flags** configuration option is enabled. See
Supported options for **tag** include Supported options for **tag** include
``--remove-all`` .. program:: tag
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`` .. option:: --remove-all
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> Remove all tags from each message matching the search terms before
Read input from given file, instead of from stdin. Implies applying the tag changes appearing on the command line. This
``--batch``. 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 TAG FILE FORMAT
=============== ===============

38
doc/man1/notmuch.rst
View file

@ -43,25 +43,31 @@ OPTIONS
Supported global options for ``notmuch`` include Supported global options for ``notmuch`` include
``--help`` [command-name] .. program:: notmuch
Print a synopsis of available commands and exit. With an optional
command name, show the man page for that subcommand.
``--version`` .. option:: --help [command-name]
Print the installed version of notmuch, and exit.
``--config=FILE`` Print a synopsis of available commands and exit. With an optional
Specify the configuration file to use. This overrides any command name, show the man page for that subcommand.
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`` .. option:: --version
Enforce that the database UUID (a unique identifier which persists
until e.g. the database is compacted) is HEX; exit with an error Print the installed version of notmuch, and exit.
if it is not. This is useful to detect rollover in modification
counts on messages. You can find this UUID using e.g. ``notmuch .. option:: --config=FILE
count --lastmod``
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 All global options except ``--config`` can also be specified after the
command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent