debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-21 18:38: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

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

@ -21,8 +21,8 @@ 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 **xargs(1)** -0 option
where available).
separated plain-text (compatible with **xargs(1)** -0 option where
available).
``--format-version=N``
Use the specified structured output format version. This is
@ -30,10 +30,9 @@ Supported options for **address** include
omitted, the latest supported version will be used.
``--output=(sender|recipients|count|address)``
Controls which information appears in the output. This option
can be given multiple times to combine different outputs.
When neither --output=sender nor --output=recipients is
Controls which information appears in the output. This option can
be given multiple times to combine different outputs. When
neither --output=sender nor --output=recipients is
given, --output=sender is implied.
**sender**
@ -41,27 +40,25 @@ Supported options for **address** include
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.
cached directly in the database whereas other addresses need
to be fetched from message files.
**recipients**
Output all addresses from the *To*, *Cc* and *Bcc*
headers.
Output all addresses from the *To*, *Cc* and *Bcc* headers.
**count**
Print the count of how many times was the address
encountered during search.
Print the count of how many times was the address encountered
during search.
Note: With this option, addresses are printed only after
the whole search is finished. This may take long time.
Note: With this option, addresses are printed only after the
whole search is finished. This may take long time.
**address**
Output only the email addresses instead of the full
mailboxes with names and email addresses. This option has
no effect on the JSON or S-Expression output formats.
Output only the email addresses instead of the full mailboxes
with names and email addresses. This option has no effect on
the JSON or S-Expression output formats.
``--deduplicate=(no|mailbox|address)``
Control the deduplication of results.
**no**
@ -69,36 +66,35 @@ Supported options for **address** include
messages. This is not applicable with --output=count.
**mailbox**
Deduplicate addresses based on the full, case sensitive
name and email address, or mailbox. This is effectively
the same as piping the --deduplicate=no output to **sort |
uniq**, except for the order of results. This is the
default.
Deduplicate addresses based on the full, case sensitive name
and email address, or mailbox. This is effectively the same as
piping the --deduplicate=no output to **sort | uniq**, except
for the order of results. This is the default.
**address**
Deduplicate addresses based on the case insensitive
address part of the mailbox. Of all the variants (with
different name or case), print the one occurring most
frequently among the matching messages. If --output=count
is specified, include all variants in the count.
Deduplicate addresses based on the case insensitive address
part of the mailbox. Of all the variants (with different name
or case), print the one occurring most frequently among the
matching messages. If --output=count is specified, include all
variants in the count.
``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
This option can be used to present results in either
chronological order (**oldest-first**) or reverse chronological
order (**newest-first**).
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.
specified, this option is ignored and the order of the results is
unspecified.
``--exclude=(true|false)``
A message is called "excluded" if it matches at least one tag in
search.tag\_exclude that does not appear explicitly in the
search terms. This option specifies whether to omit excluded
messages in the search process.
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.

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

@ -25,10 +25,10 @@ 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.
Save the current database to the given directory before replacing
it with the compacted database. The backup directory must not
exist and it must reside on the same mounted filesystem as the
current database.
``--quiet``
Do not report database compaction progress to stdout.

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

