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

doc: unify definition list usage across man pages

Browse source 
Make all parameter descriptions etc. use reStructuredText definition
lists with uniform style and indentation. Remove redundant indentation
from around the lists. Remove blank lines between term lines and
definition blocks. Use four spaces for indentation.

This is almost completely whitespace and paragraph reflow changes.
This commit is contained in:
Jani Nikula 2017-12-30 19:16:11 +02:00 committed by David Bremner
parent 0fab493ffe
commit e5e252de55
17 changed files with 721 additions and 773 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

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

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

@ -24,14 +24,14 @@ process (which may be quite long) to protect data integrity.
Supported options for **compact** include Supported options for **compact** include
``--backup=``\ <directory> ``--backup=``\ <directory>
Save the current database to the given directory before Save the current database to the given directory before replacing
replacing it with the compacted database. The backup directory it with the compacted database. The backup directory must not
must not exist and it must reside on the same mounted filesystem exist and it must reside on the same mounted filesystem as the
as the current database. current database.
``--quiet`` ``--quiet``
Do not report database compaction progress to stdout. Do not report database compaction progress to stdout.
ENVIRONMENT ENVIRONMENT
=========== ===========

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

@ -21,203 +21,189 @@ Items marked **[STORED IN DATABASE]** are only in the database. They
should not be placed in the configuration file, and should be accessed should not be placed in the configuration file, and should be accessed
programmatically as described in the SYNOPSIS above. programmatically as described in the SYNOPSIS above.
**get** **get**
The value of the specified configuration item is printed to The value of the specified configuration item is printed to
stdout. If the item has multiple values (it is a list), each stdout. If the item has multiple values (it is a list), each value
value is separated by a newline character. is separated by a newline character.
**set** **set**
The specified configuration item is set to the given value. To The specified configuration item is set to the given value. To
specify a multiple-value item (a list), provide each value as a specify a multiple-value item (a list), provide each value as a
separate command-line argument. separate command-line argument.
If no values are provided, the specified configuration item will If no values are provided, the specified configuration item will
be removed from the configuration file. be removed from the configuration file.
**list** **list**
Every configuration item is printed to stdout, each on a Every configuration item is printed to stdout, each on a separate
separate line of the form: line of the form::
*section*.\ *item*\ =\ *value* *section*.\ *item*\ =\ *value*
No additional whitespace surrounds the dot or equals sign No additional whitespace surrounds the dot or equals sign
characters. In a multiple-value item (a list), the values are characters. In a multiple-value item (a list), the values are
separated by semicolon characters. separated by semicolon characters.
The available configuration items are described below. The available configuration items are described below.
**database.path** **database.path**
The top-level directory where your mail currently exists and to The top-level directory where your mail currently exists and to
where mail will be delivered in the future. Files should be where mail will be delivered in the future. Files should be
individual email messages. Notmuch will store its database individual email messages. Notmuch will store its database within
within a sub-directory of the path configured here named a sub-directory of the path configured here named ``.notmuch``.
``.notmuch``.
Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``. Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
**user.name** **user.name**
Your full name. Your full name.
Default: ``$NAME`` variable if set, otherwise read from Default: ``$NAME`` variable if set, otherwise read from
``/etc/passwd``. ``/etc/passwd``.
**user.primary\_email** **user.primary\_email**
Your primary email address. Your primary email address.
Default: ``$EMAIL`` variable if set, otherwise constructed from the Default: ``$EMAIL`` variable if set, otherwise constructed from
username and hostname of the current machine. the username and hostname of the current machine.
**user.other\_email** **user.other\_email**
A list of other email addresses at which you receive email. A list of other email addresses at which you receive email.
Default: not set. Default: not set.
**new.tags** **new.tags**
A list of tags that will be added to all messages incorporated A list of tags that will be added to all messages incorporated by
by **notmuch new**. **notmuch new**.
Default: ``unread;inbox``. Default: ``unread;inbox``.
**new.ignore** **new.ignore**
A list to specify files and directories that will not be A list to specify files and directories that will not be searched
searched for messages by **notmuch new**. Each entry in the for messages by **notmuch new**. Each entry in the list is either:
list is either:
A file or a directory name, without path, that will be A file or a directory name, without path, that will be ignored,
ignored, regardless of the location in the mail store regardless of the location in the mail store directory hierarchy.
directory hierarchy.
Or: Or:
A regular expression delimited with // that will be matched A regular expression delimited with // that will be matched
against the path of the file or directory relative to the against the path of the file or directory relative to the database
database path. Matching files and directories will be path. Matching files and directories will be ignored. The
ignored. The beginning and end of string must be explictly beginning and end of string must be explictly anchored. For
anchored. For example, /.*/foo$/ would match "bar/foo" and example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
"bar/baz/foo", but not "foo" or "bar/foobar". not "foo" or "bar/foobar".
Default: empty list. Default: empty list.
**search.exclude\_tags** **search.exclude\_tags**
A list of tags that will be excluded from search results by A list of tags that will be excluded from search results by
default. Using an excluded tag in a query will override that default. Using an excluded tag in a query will override that
exclusion. exclusion.
Default: empty list. Note that **notmuch-setup(1)** puts Default: empty list. Note that **notmuch-setup(1)** puts
``deleted;spam`` here when creating new configuration file. ``deleted;spam`` here when creating new configuration file.
**maildir.synchronize\_flags**
If true, then the following maildir flags (in message filenames)
will be synchronized with the corresponding notmuch tags:
+--------+-----------------------------------------------+
| Flag | Tag |
+========+===============================================+
| D | draft |
+--------+-----------------------------------------------+
| F | flagged |
+--------+-----------------------------------------------+
| P | passed |
+--------+-----------------------------------------------+
| R | replied |
+--------+-----------------------------------------------+
| S | unread (added when 'S' flag is not present) |
+--------+-----------------------------------------------+
**maildir.synchronize\_flags** The **notmuch new** command will notice flag changes in filenames
If true, then the following maildir flags (in message filenames) and update tags, while the **notmuch tag** and **notmuch restore**
will be synchronized with the corresponding notmuch tags: commands will notice tag changes and update flags in filenames.
+--------+-----------------------------------------------+ If there have been any changes in the maildir (new messages added,
| Flag | Tag | old ones removed or renamed, maildir flags changed, etc.), it is
+========+===============================================+ advisable to run **notmuch new** before **notmuch tag** or
| D | draft | **notmuch restore** commands to ensure the tag changes are
+--------+-----------------------------------------------+ properly synchronized to the maildir flags, as the commands expect
| F | flagged | the database and maildir to be in sync.
+--------+-----------------------------------------------+
| P | passed |
+--------+-----------------------------------------------+
| R | replied |
+--------+-----------------------------------------------+
| S | unread (added when 'S' flag is not present) |
+--------+-----------------------------------------------+
The **notmuch new** command will notice flag changes in Default: ``true``.
filenames and update tags, while the **notmuch tag** and
**notmuch restore** commands will notice tag changes and update
flags in filenames.
If there have been any changes in the maildir (new messages **crypto.gpg_path**
added, old ones removed or renamed, maildir flags changed, Name (or full path) of gpg binary to use in verification and
etc.), it is advisable to run **notmuch new** before **notmuch decryption of PGP/MIME messages. NOTE: This configuration item is
tag** or **notmuch restore** commands to ensure the tag changes deprecated, and will be ignored if notmuch is built against GMime
are properly synchronized to the maildir flags, as the commands 3.0 or later.
expect the database and maildir to be in sync.
Default: ``true``. Default: ``gpg``.
**crypto.gpg_path** **index.decrypt** **[STORED IN DATABASE]**
Policy for decrypting encrypted messages during indexing. Must be
one of: ``false``, ``auto``, ``nostash``, or ``true``.
Name (or full path) of gpg binary to use in verification and When indexing an encrypted e-mail message, if this variable is set
decryption of PGP/MIME messages. NOTE: This configuration to ``true``, notmuch will try to decrypt the message and index the
item is deprecated, and will be ignored if notmuch is built cleartext, stashing a copy of any discovered session keys for the
against GMime 3.0 or later. message. If ``auto``, it will try to index the cleartext if a
stashed session key is already known for the message (e.g. from a
previous copy), but will not try to access your secret keys. Use
``false`` to avoid decrypting even when a stashed session key is
already present.
Default: ``gpg``. ``nostash`` is the same as ``true`` except that it will not stash
newly-discovered session keys in the database.
**index.decrypt** From the command line (i.e. during **notmuch-new(1)**,
**notmuch-insert(1)**, or **notmuch-reindex(1)**), the user can
override the database's stored decryption policy with the
``--decrypt=`` option.
**[STORED IN DATABASE]** Here is a table that summarizes the functionality of each of these
policies:
Policy for decrypting encrypted messages during indexing. +------------------------+-------+------+---------+------+
Must be one of: ``false``, ``auto``, ``nostash``, or | | false | auto | nostash | true |
``true``. +========================+=======+======+=========+======+
| Index cleartext using | | X | X | X |
| stashed session keys | | | | |
+------------------------+-------+------+---------+------+
| Index cleartext | | | X | X |
| using secret keys | | | | |
+------------------------+-------+------+---------+------+
| Stash session keys | | | | X |
+------------------------+-------+------+---------+------+
| Delete stashed session | X | | | |
| keys on reindex | | | | |
+------------------------+-------+------+---------+------+
When indexing an encrypted e-mail message, if this variable is Stashed session keys are kept in the database as properties
set to ``true``, notmuch will try to decrypt the message and associated with the message. See ``session-key`` in
index the cleartext, stashing a copy of any discovered session **notmuch-properties(7)** for more details about how they can be
keys for the message. If ``auto``, it will try to index the useful.
cleartext if a stashed session key is already known for the message
(e.g. from a previous copy), but will not try to access your
secret keys. Use ``false`` to avoid decrypting even when a
stashed session key is already present.
``nostash`` is the same as ``true`` except that it will not Be aware that the notmuch index is likely sufficient (and a
stash newly-discovered session keys in the database. 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
``index.decrypt=true`` or ``index.decrypt=nostash`` without
considering the security of your index.
From the command line (i.e. during **notmuch-new(1)**, Default: ``auto``.
**notmuch-insert(1)**, or **notmuch-reindex(1)**), the user
can override the database's stored decryption policy with the
``--decrypt=`` option.
Here is a table that summarizes the functionality of each of **built_with.<name>**
these policies: Compile time feature <name>. Current possibilities include
"compact" (see **notmuch-compact(1)**) and "field_processor" (see
**notmuch-search-terms(7)**).
+------------------------+-------+------+---------+------+ **query.<name>** **[STORED IN DATABASE]**
| | false | auto | nostash | true | Expansion for named query called <name>. See
+========================+=======+======+=========+======+ **notmuch-search-terms(7)** for more information about named
| Index cleartext using | | X | X | X | queries.
| stashed session keys | | | | |
+------------------------+-------+------+---------+------+
| Index cleartext | | | X | X |
| using secret keys | | | | |
+------------------------+-------+------+---------+------+
| Stash session keys | | | | X |
+------------------------+-------+------+---------+------+
| Delete stashed session | X | | | |
| keys on reindex | | | | |
+------------------------+-------+------+---------+------+
Stashed session keys are kept in the database as properties
associated with the message. See ``session-key`` in
**notmuch-properties(7)** for more details about how they can
be useful.
Be aware that the notmuch 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
``index.decrypt=true`` or ``index.decrypt=nostash`` without
considering the security of your index.
Default: ``auto``.
**built_with.<name>**
Compile time feature <name>. Current possibilities include
"compact" (see **notmuch-compact(1)**)
and "field_processor" (see **notmuch-search-terms(7)**).
**query.<name>**
**[STORED IN DATABASE]**
Expansion for named query called <name>. See
**notmuch-search-terms(7)** for more information about named
queries.
ENVIRONMENT ENVIRONMENT
=========== ===========

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

@ -22,39 +22,38 @@ See **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)`` ``--output=(messages|threads|files)``
**messages**
Output the number of matching messages. This is the default.
**messages** **threads**
Output the number of matching messages. This is the default. Output the number of matching threads.
**threads** **files**
Output the number of matching threads. 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).
**files** ``--exclude=(true|false)``
Output the number of files associated with matching Specify whether to omit messages matching search.tag\_exclude from
messages. This may be bigger than the number of matching the count (the default) or not.
messages due to duplicates (i.e. multiple files having the
same message-id).
``--exclude=(true|false)`` ``--batch``
Specify whether to omit messages matching search.tag\_exclude Read queries from a file (stdin by default), one per line, and
from the count (the default) or not. 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.
``--batch`` ``--lastmod``
Read queries from a file (stdin by default), one per line, and Append lastmod (counter for number of database updates) and UUID
output the number of matching messages (or threads) to stdout, to the output. lastmod values are only comparable between
one per line. On an empty input line the count of all messages databases with the same UUID.
(or threads) in the database will be output. This option is not
compatible with specifying search terms on the command line.
``--lastmod`` ``--input=``\ <filename>
Append lastmod (counter for number of database updates) and UUID Read input from given file, instead of from stdin. Implies
to the output. lastmod values are only comparable between databases ``--batch``.
with the same UUID.
``--input=``\ <filename>
Read input from given file, instead of from stdin. Implies
``--batch``.
SEE ALSO SEE ALSO
======== ========

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

@ -26,86 +26,76 @@ the remaining arguments are search terms.
Supported options for **dump** include Supported options for **dump** include
``--gzip`` ``--gzip``
Compress the output in a format compatible with **gzip(1)**. Compress the output in a format compatible with **gzip(1)**.
``--format=(sup|batch-tag)`` ``--format=(sup|batch-tag)``
Notmuch restore supports two plain text dump formats, both with one Notmuch restore supports two plain text dump formats, both with
message-id per line, followed by a list of tags. one message-id per line, followed by a list of tags.
**batch-tag** **batch-tag**
The default **batch-tag** dump format is intended to more
robust against malformed message-ids and tags containing
whitespace or non-\ **ascii(7)** characters. Each line has the
form::
The default **batch-tag** dump format is intended to more +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ >
robust against malformed message-ids and tags containing
whitespace or non-\ **ascii(7)** characters. Each line has
the form
+<*encoded-tag*\ > +<*encoded-tag*\ > ... -- Tags are hex-encoded by replacing every byte not matching the
id:<*quoted-message-id*\ > 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
**notmuch-tag(1)**; note that the single message-id query is
mandatory for **notmuch-restore(1)**.
Tags are hex-encoded by replacing every byte not matching **sup**
the regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is The **sup** dump file format is specifically chosen to be
the two digit hex encoding. The message ID is a valid compatible with the format of files produced by sup-dump. So
Xapian query, quoted using Xapian boolean term quoting if you've previously been using sup for mail, then the
rules: if the ID contains whitespace or a close paren or **notmuch restore** command provides you a way to import all
starts with a double quote, it must be enclosed in double of your tags (or labels as sup calls them). Each line has the
quotes and double quotes inside the ID must be following form::
doubled. The astute reader will notice this is a special
case of the batch input format for **notmuch-tag(1)**;
note that the single message-id query is mandatory for
**notmuch-restore(1)**.
**sup** <*message-id*\ > **(** <*tag*\ > ... **)**
The **sup** dump file format is specifically chosen to be with zero or more tags are separated by spaces. Note that
compatible with the format of files produced by (malformed) message-ids may contain arbitrary non-null
sup-dump. So if you've previously been using sup for mail, characters. Note also that tags with spaces will not be
then the **notmuch restore** command provides you a way to correctly restored with this format.
import all of your tags (or labels as sup calls
them). Each line has the following form
<*message-id*\ > **(** <*tag*\ > ... **)**
with zero or more tags are separated by spaces. Note that
(malformed) message-ids may contain arbitrary non-null
characters. Note also that tags with spaces will not be
correctly restored with this format.
``--include=(config|properties|tags)``
``--include=(config|properties|tags)``
Control what kind of metadata is included in the output. Control what kind of metadata is included in the output.
**config** **config**
Output configuration data stored in the database. Each line Output configuration data stored in the database. Each line
starts with "#@ ", followed by a space separated key-value starts with "#@ ", followed by a space separated key-value
pair. Both key and value are hex encoded if needed. pair. Both key and value are hex encoded if needed.
**properties** **properties**
Output per-message (key,value) metadata. Each line starts Output per-message (key,value) metadata. Each line starts
with "#= ", followed by a message id, and a space separated with "#= ", followed by a message id, and a space separated
list of key=value pairs. Ids, keys and values are hex encoded list of key=value pairs. Ids, keys and values are hex encoded
if needed. See **notmuch-properties(7)** for more details. if needed. See **notmuch-properties(7)** for more details.
**tags** **tags**
Output per-message boolean metadata, namely tags. See *format* above Output per-message boolean metadata, namely tags. See *format* above
for description of the output. for description of the output.
The default is to include all available types of data. The The default is to include all available types of data. The option
option can be specified multiple times to select some subset. As can be specified multiple times to select some subset. As of
of version 3 of the dump format, there is a header line of the version 3 of the dump format, there is a header line of the
following form following form::
| #notmuch-dump <*format*>:<*version*> <*included*>
| #notmuch-dump <*format*>:<*version*> <*included*>
where <*included*> is a comma separated list of the above where <*included*> is a comma separated list of the above options.
options.
``--output=``\ <filename> ``--output=``\ <filename>
Write output to given file instead of stdout. Write output to given file instead of stdout.
SEE ALSO SEE ALSO
======== ========

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

@ -15,49 +15,49 @@ subject, recipients, and message body, or mailto: URL.
Supported options for **emacs-mua** include Supported options for **emacs-mua** include
``-h, --help`` ``-h, --help``
Display help. Display help.
``-s, --subject=``\ <subject> ``-s, --subject=``\ <subject>
Specify the subject of the message. Specify the subject of the message.
``--to=``\ <to-address> ``--to=``\ <to-address>
Specify a recipient (To). Specify a recipient (To).
``-c, --cc=``\ <cc-address> ``-c, --cc=``\ <cc-address>
Specify a carbon-copy (Cc) recipient. Specify a carbon-copy (Cc) recipient.
``-b, --bcc=``\ <bcc-address> ``-b, --bcc=``\ <bcc-address>
Specify a blind-carbon-copy (Bcc) recipient. Specify a blind-carbon-copy (Bcc) recipient.
``-i, --body=``\ <file> ``-i, --body=``\ <file>
Specify a file to include into the body of the message. Specify a file to include into the body of the message.
``--hello`` ``--hello``
Go to the Notmuch hello screen instead of the message composition Go to the Notmuch hello screen instead of the message composition
window if no message composition parameters are given. window if no message composition parameters are given.
``--no-window-system`` ``--no-window-system``
Even if a window system is available, use the current terminal. Even if a window system is available, use the current terminal.
``--client`` ``--client``
Use **emacsclient**, rather than **emacs**. For Use **emacsclient**, rather than **emacs**. For **emacsclient** to
**emacsclient** to work, you need an already running Emacs work, you need an already running Emacs with a server, or use
with a server, or use ``--auto-daemon``. ``--auto-daemon``.
``--auto-daemon`` ``--auto-daemon``
Automatically start Emacs in daemon mode, if the Emacs server Automatically start Emacs in daemon mode, if the Emacs server is
is not running. Applicable with ``--client``. Implies not running. Applicable with ``--client``. Implies
``--create-frame``. ``--create-frame``.
``--create-frame`` ``--create-frame``
Create a new frame instead of trying to use the current Emacs Create a new frame instead of trying to use the current Emacs
frame. Applicable with ``--client``. This will be required frame. Applicable with ``--client``. This will be required when
when Emacs is running (or automatically started with Emacs is running (or automatically started with ``--auto-daemon``)
``--auto-daemon``) in daemon mode. in daemon mode.
``--print`` ``--print``
Output the resulting elisp to stdout instead of evaluating it. 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 **mutt** MUA command-line options. The options and subset of the **mutt** MUA command-line options. The options and

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

@ -31,48 +31,46 @@ 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\ **>** ``--folder=<``\ folder\ **>**
Deliver the message to the specified folder, relative to the Deliver the message to the specified folder, relative to the
top-level directory given by the value of **database.path**. The top-level directory given by the value of **database.path**. The
default is the empty string, which means delivering to the default is the empty string, which means delivering to the
top-level directory. top-level directory.
``--create-folder`` ``--create-folder``
Try to create the folder named by the ``--folder`` option, if it Try to create the folder named by the ``--folder`` option, if it
does not exist. Otherwise the folder must already exist for mail does not exist. Otherwise the folder must already exist for mail
delivery to succeed. delivery to succeed.
``--keep`` ``--keep``
Keep the message file if indexing fails, and keep the message Keep the message file if indexing fails, and keep the message
indexed if applying tags or maildir flag synchronization indexed if applying tags or maildir flag synchronization
fails. Ignore these errors and return exit status 0 to fails. Ignore these errors and return exit status 0 to indicate
indicate successful mail delivery. successful mail delivery.
``--no-hooks`` ``--no-hooks``
Prevent hooks from being run. Prevent hooks from being run.
``--decrypt=(true|nostash|auto|false)`` ``--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).
If ``true`` and the message is encrypted, try to decrypt the ``nostash`` is the same as ``true`` except that it will not stash
message while indexing, stashing any session keys discovered. newly-discovered session keys in the database.
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 Be aware that the index is likely sufficient (and a stashed
stash newly-discovered session keys in the database. 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.
Be aware that the index is likely sufficient (and a stashed See also ``index.decrypt`` in **notmuch-config(1)**.
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 **notmuch-config(1)**.
EXIT STATUS EXIT STATUS
=========== ===========

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

@ -37,29 +37,27 @@ details on hooks.
Supported options for **new** include Supported options for **new** include
``--no-hooks`` ``--no-hooks``
Prevents hooks from being run. Prevents hooks from being run.
``--quiet`` ``--quiet``
Do not print progress or results. Do not print progress or results.
``--decrypt=(true|nostash|auto|false)`` ``--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.
If ``true``, when encountering an encrypted message, try to Be aware that the index is likely sufficient (and the session key
decrypt it while indexing, and stash any discovered session is certainly sufficient) to reconstruct the cleartext of the
keys. If ``auto``, try to use any session key already known message itself, so please ensure that the notmuch message index is
to belong to this message, but do not attempt to use the adequately protected. DO NOT USE ``--decrypt=true`` or
user's secret keys. If decryption is successful, index the ``--decrypt=nostash`` without considering the security of your
cleartext of the message. index.
Be aware that the index is likely sufficient (and the session See also ``index.decrypt`` in **notmuch-config(1)**.
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 **notmuch-config(1)**.
EXIT STATUS EXIT STATUS
=========== ===========

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

@ -21,29 +21,28 @@ messages using the supplied options.
Supported options for **reindex** include Supported options for **reindex** include
``--decrypt=(true|nostash|auto|false)`` ``--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.
If ``true``, when encountering an encrypted message, try to ``nostash`` is the same as ``true`` except that it will not stash
decrypt it while reindexing, stashing any session keys newly-discovered session keys in the database.
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 If ``false``, notmuch reindex will also delete any stashed session
stash newly-discovered session keys in the database. keys for all messages matching the search terms.
If ``false``, notmuch reindex will also delete any stashed Be aware that the index is likely sufficient (and a stashed
session keys for all messages matching the search terms. 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.
Be aware that the index is likely sufficient (and a stashed See also ``index.decrypt`` in **notmuch-config(1)**.
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 **notmuch-config(1)**.
SEE ALSO SEE ALSO
======== ========

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

@ -34,58 +34,56 @@ The resulting message template is output to stdout.
Supported options for **reply** include Supported options for **reply** include
``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**) ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
**default**
Includes subject and quoted message body as an RFC 2822
message.
**default** **json**
Includes subject and quoted message body as an RFC 2822 Produces JSON output containing headers for a reply message
message. and the contents of the original message. This output can be
used by a client to create a reply message intelligently.
**json** **sexp**
Produces JSON output containing headers for a reply message Produces S-Expression output containing headers for a reply
and the contents of the original message. This output can be message and the contents of the original message. This output
used by a client to create a reply message intelligently. can be used by a client to create a reply message
intelligently.
**sexp** **headers-only**
Produces S-Expression output containing headers for a reply Only produces In-Reply-To, References, To, Cc, and Bcc
message and the contents of the original message. This headers.
output can be used by a client to create a reply message
intelligently.
**headers-only** ``--format-version=N``
Only produces In-Reply-To, References, To, Cc, and Bcc Use the specified structured output format version. This is
headers. intended for programs that invoke **notmuch(1)** internally. If
omitted, the latest supported version will be used.
``--format-version=N`` ``--reply-to=``\ (**all**\ \|\ **sender**)
Use the specified structured output format version. This is **all** (default)
intended for programs that invoke **notmuch(1)** internally. If Replies to all addresses.
omitted, the latest supported version will be used.
``--reply-to=``\ (**all**\ \|\ **sender**) **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.
**all** (default) ``--decrypt``
Replies to all addresses. Decrypt any MIME encrypted parts found in the selected content
(ie. "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.
**sender** If a session key is already known for the message, then it will be
Replies only to the sender. If replying to user's own decrypted automatically unless the user explicitly sets
message (Reply-to: or From: header is one of the user's ``--decrypt=false``.
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`` Decryption expects a functioning **gpg-agent(1)** to provide any
Decrypt any MIME encrypted parts found in the selected content needed credentials. Without one, the decryption will likely fail.
(ie. "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 a session key is already known for the message, then it
will be decrypted automatically unless the user explicitly
sets ``--decrypt=false``.
Decryption expects a functioning **gpg-agent(1)** to provide any
needed credentials. Without one, the decryption will likely fail.
See **notmuch-search-terms(7)** for details of the supported syntax for See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>. <search-terms>.

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

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

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

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

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

@ -23,144 +23,138 @@ post-processor (such as the emacs interface to notmuch).
Supported options for **show** include Supported options for **show** include
``--entire-thread=(true|false)`` ``--entire-thread=(true|false)``
If true, **notmuch show** outputs all messages in the thread of If true, **notmuch show** outputs all messages in the thread of
any message matching the search terms; if false, it outputs only any message matching the search terms; if false, it outputs only
the matching messages. For ``--format=json`` and the matching messages. For ``--format=json`` and ``--format=sexp``
``--format=sexp`` this defaults to true. For other formats, this this defaults to true. For other formats, this defaults to false.
defaults to false.
``--format=(text|json|sexp|mbox|raw)`` ``--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.
**text** (default for messages) **json**
The default plain-text format has all text-content MIME The output is formatted with Javascript Object Notation
parts decoded. Various components in the output, (JSON). This format is more robust than the text format for
(**message**, **header**, **body**, **attachment**, and MIME automated processing. The nested structure of multipart MIME
**part**), will be delimited by easily-parsed markers. Each messages is reflected in nested JSON output. By default JSON
marker consists of a Control-L character (ASCII decimal 12), output includes all messages in a matching thread; that is, by
the name of the marker, and then either an opening or default, ``--format=json`` sets ``--entire-thread``. The
closing brace, ('{' or '}'), to either open or close the caller can disable this behaviour by setting
component. For a multipart MIME message, these parts will be ``--entire-thread=false``. The JSON output is always encoded
nested. as UTF-8 and any message content included in the output will
be charset-converted to UTF-8.
**json** **sexp**
The output is formatted with Javascript Object Notation The output is formatted as the Lisp s-expression (sexp)
(JSON). This format is more robust than the text format for equivalent of the JSON format above. Objects are formatted as
automated processing. The nested structure of multipart MIME property lists whose keys are keywords (symbols preceded by a
messages is reflected in nested JSON output. By default JSON colon). True is formatted as ``t`` and both false and null are
output includes all messages in a matching thread; that is, formatted as ``nil``. As for JSON, the s-expression output is
by default, always encoded as UTF-8.
``--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** **mbox**
The output is formatted as the Lisp s-expression (sexp) All matching messages are output in the traditional, Unix mbox
equivalent of the JSON format above. Objects are formatted format with each message being prefixed by a line beginning
as property lists whose keys are keywords (symbols preceded with "From " and a blank line separating each message. Lines
by a colon). True is formatted as ``t`` and both false and in the message content beginning with "From " (preceded by
null are formatted as ``nil``. As for JSON, the s-expression zero or more '>' characters) have an additional '>' character
output is always encoded as UTF-8. added. This reversible escaping is termed "mboxrd" format and
described in detail here:
**mbox**
All matching messages are output in the traditional, Unix
mbox format with each message being prefixed by a line
beginning with "From " and a blank line separating each
message. Lines in the message content beginning with "From "
(preceded by zero or more '>' characters) have an additional
'>' character added. This reversible escaping is termed
"mboxrd" format and described in detail here:
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
**raw** (default if --part is given) **raw** (default if --part is given)
Write the raw bytes of the given MIME part of a message to 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 standard out. For this format, it is an error to specify a
query that matches more than one message. query that matches more than one message.
If the specified part is a leaf part, this outputs the If the specified part is a leaf part, this outputs the body of
body of the part after performing content transfer the part after performing content transfer decoding (but no
decoding (but no charset conversion). This is suitable for charset conversion). This is suitable for saving attachments,
saving attachments, for example. for example.
For a multipart or message part, the output includes the For a multipart or message part, the output includes the part
part headers as well as the body (including all child headers as well as the body (including all child parts). No
parts). No decoding is performed because multipart and decoding is performed because multipart and message parts
message parts cannot have non-trivial content transfer cannot have non-trivial content transfer encoding. Consumers
encoding. Consumers of this may need to implement MIME of this may need to implement MIME decoding and similar
decoding and similar functions. functions.
``--format-version=N`` ``--format-version=N``
Use the specified structured output format version. This is Use the specified structured output format version. This is
intended for programs that invoke **notmuch(1)** internally. If intended for programs that invoke **notmuch(1)** internally. If
omitted, the latest supported version will be used. omitted, the latest supported version will be used.
``--part=N`` ``--part=N``
Output the single decoded MIME part N of a single message. The Output the single decoded MIME part N of a single message. The
search terms must match only a single message. Message parts are search terms must match only a single message. Message parts are
numbered in a depth-first walk of the message MIME structure, numbered in a depth-first walk of the message MIME structure, and
and are identified in the 'json', 'sexp' or 'text' output are identified in the 'json', 'sexp' or 'text' output formats.
formats.
Note that even a message with no MIME structure or a single Note that even a message with no MIME structure or a single body
body part still has two MIME parts: part 0 is the whole part still has two MIME parts: part 0 is the whole message
message (headers and body) and part 1 is just the body. (headers and body) and part 1 is just the body.
``--verify`` ``--verify``
Compute and report the validity of any MIME cryptographic Compute and report the validity of any MIME cryptographic
signatures found in the selected content (ie. "multipart/signed" signatures found in the selected content (ie. "multipart/signed"
parts). Status of the signature will be reported (currently only parts). Status of the signature will be reported (currently only
supported with --format=json and --format=sexp), and the supported with --format=json and --format=sexp), and the
multipart/signed part will be replaced by the signed data. multipart/signed part will be replaced by the signed data.
``--decrypt`` ``--decrypt``
Decrypt any MIME encrypted parts found in the selected content Decrypt any MIME encrypted parts found in the selected content
(ie. "multipart/encrypted" parts). Status of the decryption will (ie. "multipart/encrypted" parts). Status of the decryption will
be reported (currently only supported with --format=json and be reported (currently only supported with --format=json and
--format=sexp) and on successful decryption the --format=sexp) and on successful decryption the
multipart/encrypted part will be replaced by the decrypted multipart/encrypted part will be replaced by the decrypted
content. content.
If a session key is already known for the message, then it If a session key is already known for the message, then it will be
will be decrypted automatically unless the user explicitly decrypted automatically unless the user explicitly sets
sets ``--decrypt=false``. ``--decrypt=false``.
Decryption expects a functioning **gpg-agent(1)** to provide any Decryption expects a functioning **gpg-agent(1)** to provide any
needed credentials. Without one, the decryption will fail. needed credentials. Without one, the decryption will fail.
Implies --verify. Implies --verify.
``--exclude=(true|false)`` ``--exclude=(true|false)``
Specify whether to omit threads only matching Specify whether to omit threads only matching search.tag\_exclude
search.tag\_exclude from the search results (the default) or from the search results (the default) or not. In either case the
not. In either case the excluded message will be marked with the excluded message will be marked with the exclude flag (except when
exclude flag (except when output=mbox when there is nowhere to output=mbox when there is nowhere to put the flag).
put the flag).
If --entire-thread is specified then complete threads are If --entire-thread is specified then complete threads are returned
returned regardless (with the excluded flag being set when regardless (with the excluded flag being set when appropriate) but
appropriate) but threads that only match in an excluded message threads that only match in an excluded message are not returned
are not returned when ``--exclude=true.`` when ``--exclude=true.``
The default is ``--exclude=true.`` The default is ``--exclude=true.``
``--body=(true|false)`` ``--body=(true|false)``
If true (the default) **notmuch show** includes the bodies of If true (the default) **notmuch show** includes the bodies of the
the messages in the output; if false, bodies are omitted. messages in the output; if false, bodies are omitted.
``--body=false`` is only implemented for the json and sexp ``--body=false`` is only implemented for the json and sexp formats
formats and it is incompatible with ``--part > 0.`` and it is incompatible with ``--part > 0.``
This is useful if the caller only needs the headers as body-less This is useful if the caller only needs the headers as body-less
output is much faster and substantially smaller. output is much faster and substantially smaller.
``--include-html`` ``--include-html``
Include "text/html" parts as part of the output (currently only Include "text/html" parts as part of the output (currently only
supported with --format=json and --format=sexp). By default, supported with --format=json and --format=sexp). By default,
unless ``--part=N`` is used to select a specific part or unless ``--part=N`` is used to select a specific part or
``--include-html`` is used to include all "text/html" parts, no ``--include-html`` is used to include all "text/html" parts, no
part with content type "text/html" is included in the output. 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 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 can be messages. For this, use a search term of "thread:<thread-id>" as can be

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

@ -32,23 +32,22 @@ the **maildir.synchronize\_flags** configuration option is enabled. See
Supported options for **tag** include Supported options for **tag** include
``--remove-all`` ``--remove-all``
Remove all tags from each message matching the search terms Remove all tags from each message matching the search terms before
before applying the tag changes appearing on the command line. applying the tag changes appearing on the command line. This
This means setting the tags of each message to the tags to be means setting the tags of each message to the tags to be added. If
added. If there are no tags to be added, the messages will have there are no tags to be added, the messages will have no tags.
no tags.
``--batch`` ``--batch``
Read batch tagging operations from a file (stdin by default). Read batch tagging operations from a file (stdin by default).
This is more efficient than repeated **notmuch tag** This is more efficient than repeated **notmuch tag**
invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for
for the input format. This option is not compatible with the input format. This option is not compatible with specifying
specifying tagging on the command line. tagging on the command line.
``--input=``\ <filename> ``--input=``\ <filename>
Read input from given file, instead of from stdin. Implies Read input from given file, instead of from stdin. Implies
``--batch``. ``--batch``.
TAG FILE FORMAT TAG FILE FORMAT
=============== ===============

33
doc/man1/notmuch.rst
View file

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

45
doc/man5/notmuch-hooks.rst
View file

@ -17,34 +17,33 @@ have executable permissions.
The currently available hooks are described below. The currently available hooks are described below.
**pre-new** **pre-new**
This hook is invoked by the **new** command before scanning or This hook is invoked by the **new** command before scanning or
importing new messages into the database. If this hook exits importing new messages into the database. If this hook exits with
with a non-zero status, notmuch will abort further processing of a non-zero status, notmuch will abort further processing of the
the **new** command. **new** command.
Typically this hook is used for fetching or delivering new mail Typically this hook is used for fetching or delivering new mail to
to be imported into the database. be imported into the database.
**post-new** **post-new**
This hook is invoked by the **new** command after new messages This hook is invoked by the **new** command after new messages
have been imported into the database and initial tags have been have been imported into the database and initial tags have been
applied. The hook will not be run if there have been any errors applied. The hook will not be run if there have been any errors
during the scan or import. during the scan or import.
Typically this hook is used to perform additional query-based Typically this hook is used to perform additional query-based
tagging on the imported messages. tagging on the imported messages.
**post-insert** **post-insert**
This hook is invoked by the **insert** command after the message
has been delivered, added to the database, and initial tags have
been applied. The hook will not be run if there have been any
errors during the message delivery; what is regarded as successful
delivery depends on the ``--keep`` option.
This hook is invoked by the **insert** command after the Typically this hook is used to perform additional query-based
message has been delivered, added to the database, and initial tagging on the delivered messages.
tags have been applied. The hook will not be run if there have
been any errors during the message delivery; what is regarded
as successful delivery depends on the ``--keep`` option.
Typically this hook is used to perform additional query-based
tagging on the delivered messages.
SEE ALSO SEE ALSO
======== ========

1
doc/man7/notmuch-properties.rst
View file

@ -54,7 +54,6 @@ The following properties are set by notmuch internally in the course
of its normal activity. of its normal activity.
**index.decryption** **index.decryption**
If a message contains encrypted content, and notmuch tries to If a message contains encrypted content, and notmuch tries to
decrypt that content during indexing, it will add the property decrypt that content during indexing, it will add the property
``index.decryption=success`` when the cleartext was successfully ``index.decryption=success`` when the cleartext was successfully