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).
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- 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
- given, --output=sender is implied.
-
- **sender**
- Output all addresses from the *From* header.
-
- 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.
-
- **recipients**
- Output all addresses from the *To*, *Cc* and *Bcc*
- headers.
-
- **count**
- 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.
-
- **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.
-
- ``--deduplicate=(no|mailbox|address)``
-
- Control the deduplication of results.
-
- **no**
- Output all occurrences of addresses in the matching
- 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.
-
- **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.
-
- ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
- This option can be used to present results in either
- chronological order (**oldest-first**) or reverse chronological
- order (**newest-first**).
-
- By default, results will be displayed in reverse chronological
- order, (that is, the newest results will be displayed first).
-
- However, if either --output=count or --deduplicate=address is
- specified, this option is ignored and the order of the results
- is unspecified.
-
- ``--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.
-
- 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.
+``--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).
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ 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
+ given, --output=sender is implied.
+
+ **sender**
+ Output all addresses from the *From* header.
+
+ 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.
+
+ **recipients**
+ Output all addresses from the *To*, *Cc* and *Bcc* headers.
+
+ **count**
+ 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.
+
+ **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.
+
+``--deduplicate=(no|mailbox|address)``
+ Control the deduplication of results.
+
+ **no**
+ Output all occurrences of addresses in the matching
+ 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.
+
+ **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.
+
+``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+ This option can be used to present results in either chronological
+ order (**oldest-first**) or reverse chronological order
+ (**newest-first**).
+
+ By default, results will be displayed in reverse chronological
+ order, (that is, the newest results will be displayed first).
+
+ However, if either --output=count or --deduplicate=address is
+ specified, this option is ignored and the order of the results is
+ unspecified.
+
+``--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.
+
+ 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
===========
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.
-
- ``--quiet``
- Do not report database compaction progress to stdout.
+``--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.
+
+``--quiet``
+ Do not report database compaction progress to stdout.
ENVIRONMENT
===========
should not be placed in the configuration file, and should be accessed
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.
+**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.
- **set**
- The specified configuration item is set to the given value. To
- specify a multiple-value item (a list), provide each value as a
- separate command-line argument.
+**set**
+ The specified configuration item is set to the given value. To
+ specify a multiple-value item (a list), provide each value as a
+ separate command-line argument.
- If no values are provided, the specified configuration item will
- be removed from the configuration file.
+ If no values are provided, the specified configuration item will
+ be removed from the configuration file.
- **list**
- Every configuration item is printed to stdout, each on a
- separate line of the form:
+**list**
+ Every configuration item is printed to stdout, each on a separate
+ line of the form::
*section*.\ *item*\ =\ *value*
- No additional whitespace surrounds the dot or equals sign
- characters. In a multiple-value item (a list), the values are
- separated by semicolon characters.
+ No additional whitespace surrounds the dot or equals sign
+ characters. In a multiple-value item (a list), the values are
+ separated by semicolon characters.
The available configuration items are described below.
- **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``.
+**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``.
- Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
+ Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
+
+**user.name**
+ Your full name.
+
+ Default: ``$NAME`` variable if set, otherwise read from
+ ``/etc/passwd``.
- **user.name**
- Your full name.
+**user.primary\_email**
+ Your primary email address.
- Default: ``$NAME`` variable if set, otherwise read from
- ``/etc/passwd``.
+ Default: ``$EMAIL`` variable if set, otherwise constructed from
+ the username and hostname of the current machine.
- **user.primary\_email**
- Your primary email address.
-
- 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.
-
- Default: not set.
-
- **new.tags**
- 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 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".
-
- Default: empty list.
-
- **search.exclude\_tags**
- A list of tags that will be excluded from search results by
- default. Using an excluded tag in a query will override that
- exclusion.
-
- 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:
-
- +--------+-----------------------------------------------+
- | Flag | Tag |
- +========+===============================================+
- | D | draft |
- +--------+-----------------------------------------------+
- | F | flagged |
- +--------+-----------------------------------------------+
- | P | passed |
- +--------+-----------------------------------------------+
- | R | replied |
- +--------+-----------------------------------------------+
- | 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.
-
- 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.
-
- Default: ``gpg``.
-
- **index.decrypt**
-
- **[STORED IN DATABASE]**
-
- 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.
-
- 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.
-
- Here is a table that summarizes the functionality of each of
- these policies:
-
- +------------------------+-------+------+---------+------+
- | | false | auto | nostash | 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 | | | | |
- +------------------------+-------+------+---------+------+
-
- 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.
+**user.other\_email**
+ A list of other email addresses at which you receive email.
+
+ Default: not set.
+
+**new.tags**
+ 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 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".
+
+ Default: empty list.
+
+**search.exclude\_tags**
+ A list of tags that will be excluded from search results by
+ default. Using an excluded tag in a query will override that
+ exclusion.
+
+ 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:
+
+ +--------+-----------------------------------------------+
+ | Flag | Tag |
+ +========+===============================================+
+ | D | draft |
+ +--------+-----------------------------------------------+
+ | F | flagged |
+ +--------+-----------------------------------------------+
+ | P | passed |
+ +--------+-----------------------------------------------+
+ | R | replied |
+ +--------+-----------------------------------------------+
+ | 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.
+
+ 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.
+
+ Default: ``gpg``.
+
+**index.decrypt** **[STORED IN DATABASE]**
+ 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.
+
+ 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.
+
+ Here is a table that summarizes the functionality of each of these
+ policies:
+
+ +------------------------+-------+------+---------+------+
+ | | false | auto | nostash | 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 | | | | |
+ +------------------------+-------+------+---------+------+
+
+ 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
===========
Supported options for **count** include
- ``--output=(messages|threads|files)``
-
- **messages**
- Output the number of matching messages. This is the default.
-
- **threads**
- Output the number of matching threads.
-
- **files**
- Output the number of files associated with matching
- messages. This may be bigger than the number of matching
- messages due to duplicates (i.e. multiple files having the
- same message-id).
-
- ``--exclude=(true|false)``
- 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
- 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.
-
- ``--input=``\ <filename>
- Read input from given file, instead of from stdin. Implies
- ``--batch``.
+``--output=(messages|threads|files)``
+ **messages**
+ Output the number of matching messages. This is the default.
+
+ **threads**
+ Output the number of matching threads.
+
+ **files**
+ Output the number of files associated with matching
+ messages. This may be bigger than the number of matching
+ messages due to duplicates (i.e. multiple files having the
+ same message-id).
+
+``--exclude=(true|false)``
+ 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
+ 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.
+
+``--input=``\ <filename>
+ Read input from given file, instead of from stdin. Implies
+ ``--batch``.
SEE ALSO
========
Supported options for **dump** include
- ``--gzip``
- 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.
-
- **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
-
- +<*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)**.
-
- **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
-
- <*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)``
-
+``--gzip``
+ 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.
+
+ **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::
+
+ +<*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)**.
+
+ **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::
+
+ <*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)``
Control what kind of metadata is included in the output.
- **config**
-
+ **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**
-
+ **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**
-
+ **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.
+``--output=``\ <filename>
+ Write output to given file instead of stdout.
SEE ALSO
========
Supported options for **emacs-mua** include
- ``-h, --help``
- Display help.
+``-h, --help``
+ Display help.
- ``-s, --subject=``\ <subject>
- Specify the subject of the message.
+``-s, --subject=``\ <subject>
+ Specify the subject of the message.
- ``--to=``\ <to-address>
- Specify a recipient (To).
+``--to=``\ <to-address>
+ Specify a recipient (To).
- ``-c, --cc=``\ <cc-address>
- Specify a carbon-copy (Cc) recipient.
+``-c, --cc=``\ <cc-address>
+ Specify a carbon-copy (Cc) recipient.
- ``-b, --bcc=``\ <bcc-address>
- Specify a blind-carbon-copy (Bcc) recipient.
+``-b, --bcc=``\ <bcc-address>
+ Specify a blind-carbon-copy (Bcc) recipient.
- ``-i, --body=``\ <file>
- Specify a file to include into the body of the message.
+``-i, --body=``\ <file>
+ Specify a file to include into the body of the message.
- ``--hello``
- Go to the Notmuch hello screen instead of the message composition
- window if no message composition parameters are given.
+``--hello``
+ Go to the Notmuch hello screen instead of the message composition
+ window if no message composition parameters are given.
- ``--no-window-system``
- Even if a window system is available, use the current terminal.
+``--no-window-system``
+ 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``.
+``--client``
+ 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
- ``--create-frame``.
+``--auto-daemon``
+ 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.
+``--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.
- ``--print``
- Output the resulting elisp to stdout instead of evaluating it.
+``--print``
+ Output the resulting elisp to stdout instead of evaluating it.
The supported positional parameters and short options are a compatible
subset of the **mutt** MUA command-line options. The options and
Option arguments must appear before any tag operation arguments.
Supported options for **insert** include
- ``--folder=<``\ folder\ **>**
- Deliver the message to the specified folder, relative to the
- top-level directory given by the value of **database.path**. The
- default is the empty string, which means delivering to the
- top-level directory.
-
- ``--create-folder``
- Try to create the folder named by the ``--folder`` option, if it
- does not exist. Otherwise the folder must already exist for mail
- delivery to succeed.
-
- ``--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.
-
- ``--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).
-
- ``nostash`` is the same as ``true`` except that it will not
- stash newly-discovered session keys in the database.
-
- Be aware that the index is likely sufficient (and a stashed
- session key is certainly sufficient) to reconstruct the
- cleartext of the message itself, so please ensure that the
- notmuch message index is adequately protected. DO NOT USE
- ``--decrypt=true`` or ``--decrypt=nostash`` without
- considering the security of your index.
-
- See also ``index.decrypt`` in **notmuch-config(1)**.
+``--folder=<``\ folder\ **>**
+ Deliver the message to the specified folder, relative to the
+ top-level directory given by the value of **database.path**. The
+ default is the empty string, which means delivering to the
+ top-level directory.
+
+``--create-folder``
+ Try to create the folder named by the ``--folder`` option, if it
+ does not exist. Otherwise the folder must already exist for mail
+ delivery to succeed.
+
+``--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.
+
+``--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).
+
+ ``nostash`` is the same as ``true`` except that it will not stash
+ newly-discovered session keys in the database.
+
+ Be aware that the index is likely sufficient (and a stashed
+ session key is certainly sufficient) to reconstruct the cleartext
+ of the message itself, so please ensure that the notmuch message
+ index is adequately protected. DO NOT USE ``--decrypt=true`` or
+ ``--decrypt=nostash`` without considering the security of your
+ index.
+
+ See also ``index.decrypt`` in **notmuch-config(1)**.
EXIT STATUS
===========
Supported options for **new** include
- ``--no-hooks``
- Prevents hooks from being run.
-
- ``--quiet``
- 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.
-
- 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)**.
+``--no-hooks``
+ Prevents hooks from being run.
+
+``--quiet``
+ 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.
+
+ 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)**.
EXIT STATUS
===========
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.
-
- ``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.
-
- Be aware that the index is likely sufficient (and a stashed
- session key is certainly sufficient) to reconstruct the
- cleartext of the message itself, so please ensure that the
- notmuch message index is adequately protected. DO NOT USE
- ``--decrypt=true`` or ``--decrypt=nostash`` without
- considering the security of your index.
-
- See also ``index.decrypt`` in **notmuch-config(1)**.
+``--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.
+
+ ``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.
+
+ Be aware that the index is likely sufficient (and a stashed
+ session key is certainly sufficient) to reconstruct the cleartext
+ of the message itself, so please ensure that the notmuch message
+ index is adequately protected. DO NOT USE ``--decrypt=true`` or
+ ``--decrypt=nostash`` without considering the security of your
+ index.
+
+ See also ``index.decrypt`` in **notmuch-config(1)**.
SEE ALSO
========
Supported options for **reply** include
- ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
-
- **default**
- Includes subject and quoted message body as an RFC 2822
- message.
-
- **json**
- Produces JSON output containing headers for a reply message
- and the contents of the original message. This output can be
- used by a client to create a reply message intelligently.
-
- **sexp**
- Produces S-Expression output containing headers for a reply
- message and the contents of the original message. This
- output can be used by a client to create a reply message
- intelligently.
-
- **headers-only**
- Only produces In-Reply-To, References, To, Cc, and Bcc
- headers.
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- 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.
+``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
+ **default**
+ Includes subject and quoted message body as an RFC 2822
+ message.
+
+ **json**
+ Produces JSON output containing headers for a reply message
+ and the contents of the original message. This output can be
+ used by a client to create a reply message intelligently.
+
+ **sexp**
+ Produces S-Expression output containing headers for a reply
+ message and the contents of the original message. This output
+ can be used by a client to create a reply message
+ intelligently.
+
+ **headers-only**
+ Only produces In-Reply-To, References, To, Cc, and Bcc
+ headers.
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ 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.
``--decrypt=(false|auto|true)``
Supported options for **restore** include
- ``--accumulate``
- The union of the existing and new tags is applied, instead of
- replacing each message's tags as they are read in from the dump
- file.
-
- ``--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)**.
-
- **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).
-
- **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.
-
- **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.
-
- ``--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.
-
- **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.
-
- **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.
+``--accumulate``
+ The union of the existing and new tags is applied, instead of
+ replacing each message's tags as they are read in from the dump
+ file.
+
+``--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)**.
+
+ **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).
+
+ **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.
+
+ **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.
+
+``--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.
+
+ **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.
+
+ **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
=============
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).
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- 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).
-
- **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).
-
- **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).
-
- **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).
-
- 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).
-
- ``--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**).
-
- 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).
-
- ``--offset=[-]N``
- Skip displaying the first N results. With the leading '-', start
- at the Nth result from the end.
-
- ``--limit=N``
- Limit the number of displayed results to N.
-
- ``--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.
-
- The default value, **true**, prevents excluded messages from
- matching the search terms.
-
- **all** additionally prevents excluded messages from appearing
- in displayed results, in effect behaving as though the excluded
+``--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).
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ 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).
+
+ **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).
+
+ **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).
+
+ **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).
+
+ 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).
+
+``--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**).
+
+ 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).
+
+``--offset=[-]N``
+ Skip displaying the first N results. With the leading '-', start
+ at the Nth result from the end.
+
+``--limit=N``
+ Limit the number of displayed results to N.
+
+``--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.
+
+ **true** (default)
+ Prevent excluded messages from matching the search terms.
+
+ **all**
+ Additionally prevent excluded messages from appearing in
+ displayed results, in effect behaving as though the excluded
messages do not exist.
- **false** allows 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.
-
- ``--duplicate=N``
- For ``--output=files``, output the Nth filename associated
- with each message matching the query (N is 1-based). If N is
- greater than the number of files associated with the message,
- don't print anything.
-
- For ``--output=messages``, only output message IDs of messages
- matching the search terms that have at least N filenames
- associated with them.
-
- Note that this option is orthogonal with the **folder:** search
- prefix. The prefix matches messages based on filenames. This
- option filters filenames of the matching messages.
+ **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.
+
+``--duplicate=N``
+ For ``--output=files``, output the Nth filename associated with
+ each message matching the query (N is 1-based). If N is greater
+ than the number of files associated with the message, don't print
+ anything.
+
+ For ``--output=messages``, only output message IDs of messages
+ matching the search terms that have at least N filenames
+ associated with them.
+
+ Note that this option is orthogonal with the **folder:** search
+ prefix. The prefix matches messages based on filenames. This
+ option filters filenames of the matching messages.
EXAMPLE
=======
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.
-
- ``--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.
-
- **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.
-
- **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.
-
- **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:
+``--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.
+
+``--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.
+
+ **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.
+
+ **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.
+
+ **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
- **raw** (default if --part is given)
- Write the raw bytes of the given MIME part of a message to
- standard out. For this format, it is an error to specify a
- query that matches more than one message.
-
- 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.
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- omitted, the latest supported version will be used.
-
- ``--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.
-
- 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
- signatures found in the selected content (ie. "multipart/signed"
- parts). Status of the signature will be reported (currently only
- supported with --format=json and --format=sexp), and the
- multipart/signed part will be replaced by the signed data.
+ **raw** (default if --part is given)
+ Write the raw bytes of the given MIME part of a message to
+ standard out. For this format, it is an error to specify a
+ query that matches more than one message.
+
+ 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.
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ omitted, the latest supported version will be used.
+
+``--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.
+
+ 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
+ signatures found in the selected content (ie. "multipart/signed"
+ parts). Status of the signature will be reported (currently only
+ supported with --format=json and --format=sexp), and the
+ multipart/signed part will be replaced by the signed data.
``--decrypt=(false|auto|true)``
If ``true``, decrypt any MIME encrypted parts found in the
Default: ``auto``
- ``--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).
-
- 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.``
-
- This is useful if the caller only needs the headers as body-less
- output is much faster and substantially smaller.
-
- ``--include-html``
- Include "text/html" parts as part of the output (currently only
- supported with --format=json and --format=sexp). By default,
- unless ``--part=N`` is used to select a specific part or
- ``--include-html`` is used to include all "text/html" parts, no
- part with content type "text/html" is included in the output.
+``--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).
+
+ 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.``
+
+ This is useful if the caller only needs the headers as body-less
+ output is much faster and substantially smaller.
+
+``--include-html``
+ Include "text/html" parts as part of the output (currently only
+ supported with --format=json and --format=sexp). By default,
+ unless ``--part=N`` is used to select a specific part or
+ ``--include-html`` is used to include all "text/html" parts, no
+ part with content type "text/html" is included in the output.
A common use of **notmuch show** is to display a single thread of email
messages. For this, use a search term of "thread:<thread-id>" as can be
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.
-
- ``--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.
-
- ``--input=``\ <filename>
- Read input from given file, instead of from stdin. Implies
- ``--batch``.
+``--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.
+
+``--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.
+
+``--input=``\ <filename>
+ Read input from given file, instead of from stdin. Implies
+ ``--batch``.
TAG FILE FORMAT
===============
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.
+``--help`` [command-name]
+ 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.
+``--version``
+ Print the installed version of notmuch, and exit.
- ``--config=FILE``
- Specify the configuration file to use. This overrides any
- configuration file specified by ${NOTMUCH\_CONFIG}.
+``--config=FILE``
+ Specify the configuration file to use. This overrides any
+ 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``
+``--uuid=HEX``
+ Enforce that the database UUID (a unique identifier which persists
+ until e.g. the database is compacted) is HEX; exit with an error
+ if it is not. This is useful to detect rollover in modification
+ counts on messages. You can find this UUID using e.g. ``notmuch
+ count --lastmod``
All global options except ``--config`` can also be specified after the
-command. For example, ``notmuch subcommand --uuid=HEX`` is
-equivalent to ``notmuch --uuid=HEX subcommand``.
+command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent
+to ``notmuch --uuid=HEX subcommand``.
COMMANDS
========
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.
-
- 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
- have been imported into the database and initial tags have been
- applied. The hook will not be run if there have been any errors
- during the scan or import.
-
- Typically this hook is used to perform additional query-based
- 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.
-
- Typically this hook is used to perform additional query-based
- tagging on the delivered messages.
+**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.
+
+ 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
+ have been imported into the database and initial tags have been
+ applied. The hook will not be run if there have been any errors
+ during the scan or import.
+
+ Typically this hook is used to perform additional query-based
+ 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.
+
+ Typically this hook is used to perform additional query-based
+ tagging on the delivered messages.
SEE ALSO
========
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
projects / notmuch / commitdiff