@ -23,8 +23,8 @@ programmatically as described in the SYNOPSIS above.
**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.
stdout. If the item has multiple values (it is a list), each value
is separated by a newline character.
**set**
The specified configuration item is set to the given value. To
@ -35,8 +35,8 @@ programmatically as described in the SYNOPSIS above.
be removed from the configuration file.
**list**
Every configuration item is printed to stdout, each on a
separate line of the form:
Every configuration item is printed to stdout, each on a separate
line of the form::
*section*.\ *item*\ =\ *value*
@ -49,9 +49,8 @@ The available configuration items are described below.
**database.path**
The top-level directory where your mail currently exists and to
where mail will be delivered in the future. Files should be
individual email messages. Notmuch will store its database
within a sub-directory of the path configured here named
``.notmuch``.
individual email messages. Notmuch will store its database within
a sub-directory of the path configured here named ``.notmuch``.
Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
@ -64,8 +63,8 @@ The available configuration items are described below.
**user.primary\_email**
Your primary email address.
Default: ``$EMAIL`` variable if set, otherwise constructed from the
username and hostname of the current machine.
Default: ``$EMAIL`` variable if set, otherwise constructed from
the username and hostname of the current machine.
**user.other\_email**
A list of other email addresses at which you receive email.
@ -73,28 +72,26 @@ The available configuration items are described below.
Default: not set.
**new.tags**
A list of tags that will be added to all messages incorporated
by **notmuch new**.
A list of tags that will be added to all messages incorporated by
**notmuch new**.
Default: ``unread;inbox``.
**new.ignore**
A list to specify files and directories that will not be
searched for messages by **notmuch new**. Each entry in the
list is either:
A list to specify files and directories that will not be searched
for messages by **notmuch new**. Each entry in the list is either:
A file or a directory name, without path, that will be
ignored, regardless of the location in the mail store
directory hierarchy.
A file or a directory name, without path, that will be ignored,
regardless of the location in the mail store directory hierarchy.
Or:
A regular expression delimited with // that will be matched
against the path of the file or directory relative to the
database path. Matching files and directories will be
ignored. The beginning and end of string must be explictly
anchored. For example, /.*/foo$/ would match "bar/foo" and
"bar/baz/foo", but not "foo" or "bar/foobar".
against the path of the file or directory relative to the database
path. Matching files and directories will be ignored. The
beginning and end of string must be explictly anchored. For
example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
not "foo" or "bar/foobar".
Default: empty list.
@ -106,8 +103,6 @@ The available configuration items are described below.
Default: empty list. Note that **notmuch-setup(1)** puts
``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:
@ -126,56 +121,50 @@ The available configuration items are described below.
| S | unread (added when 'S' flag is not present) |
+--------+-----------------------------------------------+
The **notmuch new** command will notice flag changes in
filenames and update tags, while the **notmuch tag** and
**notmuch restore** commands will notice tag changes and update
flags in filenames.
The **notmuch new** command will notice flag changes in 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
added, old ones removed or renamed, maildir flags changed,
etc.), it is advisable to run **notmuch new** before **notmuch
tag** or **notmuch restore** commands to ensure the tag changes
are properly synchronized to the maildir flags, as the commands
expect the database and maildir to be in sync.
If there have been any changes in the maildir (new messages added,
old ones removed or renamed, maildir flags changed, etc.), it is
advisable to run **notmuch new** before **notmuch tag** or
**notmuch restore** commands to ensure the tag changes are
properly synchronized to the maildir flags, as the commands expect
the database and maildir to be in sync.
Default: ``true``.
**crypto.gpg_path**
Name (or full path) of gpg binary to use in verification and
decryption of PGP/MIME messages. NOTE: This configuration
item is deprecated, and will be ignored if notmuch is built
against GMime 3.0 or later.
decryption of PGP/MIME messages. NOTE: This configuration item is
deprecated, and will be ignored if notmuch is built against GMime
3.0 or later.
Default: ``gpg``.
**index.decrypt**
**index.decrypt** **[STORED IN DATABASE]**
Policy for decrypting encrypted messages during indexing. Must be
one of: ``false``, ``auto``, ``nostash``, or ``true``.
**[STORED IN DATABASE]**
When indexing an encrypted e-mail message, if this variable is set
to ``true``, notmuch will try to decrypt the message and index the
cleartext, stashing a copy of any discovered session keys for the
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.
Policy for decrypting encrypted messages during indexing.
Must be one of: ``false``, ``auto``, ``nostash``, or
``true``.
When indexing an encrypted e-mail message, if this variable is
set to ``true``, notmuch will try to decrypt the message and
index the cleartext, stashing a copy of any discovered session
keys for the 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.
``nostash`` is the same as ``true`` except that it will not
stash newly-discovered session keys in the database.
``nostash`` is the same as ``true`` except that it will not stash
newly-discovered session keys in the database.
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
**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
these policies:
Here is a table that summarizes the functionality of each of these
policies:
+------------------------+-------+------+---------+------+
| | false | auto | nostash | true |
@ -194,27 +183,24 @@ The available configuration items are described below.
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.
**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
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)**).
"compact" (see **notmuch-compact(1)**) and "field_processor" (see
**notmuch-search-terms(7)**).
**query.<name>**
**[STORED IN DATABASE]**
**query.<name>** **[STORED IN DATABASE]**
Expansion for named query called <name>. See
**notmuch-search-terms(7)** for more information about named
queries.

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

@ -23,7 +23,6 @@ See **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.
@ -37,20 +36,20 @@ Supported options for **count** include
same message-id).
``--exclude=(true|false)``
Specify whether to omit messages matching search.tag\_exclude
from the count (the default) or not.
Specify whether to omit messages matching search.tag\_exclude from
the count (the default) or not.
``--batch``
Read queries from a file (stdin by default), one per line, and
output the number of matching messages (or threads) to stdout,
one per line. On an empty input line the count of all messages
(or threads) in the database will be output. This option is not
output the number of matching messages (or threads) to stdout, one
per line. On an empty input line the count of all messages (or
threads) in the database will be output. This option is not
compatible with specifying search terms on the command line.
``--lastmod``
Append lastmod (counter for number of database updates) and UUID
to the output. lastmod values are only comparable between databases
with the same UUID.
to the output. lastmod values are only comparable between
databases with the same UUID.
``--input=``\ <filename>
Read input from given file, instead of from stdin. Implies

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

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

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

@ -41,20 +41,20 @@ Supported options for **emacs-mua** include
Even if a window system is available, use the current terminal.
``--client``
Use **emacsclient**, rather than **emacs**. For
**emacsclient** to work, you need an already running Emacs
with a server, or use ``--auto-daemon``.
Use **emacsclient**, rather than **emacs**. For **emacsclient** to
work, you need an already running Emacs with a server, or use
``--auto-daemon``.
``--auto-daemon``
Automatically start Emacs in daemon mode, if the Emacs server
is not running. Applicable with ``--client``. Implies
Automatically start Emacs in daemon mode, if the Emacs server is
not running. Applicable with ``--client``. Implies
``--create-frame``.
``--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.
frame. Applicable with ``--client``. This will be required when
Emacs is running (or automatically started with ``--auto-daemon``)
in daemon mode.
``--print``
Output the resulting elisp to stdout instead of evaluating it.

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

@ -45,32 +45,30 @@ Supported options for **insert** include
``--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.
fails. Ignore these errors and return exit status 0 to indicate
successful mail delivery.
``--no-hooks``
Prevent hooks from being run.
``--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).
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.
``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.
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)**.

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

@ -44,20 +44,18 @@ Supported options for **new** include
Do not print progress or results.
``--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.
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.
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 **notmuch-config(1)**.

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

@ -22,26 +22,25 @@ 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.
decrypt it while reindexing, stashing any session keys discovered.
If ``auto``, and notmuch already knows about a session key for the
message, it will try decrypting using that session key but will
not try to access the user's secret keys. If decryption is
successful, index the cleartext itself.
``nostash`` is the same as ``true`` except that it will not
stash newly-discovered session keys in the database.
``nostash`` is the same as ``true`` except that it will not stash
newly-discovered session keys in the database.
If ``false``, notmuch reindex will also delete any stashed
session keys for all messages matching the search terms.
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.
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)**.

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

@ -35,7 +35,6 @@ 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.
@ -47,8 +46,8 @@ Supported options for **reply** include
**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
message and the contents of the original message. This output
can be used by a client to create a reply message
intelligently.
**headers-only**
@ -61,16 +60,15 @@ Supported options for **reply** include
omitted, the latest supported version will be used.
``--reply-to=``\ (**all**\ \|\ **sender**)
**all** (default)
Replies to all addresses.
**sender**
Replies only to the sender. If replying to user's own
message (Reply-to: or From: header is one of the user's
configured email addresses), try To:, Cc:, and Bcc: headers
in this order, and copy values from the first that contains
something other than only the user's addresses.
Replies only to the sender. If replying to user's own message
(Reply-to: or From: header is one of the user's configured
email addresses), try To:, Cc:, and Bcc: headers in this
order, and copy values from the first that contains something
other than only the user's addresses.
``--decrypt``
Decrypt any MIME encrypted parts found in the selected content
@ -80,9 +78,9 @@ Supported options for **reply** include
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``.
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.

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

@ -23,8 +23,8 @@ Supported options for **restore** include
``--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 **notmuch-dump(1)**.
line specifying a message-id and a set of tags. For details of the
actual formats, see **notmuch-dump(1)**.
**sup**
The **sup** dump file format is specifically chosen to be
@ -36,45 +36,39 @@ Supported options for **restore** include
**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 **notmuch-dump(1)**
for details on this format.
or non-\ **ascii(7)** characters. See **notmuch-dump(1)** for
details on this format.
**notmuch restore** updates the maildir flags according to
tag changes if the **maildir.synchronize\_flags**
configuration option is enabled. See **notmuch-config(1)**
for details.
**notmuch restore** updates the maildir flags according to tag
changes if the **maildir.synchronize\_flags** configuration
option is enabled. See **notmuch-config(1)** for details.
**auto**
This option (the default) tries to guess the format from the
input. For correctly formed input in either supported
format, this heuristic, based the fact that batch-tag format
contains no parentheses, should be accurate.
input. For correctly formed input in either supported format,
this heuristic, based the fact that batch-tag format contains
no parentheses, should be accurate.
``--include=(config|properties|tags)``
Control what kind of metadata is restored.
**config**
Restore configuration data to the database. Each configuration line starts
with "#@ ", followed by a space separated key-value pair.
Both key and value are hex encoded if needed.
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 **notmuch-properties(7)** for more
details.
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.
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.

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

@ -27,8 +27,8 @@ 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 **xargs(1)** -0 option
where available).
separated plain-text (compatible with **xargs(1)** -0 option where
available).
``--format-version=N``
Use the specified structured output format version. This is
@ -36,60 +36,57 @@ Supported options for **search** include
omitted, the latest supported version will be used.
``--output=(summary|threads|messages|files|tags)``
**summary**
Output a summary of each thread with any message matching
the search terms. The summary includes the thread ID, date,
the number of messages in the thread (both the number
matched and the total number), the authors of the thread and
the subject. In the case where a thread contains multiple files for
some messages, the total number of files is printed in parentheses
(see below for an example).
Output a summary of each thread with any message matching the
search terms. The summary includes the thread ID, date, the
number of messages in the thread (both the number matched and
the total number), the authors of the thread and the
subject. In the case where a thread contains multiple files
for some messages, the total number of files is printed in
parentheses (see below for an example).
**threads**
Output the thread IDs of all threads with any message
matching the search terms, either one per line
(--format=text), separated by null characters
(--format=text0), as a JSON array (--format=json), or an
S-Expression list (--format=sexp).
Output the thread IDs of all threads with any message matching
the search terms, either one per line (--format=text),
separated by null characters (--format=text0), as a JSON array
(--format=json), or an S-Expression list (--format=sexp).
**messages**
Output the message IDs of all messages matching the search
terms, either one per line (--format=text), separated by
null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
terms, either one per line (--format=text), separated by null
characters (--format=text0), as a JSON array (--format=json),
or as an S-Expression list (--format=sexp).
**files**
Output the filenames of all messages matching the search
terms, either one per line (--format=text), separated by
null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
terms, either one per line (--format=text), separated by null
characters (--format=text0), as a JSON array (--format=json),
or as an S-Expression list (--format=sexp).
Note that each message may have multiple filenames
associated with it. All of them are included in the output
(unless limited with the --duplicate=N option). This may
be particularly confusing for **folder:** or **path:**
searches in a specified directory, as the messages may
have duplicates in other directories that are included in
the output, although these files alone would not match the
search.
Note that each message may have multiple filenames associated
with it. All of them are included in the output (unless
limited with the --duplicate=N option). This may be
particularly confusing for **folder:** or **path:** searches
in a specified directory, as the messages may have duplicates
in other directories that are included in the output, although
these files alone would not match the search.
**tags**
Output all tags that appear on any message matching the
search terms, either one per line (--format=text), separated
by null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
Output all tags that appear on any message matching the search
terms, either one per line (--format=text), separated by null
characters (--format=text0), as a JSON array (--format=json),
or as an S-Expression list (--format=sexp).
``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
This option can be used to present results in either
chronological order (**oldest-first**) or reverse chronological
order (**newest-first**).
This option can be used to present results in either chronological
order (**oldest-first**) or reverse chronological order
(**newest-first**).
Note: The thread order will be distinct between these two
options (beyond being simply reversed). When sorting by
**oldest-first** the threads will be sorted by the oldest
message in each thread, but when sorting by **newest-first** the
threads will be sorted by the newest message in each thread.
Note: The thread order will be distinct between these two options
(beyond being simply reversed). When sorting by **oldest-first**
the threads will be sorted by the oldest message in each thread,
but when sorting by **newest-first** the threads will be sorted by
the newest message in each thread.
By default, results will be displayed in reverse chronological
order, (that is, the newest results will be displayed first).
@ -103,31 +100,34 @@ Supported options for **search** include
``--exclude=(true|false|all|flag)``
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.
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.
**true** (default)
Prevent excluded messages from matching the search terms.
**all** additionally prevents excluded messages from appearing
in displayed results, in effect behaving as though the excluded
**all**
Additionally prevent excluded messages from appearing in
displayed results, in effect behaving as though the excluded
messages do not exist.
**false** allows excluded messages to match search terms and
appear in displayed results. Excluded messages are still marked
in the relevant outputs.
**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.
**flag**
Only has an effect when ``--output=summary``. The output is
almost identical to **false**, but the "match count" is the
number of matching non-excluded messages in the thread, rather
than the number of matching messages.
``--duplicate=N``
For ``--output=files``, output the Nth filename associated
with each message matching the query (N is 1-based). If N is
greater than the number of files associated with the message,
don't print anything.
For ``--output=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

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

@ -26,52 +26,48 @@ 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.
the matching messages. For ``--format=json`` and ``--format=sexp``
this defaults to true. For other formats, this defaults to false.
``--format=(text|json|sexp|mbox|raw)``
**text** (default for messages)
The default plain-text format has all text-content MIME
parts decoded. Various components in the output,
(**message**, **header**, **body**, **attachment**, and MIME
**part**), will be delimited by easily-parsed markers. Each
marker consists of a Control-L character (ASCII decimal 12),
the name of the marker, and then either an opening or
closing brace, ('{' or '}'), to either open or close the
component. For a multipart MIME message, these parts will be
nested.
The default plain-text format has all text-content MIME parts
decoded. Various components in the output, (**message**,
**header**, **body**, **attachment**, and MIME **part**), will
be delimited by easily-parsed markers. Each marker consists of
a Control-L character (ASCII decimal 12), the name of the
marker, and then either an opening or closing brace, ('{' or
'}'), to either open or close the component. For a multipart
MIME message, these parts will be nested.
**json**
The output is formatted with Javascript Object Notation
(JSON). This format is more robust than the text format for
automated processing. The nested structure of multipart MIME
messages is reflected in nested JSON output. By default JSON
output includes all messages in a matching thread; that is,
by default,
``--format=json`` sets ``--entire-thread``. The caller can
disable this behaviour by setting ``--entire-thread=false``.
The JSON output is always encoded as UTF-8 and any message
content included in the output will be charset-converted to
UTF-8.
output includes all messages in a matching thread; that is, by
default, ``--format=json`` sets ``--entire-thread``. The
caller can disable this behaviour by setting
``--entire-thread=false``. The JSON output is always encoded
as UTF-8 and any message content included in the output will
be charset-converted to UTF-8.
**sexp**
The output is formatted as the Lisp s-expression (sexp)
equivalent of the JSON format above. Objects are formatted
as property lists whose keys are keywords (symbols preceded
by a colon). True is formatted as ``t`` and both false and
null are formatted as ``nil``. As for JSON, the s-expression
output is always encoded as UTF-8.
equivalent of the JSON format above. Objects are formatted as
property lists whose keys are keywords (symbols preceded by a
colon). True is formatted as ``t`` and both false and null are
formatted as ``nil``. As for JSON, the s-expression output is
always encoded as UTF-8.
**mbox**
All matching messages are output in the traditional, Unix
mbox format with each message being prefixed by a line
beginning with "From " and a blank line separating each
message. Lines in the message content beginning with "From "
(preceded by zero or more '>' characters) have an additional
'>' character added. This reversible escaping is termed
"mboxrd" format and described in detail here:
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
@ -80,17 +76,17 @@ Supported options for **show** include
standard out. For this format, it is an error to specify a
query that matches more than one message.
If the specified part is a leaf part, this outputs the
body of the part after performing content transfer
decoding (but no charset conversion). This is suitable for
saving attachments, for example.
If the specified part is a leaf part, this outputs the body of
the part after performing content transfer decoding (but no
charset conversion). This is suitable for saving attachments,
for example.
For a multipart or message part, the output includes the
part headers as well as the body (including all child
parts). No decoding is performed because multipart and
message parts cannot have non-trivial content transfer
encoding. Consumers of this may need to implement MIME
decoding and similar functions.
For a multipart or message part, the output includes the part
headers as well as the body (including all child parts). No
decoding is performed because multipart and message parts
cannot have non-trivial content transfer encoding. Consumers
of this may need to implement MIME decoding and similar
functions.
``--format-version=N``
Use the specified structured output format version. This is
@ -100,13 +96,12 @@ Supported options for **show** include
``--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.
numbered in a depth-first walk of the message MIME structure, and
are identified in the 'json', 'sexp' or 'text' output formats.
Note that even a message with no MIME structure or a single
body part still has two MIME parts: part 0 is the whole
message (headers and body) and part 1 is just the body.
Note that even a message with no MIME structure or a single body
part still has two MIME parts: part 0 is the whole message
(headers and body) and part 1 is just the body.
``--verify``
Compute and report the validity of any MIME cryptographic
@ -123,9 +118,9 @@ Supported options for **show** include
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``.
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 fail.
@ -133,24 +128,23 @@ Supported options for **show** include
Implies --verify.
``--exclude=(true|false)``
Specify whether to omit threads only matching
search.tag\_exclude 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).
Specify whether to omit threads only matching search.tag\_exclude
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.``
If --entire-thread is specified then complete threads are returned
regardless (with the excluded flag being set when appropriate) but
threads that only match in an excluded message are not returned
when ``--exclude=true.``
The default is ``--exclude=true.``
``--body=(true|false)``
If true (the default) **notmuch show** includes the bodies of
the messages in the output; if false, bodies are omitted.
``--body=false`` is only implemented for the json and sexp
formats and it is incompatible with ``--part > 0.``
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 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.

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

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

