mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-21 18:38:08 +01:00
doc: use program and option directives to document options
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
David Bremner
parent
574b2436ee
commit
f2e2f2aa96
15 changed files with 740 additions and 635 deletions
|
|
@ -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
|
||||||
===========
|
===========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
========
|
========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
========
|
========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
========
|
========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
===========
|
===========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
===========
|
===========
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
========
|
========
|
||||||
|
|
|
||||||
|
|
@ -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>.
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
=============
|
=============
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
=======
|
=======
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
===============
|
===============
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue