[the GNU General Public License](https://www.gnu.org/licenses/gpl.txt),
either version 3.0 or at your option any later version.
-<h2>0.31</h2>
+<h2>0.32</h2>
it does not provide the most convenient interface for that functional‐
ity. More sophisticated interfaces are expected to be built on top of
either the command-line interface, or more likely, on top of the not‐
- much library interface. See <u>https://notmuchmail.org</u> for more about
- alternate interfaces to notmuch. The emacs-based interface to notmuch
+ much library interface. See <u>https://notmuchmail.org</u> for more about al‐
+ ternate interfaces to notmuch. The emacs-based interface to notmuch
(available under <b>emacs/</b> in the Notmuch source distribution) is probably
the most widely used at this time.
</pre>
Supported global options for <b>notmuch</b> include
<b>--help</b> <b>[command-name]</b>
- 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 op‐
+ tional command name, show the man page for that subcommand.
<b>--version</b>
Print the installed version of notmuch, and exit.
<b>--config=FILE</b>
Specify the configuration file to use. This overrides any con‐
- figuration file specified by ${NOTMUCH_CONFIG}.
+ figuration file specified by ${NOTMUCH_CONFIG}. The empty string
+ is a permitted and sometimes useful value of <u>FILE</u>, which tells
+ <b>notmuch</b> to use only configuration metadata from the database.
<b>--uuid=HEX</b>
Enforce that the database UUID (a unique identifier which per‐
The <b>search</b>, <b>show</b>, <b>address</b> and <b>count</b> commands are used to query the
email database.
- The <b>reply</b> command is useful for preparing a template for an email
- reply.
+ The <b>reply</b> command is useful for preparing a template for an email re‐
+ ply.
The <b>tag</b> command is the only command available for manipulating database
contents.
set.
<b>NOTMUCH</b>_<b>TALLOC</b>_<b>REPORT</b>
- Location to write a talloc memory usage report. See <b>tal-</b>
- <b>loc</b>_<b>enable</b>_<b>leak</b>_<b>report</b>_<b>full</b> in <b>talloc</b>(3) for more information.
+ Location to write a talloc memory usage report. See <b>talloc</b>_<b>en-</b>
+ <b>able</b>_<b>leak</b>_<b>report</b>_<b>full</b> in <b>talloc</b>(3) for more information.
<b>NOTMUCH</b>_<b>DEBUG</b>_<b>QUERY</b>
If set to a non-empty value, the notmuch library will print (to
<pre>
<a href='../notmuch-address-1/'>notmuch-address</a>(1), <a href='../notmuch-compact-1/'>notmuch-compact</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>not‐</a>
<a href='../notmuch-count-1/'>much-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),
- <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1), <a href='../notmuch-reply-1/'>not‐</a>
- <a href='../notmuch-reply-1/'>much-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>not‐</a>
- <a href='../notmuch-s
earch-terms-7/'>much-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+ <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1), <a href='../notmuch-reply-1/'>notmuch-re‐</a>
+ <a href='../notmuch-reply-1/'>ply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),
+ <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
The notmuch website: <b>https://notmuchmail.org</b>
</pre>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
available).
<b>--format-version=N</b>
- Use the specified structured output format version. This is
- intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
- omitted, the latest supported version will be used.
+ Use the specified structured output format version. This is in‐
+ tended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If omit‐
+ ted, the latest supported version will be used.
<b>--output=(sender|recipients|count|address)</b>
Controls which information appears in the output. This option
Deduplicate addresses based on the full, case sensitive
name and email address, or mailbox. This is effectively
the same as piping the <b>--deduplicate=no</b> output to <b>sort</b> <b>|</b>
- <b>uniq</b>, except for the order of results. This is the
- default.
+ <b>uniq</b>, except for the order of results. This is the de‐
+ fault.
<b>address</b>
- 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 <b>--output=count</b>
- is specified, include all variants in the count.
+ Deduplicate addresses based on the case insensitive ad‐
+ dress part of the mailbox. Of all the variants (with dif‐
+ ferent name or case), print the one occurring most fre‐
+ quently among the matching messages. If <b>--output=count</b> is
+ specified, include all variants in the count.
<b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
This option can be used to present results in either chronologi‐
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<pre>
<b>notmuch</b> <b>config</b> <b>get</b> <<u>section</u>>.<<u>item</u>>
- <b>notmuch</b> <b>config</b> <b>set</b> <<u>section</u>>.<<u>item</u>> [<u>value</u> ...]
+ <b>notmuch</b> <b>config</b> <b>set</b> [--database] <<u>section</u>>.<<u>item</u>> [<u>value</u> ...]
<b>notmuch</b> <b>config</b> <b>list</b>
</pre>
The <b>config</b> command can be used to get or set settings in the notmuch
configuration file and corresponding database.
- Items marked <b>[STORED</b> <b>IN</b> <b>DATABASE]</b> are only in the database. They
- should not be placed in the configuration file, and should be accessed
- programmatically as described in the SYNOPSIS above.
-
<b>get</b> The value of the specified configuration item is printed to std‐
out. If the item has multiple values (it is a list), each value
is separated by a newline character.
If no values are provided, the specified configuration item will
be removed from the configuration file.
+ With the <u>--database</u> option, updates configuration metadata
+ stored in the database, rather than the default (text) configu‐
+ ration file.
+
<b>list</b> Every configuration item is printed to stdout, each on a sepa‐
rate line of the form:
The available configuration items are described below.
<b>database.path</b>
- 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 <b>.not-</b>
- <b>much</b>.
+ Notmuch will store its database here, (in sub-directory named
+ <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
+ <b>database.mail</b>_<b>root</b>
+ The top-level directory where your mail currently exists and to
+ where mail will be delivered in the future. Files should be in‐
+ dividual email messages.
+
+ History: this configuration value was introduced in notmuch
+ 0.32.
+
+ Default: For compatibility with older configurations, the value
+ of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
+
+ <b>database.hook</b>_<b>dir</b>
+ Directory containing hooks run by notmuch commands. See <a href='../notmuch-hooks-5/'>not‐</a>
+ <a href='../notmuch-hooks-5/'>much-hooks</a>(5).
+
<b>user.name</b>
Your full name.
A regular expression delimited with // that will be matched
against the path of the file or directory relative to the data‐
base path. Matching files and directories will be ignored. The
- beginning and end of string must be explicitly anchored. For
- example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
+ beginning and end of string must be explicitly anchored. For ex‐
+ ample, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
not "foo" or "bar/foobar".
Default: empty list.
<b>search.exclude</b>_<b>tags</b>
- A list of tags that will be excluded from search results by
- default. Using an excluded tag in a query will override that
- exclusion.
+ A list of tags that will be excluded from search results by de‐
+ fault. Using an excluded tag in a query will override that ex‐
+ clusion.
Default: empty list. Note that <b>notmuch-setup</b>(1) puts
<b>deleted;spam</b> here when creating new configuration file.
Default: <b>true</b>.
- <b>index.decrypt</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
+ <b>index.decrypt</b>
Policy for decrypting encrypted messages during indexing. Must
be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
<b>nostash</b> is the same as <b>true</b> except that it will not stash
newly-discovered session keys in the database.
- From the command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>not‐</a>
- <a href='../notmuch-insert-1/'>much-insert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override
- the database's stored decryption policy with the <b>--decrypt=</b>
- option.
+ From the command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>notmuch-in‐</a>
+ <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
+ base's stored decryption policy with the <b>--decrypt=</b> option.
- Here is a table that summarizes the functionality of each of
+ Here is a table that summarizes the functionality of each of
these policies:
┌──────────────┬───────┬──────┬─────────┬──────┐
│sion keys │ │ │ │ │
├──────────────┼───────┼──────┼─────────┼──────┤
│Index cleart‐ │ │ │ X │ X │
- │ext using │ │ │ │ │
- │secret keys │ │ │ │ │
+ │ext using se‐ │ │ │ │ │
+ │cret keys │ │ │ │ │
├──────────────┼───────┼──────┼─────────┼──────┤
│Stash session │ │ │ │ X │
│keys
├──────────────┼───────┼──────┼─────────┼──────┤
│Delete
│stashed ses‐ │ │ │ │ │
- │sion keys on │ │ │ │ │
+ │sion keys on │ │ │ │ │
│reindex │ │ │ │ │
└──────────────┴───────┴──────┴─────────┴──────┘
- Stashed session keys are kept in the database as properties
-
associated with the message. See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
+ Stashed session keys are kept in the database as properties as‐
+
sociated with the message. See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
<a href='../notmuch-properties-7/'>ties</a>(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 not‐
- much message index is adequately protected. DO NOT USE
- <b>index.decrypt=true</b> or <b>index.decrypt=nostash</b> without considering
+ 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 not‐
+ much message index is adequately protected. DO NOT USE <b>in-</b>
+ <b>dex.decrypt=true</b> or <b>index.decrypt=nostash</b> without considering
the security of your index.
Default: <b>auto</b>.
- <b>index.header.<prefix></b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
- Define the query prefix <prefix>, based on a mail header. For
- example <b>index.header.List=List-Id</b> will add a probabilistic pre‐
- fix <b>List:</b> that searches the <b>List-Id</b> field. User defined pre‐
+ <b>index.header.<prefix></b>
+ Define the query prefix <prefix>, based on a mail header. For
+ example <b>index.header.List=List-Id</b> will add a probabilistic pre‐
+ fix <b>List:</b> that searches the <b>List-Id</b> field. User defined pre‐
fixes must not start with 'a'...'z'; in particular adding a pre‐
- fix with same name as a predefined prefix is not supported. See
- <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and an
+ fix with same name as a predefined prefix is not supported. See
+ <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and an
explanation of probabilistic prefixes.
<b>built</b>_<b>with.<name></b>
Compile time feature <name>. Current possibilities include
- "retry_lock" (configure option, included by default). (since
- notmuch 0.30, "compact" and "field_processor" are always
- included.)
+ "retry_lock" (configure option, included by default). (since
+ notmuch 0.30, "compact" and "field_processor" are always in‐
+ cluded.)
- <b>query.<name></b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
- Expansion
for named query called <name>. See <a href='../notmuch-search-terms-7/'>not‐</a>
+ <b>query.<name></b>
+ Expansion
for named query called <name>. See <a href='../notmuch-search-terms-7/'>not‐</a>
<a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
</pre>
of notmuch.
<b>NOTMUCH</b>_<b>CONFIG</b>
- Specifies the location of the notmuch configuration file. Not‐
- much will use ${HOME}/.notmuch-config if this variable is not
- set.
+ Specifies the location of the notmuch configuration file.
+
+ <b>NOTMUCH</b>_<b>PROFILE</b>
+ Selects among notmuch configurations.
+</pre>
+
+<h2>FILES</h2>
+
+<h3> CONFIGURATION</h3>
+<pre>
+ If <b>NOTMUCH</b>_<b>CONFIG</b> is unset, notmuch tries (in order)
+
+ • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/config</b> where <b><profile></b> is defined
+ by <b>$NOTMUCH</b>_<b>PROFILE</b> or "default"
+
+ • <b>${HOME}/.notmuch-config<profile></b> where <b><profile></b> is <b>.$NOTMUCH</b>_<b>PROFILE</b>
+ or ""
+</pre>
+
+<h3> Hooks</h3>
+<pre>
+ If <b>database.hook</b>_<b>dir</b> is unset, notmuch tries (in order)
+
+ • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/hooks</b> where <b><profile></b> is defined
+ by <b>$NOTMUCH</b>_<b>PROFILE</b> or "default"
+
+ • <b><database.path>/.notmuch/hooks</b>
</pre>
<h2>SEE ALSO</h2>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<b>--output=(messages|threads|files)</b>
<b>messages</b>
- Output the number of matching messages. This is the
- default.
+ Output the number of matching messages. This is the de‐
+ fault.
<b>threads</b>
Output the number of matching threads.
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
one message-id per line, followed by a list of tags.
<b>batch-tag</b>
- The default <b>batch-tag</b> dump format is intended to more
- robust against malformed message-ids and tags containing
+ The default <b>batch-tag</b> dump format is intended to more ro‐
+ bust against malformed message-ids and tags containing
whitespace or non-<b>ascii</b>(7) characters. Each line has the
form:
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
+ and double quotes inside the ID must be doubled. The as‐
+ tute reader will notice this is a special case of the
batch input format for <a href='../notmuch-tag-1/'>notmuch-tag</a>(1); note that the sin‐
gle message-id query is mandatory for <a href='../notmuch-restore-1/'>notmuch-restore</a>(1).
<b>tags</b> Output per-message boolean metadata, namely tags. See
<u>format</u> 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
+ The default is to include all available types of data. The op‐
+ tion 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:
<h2>SEE ALSO</h2>
<pre>
<a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-insert-1/'>not‐</a>
- <a href='../notmuch-insert-1/'>much-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-reply-1/'>not‐</a>
- <a href='../notmuch-reply-1/'>much-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>not‐</a>
- <a href='../notmuch-s
earch-terms-7/'>much-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+ <a href='../notmuch-insert-1/'>much-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-reply-1/'>notmuch-re‐</a>
+ <a href='../notmuch-reply-1/'>ply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),
+ <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
</pre>
<h2>AUTHOR</h2>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<h2>SYNOPSIS</h2>
<pre>
- $DATABASEDIR/.notmuch/hooks/*
+ <hook_dir>/{pre-new, post-new, post-insert}
</pre>
<h2>DESCRIPTION</h2>
<pre>
Hooks are scripts (or arbitrary executables or symlinks to such) that
notmuch invokes before and after certain actions. These scripts reside
- in the .notmuch/hooks directory within the database directory and must
+ in a directory defined as described in <a href='../notmuch-config-1/'>notmuch-config</a>(1). They must
have executable permissions.
The currently available hooks are described below.
<b>pre-new</b>
- This hook is invoked by the <b>new</b> 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 <b>new</b> command.
+ This hook is invoked by the <b>new</b> command before scanning or im‐
+ porting new messages into the database. If this hook exits with
+ a non-zero status, notmuch will abort further processing of the
+ <b>new</b> command.
Typically this hook is used for fetching or delivering new mail
to be imported into the database.
<b>post-new</b>
This hook is invoked by the <b>new</b> 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
+ been imported into the database and initial tags have been ap‐
+ plied. 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
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
base (it has same Message-ID), it will be added to the maildir folder
and notmuch database, but the tags will not be changed.
- The <b>insert</b> command supports hooks. See <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5) for more
- details on hooks.
+ The <b>insert</b> command supports hooks. See <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5) for more de‐
+ tails on hooks.
Option arguments must appear before any tag operation arguments. Sup‐
ported options for <b>insert</b> include
<b>--folder=<</b>folder<b>></b>
Deliver the message to the specified folder, relative to the
- top-level directory given by the value of <b>database.path</b>. The
- default is the empty string, which means delivering to the
+ top-level directory given by the value of <b>database.path</b>. The de‐
+ fault is the empty string, which means delivering to the
top-level directory.
<b>--create-folder</b>
sion 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 <b>--decrypt=true</b> or
- <b>--decrypt=nostash</b> without considering the security of your
- index.
+ <b>--decrypt=nostash</b> without considering the security of your in‐
+ dex.
See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
</pre>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
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 <b>--decrypt=true</b> or
- <b>--decrypt=nostash</b> without considering the security of your
- index.
+ is adequately protected. DO NOT USE <b>--decrypt=true</b> or <b>--de-</b>
+ <b>crypt=nostash</b> without considering the security of your index.
See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
<b>--full-scan</b>
- By default notmuch-new uses directory modification times
- (mtimes) to optimize the scanning of directories for new mail.
+ By default notmuch-new uses directory modification times
+ (mtimes) to optimize the scanning of directories for new mail.
This option turns that optimization off.
</pre>
<h2>SEE ALSO</h2>
<pre>
- <a href='../notmuch-1/'>notmuch</a>(1),
<a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not‐</a>
+ <a href='../notmuch-1/'>notmuch</a>(1),
<a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not‐</a>
<a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-insert-1/'>notmuch-insert</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),
<a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>not‐</a>
<a href='../notmuch-tag-1/'>much-tag</a>(1)
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<b>index.decryption</b>
If a message contains encrypted content, and notmuch tries to
decrypt that content during indexing, it will add the property
- <b>index.decryption=success</b> when the cleartext was successfully
- indexed. If notmuch attempts to decrypt any part of a message
+ <b>index.decryption=success</b> when the cleartext was successfully in‐
+ dexed. If notmuch attempts to decrypt any part of a message
during indexing and that decryption attempt fails, it will add
the property <b>index.decryption=failure</b> to the message.
- Note that it's possible for a single message to have both
- <b>index.decryption=success</b> and <b>index.decryption=failure</b>. Consider
+ Note that it's possible for a single message to have both <b>in-</b>
+ <b>dex.decryption=success</b> and <b>index.decryption=failure</b>. Consider
an encrypted e-mail message that contains another encrypted
e-mail message as an attachment -- if the outer message can be
decrypted, but the attached part cannot, then both properties
present, you should pass those programs <b>--decrypt=false</b>.
Using a stashed session key with "notmuch show" will speed up ren‐
- dering of long encrypted threads. It also allows the user to
- destroy the secret part of any expired encryption-capable subkey
- while still being able to read any retained messages for which they
- have stashed the session key. This enables truly deletable e-mail,
- since (once the session key and asymmetric subkey are both
- destroyed) there are no keys left that can be used to decrypt any
- copy of the original message previously stored by an adversary.
+ dering of long encrypted threads. It also allows the user to de‐
+ stroy the secret part of any expired encryption-capable subkey while
+ still being able to read any retained messages for which they have
+ stashed the session key. This enables truly deletable e-mail, since
+ (once the session key and asymmetric subkey are both destroyed)
+ there are no keys left that can be used to decrypt any copy of the
+ original message previously stored by an adversary.
However, access to the stashed session key for an encrypted message
permits full byte-for-byte reconstruction of the cleartext message.
to both detect and repair such a problematic message, it will do so
during indexing.
- If it applies a message repair during indexing, it will use the
- <b>index.repaired</b> property to note the type of repair(s) it performed.
+ If it applies a message repair during indexing, it will use the <b>in-</b>
+ <b>dex.repaired</b> property to note the type of repair(s) it performed.
<b>index.repaired=skip-protected-headers-legacy-display</b> indicates that
when indexing the cleartext of an encrypted message, notmuch skipped
that message, since it was able to index the built-in protected
headers directly.
- <b>index.repaired=mixedup</b> indicates the repair of a "Mixed Up"
- encrypted PGP/MIME message, a mangling typically produced by Micro‐
+ <b>index.repaired=mixedup</b> indicates the repair of a "Mixed Up" en‐
+ crypted PGP/MIME message, a mangling typically produced by Micro‐
soft's
<u>https://tools.ietf.org/html/draft-dkg-openpgp-pgpmime-message-mangling</u>
for more information.
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<<u>search-term</u>>.
The <b>reindex</b> command searches for all messages matching the supplied
- search terms, and re-creates the full-text index on these messages
- using the supplied options.
+ search terms, and re-creates the full-text index on these messages us‐
+ ing the supplied options.
Supported options for <b>reindex</b> include
sion 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 <b>--decrypt=true</b> or
- <b>--decrypt=nostash</b> without considering the security of your
- index.
+ <b>--decrypt=nostash</b> without considering the security of your in‐
+ dex.
See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
</pre>
A user wants to change their policy going forward to start indexing
cleartext. But they also want indexed access to the cleartext of all
- previously-received encrypted messages. Some messages might have
- already been indexed in the clear (as in the example above). They can
- ask notmuch to just reindex the not-yet-indexed messages:
+ previously-received encrypted messages. Some messages might have al‐
+ ready been indexed in the clear (as in the example above). They can ask
+ notmuch to just reindex the not-yet-indexed messages:
notmuch config set index.decrypt true
notmuch reindex tag:encrypted and not property:index.decryption=success
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<b>json</b> Produces JSON output containing headers for a reply mes‐
sage and the contents of the original message. This out‐
- put can be used by a client to create a reply message
- intelligently.
+ put can be used by a client to create a reply message in‐
+ telligently.
- <b>sexp</b> Produces S-Expression output containing headers for a
- reply message and the contents of the original message.
+ <b>sexp</b> Produces S-Expression output containing headers for a re‐
+ ply message and the contents of the original message.
This output can be used by a client to create a reply
message intelligently.
headers.
<b>--format-version=N</b>
- Use the specified structured output format version. This is
- intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
- omitted, the latest supported version will be used.
+ Use the specified structured output format version. This is in‐
+ tended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If omit‐
+ ted, the latest supported version will be used.
<b>--reply-to=</b>(<b>all</b>|<b>sender</b>)
part will be replaced by the decrypted content.
If <b>auto</b>, and a session key is already known for the message, then it
- will be decrypted, but notmuch will not try to access the user's
- secret keys.
+ will be decrypted, but notmuch will not try to access the user's se‐
+ cret keys.
Use <b>false</b> to avoid even automatic decryption.
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<h2>SYNOPSIS</h2>
<pre>
- <b>notmuch</b> <b>restore</b> [--accumulate] [--format=(auto|batch-tag|sup)]
- [--input=<<u>filename</u>>]
+ <b>notmuch</b> <b>restore</b> [--accumulate] [--format=(auto|batch-tag|sup)] [--in‐
+ put=<<u>filename</u>>]
</pre>
<h2>DESCRIPTION</h2>
<b>notmuch</b> <b>restore</b> updates the maildir flags according to
tag changes if the <b>maildir.synchronize</b>_<b>flags</b> configura‐
- tion option is enabled. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for
- details.
+ tion option is enabled. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for de‐
+ tails.
<b>auto</b> This option (the default) tries to guess the format from
the input. For correctly formed input in either supported
<b>tags</b> Restore per-message metadata, namely tags. See <u>format</u>
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 op‐
+ tion can be specified multiple times to select some subset.
<b>--input=<filename></b>
Read input from given file instead of stdin.
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<h2>DESCRIPTION</h2>
<pre>
- Search for messages matching the given search terms, and display as
- results the threads containing the matched messages.
+ Search for messages matching the given search terms, and display as re‐
+ sults the threads containing the matched messages.
The output consists of one line per thread, giving a thread ID, the
date of the newest (or oldest, depending on the sort option) matched
available).
<b>--format-version=N</b>
- Use the specified structured output format version. This is
- intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
- omitted, the latest supported version will be used.
+ Use the specified structured output format version. This is in‐
+ tended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If omit‐
+ ted, the latest supported version will be used.
<b>--output=(summary|threads|messages|files|tags)</b>
ber matched and the total number), the authors of the
thread and the subject. In the case where a thread con‐
tains multiple files for some messages, the total number
- of files is printed in parentheses (see below for an
- example).
+ of files is printed in parentheses (see below for an ex‐
+ ample).
<b>threads</b>
Output the thread IDs of all threads with any message
<b>messages</b>
Output the message IDs of all messages matching the
search terms, either one per line (<b>--format=text</b>), sepa‐
- rated by null characters (<b>--format=text0</b>), as a JSON
- array (<b>--format=json</b>), or as an S-Expression list (<b>--for-</b>
+ rated by null characters (<b>--format=text0</b>), as a JSON ar‐
+ ray (<b>--format=json</b>), or as an S-Expression list (<b>--for-</b>
<b>mat=sexp</b>).
<b>files</b> Output the filenames of all messages matching the search
<b>tags</b> Output all tags that appear on any message matching the
search terms, either one per line (<b>--format=text</b>), sepa‐
- rated by null characters (<b>--format=text0</b>), as a JSON
- array (<b>--format=json</b>), or as an S-Expression list (<b>--for-</b>
+ rated by null characters (<b>--format=text0</b>), as a JSON ar‐
+ ray (<b>--format=json</b>), or as an S-Expression list (<b>--for-</b>
<b>mat=sexp</b>).
<b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
cal order (<b>oldest-first</b>) or reverse chronological order (<b>new-</b>
<b>est-first</b>).
- Note: The thread order will be distinct between these two
- options (beyond being simply reversed). When sorting by <b>old-</b>
+ Note: The thread order will be distinct between these two op‐
+ tions (beyond being simply reversed). When sorting by <b>old-</b>
<b>est-first</b> the threads will be sorted by the oldest message in
each thread, but when sorting by <b>newest-first</b> the threads will
be sorted by the newest message in each thread.
Prevent excluded messages from matching the search terms.
<b>all</b> Additionally prevent excluded messages from appearing in
- displayed results, in effect behaving as though the
- excluded messages do not exist.
+ displayed results, in effect behaving as though the ex‐
+ cluded messages do not exist.
<b>false</b> Allow excluded messages to match search terms and appear
in displayed results. Excluded messages are still marked
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
terms/phrases in the body, the subject, or any of the sender or recipi‐
ent headers.
- As a special case, a search string consisting of exactly a single
- asterisk ("*") will match all messages.
+ As a special case, a search string consisting of exactly a single as‐
+ terisk ("*") will match all messages.
</pre>
<h3> Search prefixes</h3>
specified relative to the top-level maildir (and without the
leading slash). By default, <b>path:</b> matches messages in the speci‐
fied directory only. The "/**" suffix can be used to match mes‐
- sages in the specified directory and all its subdirectories
- recursively. <b>path:""</b> matches messages in the root of the mail
+ sages in the specified directory and all its subdirectories re‐
+ cursively. <b>path:""</b> matches messages in the root of the mail
store and, likewise, <b>path:**</b> matches all messages.
<b>path:</b> will find a message if <u>any</u> copy of that message is in the
maildir, this includes messages in the "new" and "cur" subdirec‐
tories. The exact syntax for maildir folders depends on your
mail configuration. For maildir++, <b>folder:""</b> matches the inbox
- folder (which is the root in maildir++), other folder names
- always start with ".", and nested folders are separated by "."s,
+ folder (which is the root in maildir++), other folder names al‐
+ ways start with ".", and nested folders are separated by "."s,
such as <b>folder:.classes.topology</b>. For "file system" maildir, the
inbox is typically <b>folder:INBOX</b> and nested folders are separated
by slashes, such as <b>folder:classes/topology</b>.
key can be present on a given message with several different
values. See <a href='../notmuch-properties-7/'>notmuch-properties</a>(7) for more details.
- User defined prefixes are also supported, see <a href='../notmuch-config-1/'>notmuch-config</a>(1) for
- details.
+ User defined prefixes are also supported, see <a href='../notmuch-config-1/'>notmuch-config</a>(1) for de‐
+ tails.
</pre>
<h3> Operators</h3>
There are two ways to turn this off: a search for a capitalized word
will be performed unstemmed, so that one can search for "John" and not
- get results for "Johnson"; phrase searches are also unstemmed (see
- below for details). Stemming is currently only supported for English.
+ get results for "Johnson"; phrase searches are also unstemmed (see be‐
+ low for details). Stemming is currently only supported for English.
Searches for words in other languages will be performed unstemmed.
</pre>
<h3> Boolean and Probabilistic Prefixes</h3>
<pre>
- Xapian (and hence notmuch) prefixes are either <b>boolean</b>, supporting
- exact matches like "<u>tag:inbox</u>" or <b>probabilistic</b>, supporting a more
- flexible <b>term</b> based searching. Certain <b>special</b> prefixes are processed
- by notmuch in a way not strictly fitting either of Xapian's built in
+ Xapian (and hence notmuch) prefixes are either <b>boolean</b>, supporting ex‐
+ act matches like "<u>tag:inbox</u>" or <b>probabilistic</b>, supporting a more flexi‐
+ ble <b>term</b> based searching. Certain <b>special</b> prefixes are processed by
+ notmuch in a way not strictly fitting either of Xapian's built in
styles. The prefixes currently supported by notmuch are as follows.
<b>Boolean</b>
occur in that order. One useful, but initially surprising feature is
that the following are equivalent ways to write the same phrase.
- · "a list of words"
+ • "a list of words"
- · a-list-of-words
+ • a-list-of-words
- · a/list/of/words
+ • a/list/of/words
- · a.list.of.words
+ • a.list.of.words
Both parenthesised lists of terms and quoted phrases are ok with proba‐
bilistic prefixes such as <b>to:</b>, <b>from:</b>, and <b>subject:</b>. In particular
since 1970-01-01 00:00:00 UTC. For example:
date:@<initial-timestamp>..@<final-timestamp>
- Currently, spaces in range expressions are not supported. You can
- replace the spaces with '_', or (in most cases) '-', or (in some cases)
+ Currently, spaces in range expressions are not supported. You can re‐
+ place the spaces with '_', or (in most cases) '-', or (in some cases)
leave the spaces out altogether. Examples in this man page use spaces
for clarity.
Units can be abbreviated to any length, with the otherwise ambiguous
single m being m for minutes and M for months.
- Number can also be written out one, two, ..., ten, dozen, hundred.
- Additionally, the unit may be preceded by "last" or "this" (e.g., "last
+ Number can also be written out one, two, ..., ten, dozen, hundred. Ad‐
+ ditionally, the unit may be preceded by "last" or "this" (e.g., "last
week" or "this month").
When combined with absolute date and time, the relative date and time
<h3> Supported absolute time formats</h3>
<pre>
- · H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
+ • H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
- · H[H] (am|a.m.|pm|p.m.)
+ • H[H] (am|a.m.|pm|p.m.)
- · HHMMSS
+ • HHMMSS
- · now
+ • now
- · noon
+ • noon
- · midnight
+ • midnight
- · Examples: 17:05, 5pm
+ • Examples: 17:05, 5pm
</pre>
<h3> Supported absolute date formats</h3>
<pre>
- · YYYY-MM[-DD]
+ • YYYY-MM[-DD]
- · DD-MM[-[YY]YY]
+ • DD-MM[-[YY]YY]
- · MM-YYYY
+ • MM-YYYY
- · M[M]/D[D][/[YY]YY]
+ • M[M]/D[D][/[YY]YY]
- · M[M]/YYYY
+ • M[M]/YYYY
- · D[D].M[M][.[YY]YY]
+ • D[D].M[M][.[YY]YY]
- · D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
+ • D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
- · Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
+ • Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
- · Wee[kday]
+ • Wee[kday]
Month names can be abbreviated at three or more characters.
<h3> Time zones</h3>
<pre>
- · (+|-)HH:MM
+ • (+|-)HH:MM
- · (+|-)HH[MM]
+ • (+|-)HH[MM]
Some time zone codes, e.g. UTC, EET.
</pre>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
<b>--entire-thread=(true|false)</b>
If true, <b>notmuch</b> <b>show</b> outputs all messages in the thread of any
message matching the search terms; if false, it outputs only the
- matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this
- defaults to true. For other formats, this defaults to false.
+ matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this de‐
+ faults to true. For other formats, this defaults to false.
<b>--format=(text|json|sexp|mbox|raw)</b>
for automated processing. The nested structure of multi‐
part MIME messages is reflected in nested JSON output. By
default JSON output includes all messages in a matching
- thread; that is, by default, <b>--format=json</b> sets
- <b>--entire-thread</b>. The caller can disable this behaviour by
+ thread; that is, by default, <b>--format=json</b> sets <b>--en-</b>
+ <b>tire-thread</b>. The caller can disable this behaviour by
setting <b>--entire-thread=false</b>. The JSON output is always
encoded as UTF-8 and any message content included in the
output will be charset-converted to UTF-8.
decoding and similar functions.
<b>--format-version=N</b>
- Use the specified structured output format version. This is
- intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
- omitted, the latest supported version will be used.
+ Use the specified structured output format version. This is in‐
+ tended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If omit‐
+ ted, the latest supported version will be used.
<b>--part=N</b>
Output the single decoded MIME part N of a single message. The
<b>--decrypt=(false|auto|true|stash)</b>
If <b>true</b>, decrypt any MIME encrypted parts found in the selected
- content (e.g., "multipart/encrypted" parts). Status of the
- decryption will be reported (currently only supported with
- <b>--format=json</b> and <b>--format=sexp</b>) and on successful decryption
- the multipart/encrypted part will be replaced by the decrypted
- content.
+ content (e.g., "multipart/encrypted" parts). Status of the de‐
+ cryption will be reported (currently only supported with <b>--for-</b>
+ <b>mat=json</b> and <b>--format=sexp</b>) and on successful decryption the
+ multipart/encrypted part will be replaced by the decrypted con‐
+ tent.
<b>stash</b> behaves like <b>true</b>, but upon successful decryption it will
also stash the message's session key in the database, and index
Default: <b>auto</b>
<b>--exclude=(true|false)</b>
- Specify whether to omit threads only matching
- search.exclude_tags from the search results (the default) or
- not. In either case the excluded message will be marked with the
- exclude flag (except when output=mbox when there is nowhere to
- put the flag).
+ Specify whether to omit threads only matching search.ex‐
+ clude_tags from the search results (the default) or not. In ei‐
+ ther case the excluded message will be marked with the exclude
+ flag (except when output=mbox when there is nowhere to put the
+ flag).
- If <b>--entire-thread</b> 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 <b>--exclude=true.</b>
+ If <b>--entire-thread</b> is specified then complete threads are re‐
+ turned regardless (with the excluded flag being set when appro‐
+ priate) but threads that only match in an excluded message are
+ not returned when <b>--exclude=true.</b>
The default is <b>--exclude=true.</b>
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
Supported options for <b>tag</b> include
<b>--remove-all</b>
- Remove all tags from each message matching the search terms
- before applying the tag changes appearing on the command line.
+ Remove all tags from each message matching the search terms be‐
+ fore 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.
<h2>COPYRIGHT</h2>
<pre>
- 2009-2020, Carl Worth and many others
+ 2009-2021, Carl Worth and many others
</pre>
-<h2>0.31</h2>
+<h2>0.32</h2>
notmuch_database_remove_message or notmuch_message_delete in one
session has been fixed.
-### As always, the canonical source of API documentation is `lib/notmuch.h`, or the doxygen formatted documentation in `notmuch(3)`
+As always, the canonical source of API documentation is `lib/notmuch.h`,
+or the doxygen formatted documentation in `notmuch(3)`.
CLI
---
projects / notmuch-wiki / commitdiff