19
doc/man1/notmuch.rst
View file

@ -40,9 +40,8 @@ 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.
Print a synopsis of available commands and exit. With an optional
command name, show the man page for that subcommand.
``--version``
Print the installed version of notmuch, and exit.
@ -52,15 +51,15 @@ Supported global options for ``notmuch`` include
configuration file specified by ${NOTMUCH\_CONFIG}.
``--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``
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 to ``notmuch --uuid=HEX subcommand``.
command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent
to ``notmuch --uuid=HEX subcommand``.
COMMANDS
========

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

@ -19,12 +19,12 @@ The currently available hooks are described below.
**pre-new**
This hook is invoked by the **new** command before scanning or
importing new messages into the database. If this hook exits
with a non-zero status, notmuch will abort further processing of
the **new** command.
importing new messages into the database. If this hook exits with
a non-zero status, notmuch will abort further processing of the
**new** command.
Typically this hook is used for fetching or delivering new mail
to be imported into the database.
Typically this hook is used for fetching or delivering new mail to
be imported into the database.
**post-new**
This hook is invoked by the **new** command after new messages
@ -36,12 +36,11 @@ The currently available hooks are described below.
tagging on the imported messages.
**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 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.
Typically this hook is used to perform additional query-based
tagging on the delivered messages.

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.
**index.decryption**
If a message contains encrypted content, and notmuch tries to
decrypt that content during indexing, it will add the property
``index.decryption=success`` when the cleartext was successfully