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