[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.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
<b>--no-hooks</b>
Prevent hooks from being run.
+ <b>--world-readable</b>
+ When writing mail to the mailbox, allow it to be read by users
+ other than the current user. Note that this does not override
+ umask. By default, delivered mail is only readable by the cur‐
+ rent user.
+
<b>--decrypt=(true|nostash|auto|false)</b>
If <b>true</b> and the message is encrypted, try to decrypt the message
- while indexing, stashing any session keys discovered. If <b>auto</b>,
- 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
+ while indexing, stashing any session keys discovered. If <b>auto</b>,
+ 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).
- <b>nostash</b> is the same as <b>true</b> except that it will not stash
+ <b>nostash</b> is the same as <b>true</b> except that it will not stash
newly-discovered session keys in the database.
Be aware that the index is likely sufficient (and a stashed ses‐
- sion key is certainly sufficient) to reconstruct the cleartext
+ 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
+ index is adequately protected. DO NOT USE <b>--decrypt=true</b> or
<b>--decrypt=nostash</b> without considering the security of your
index.
<h2>EXIT STATUS</h2>
<pre>
- This command returns exit status 0 on successful mail delivery,
- non-zero otherwise. The default is to indicate failed mail delivery on
- any errors, including message file delivery to the filesystem, message
- indexing to Notmuch database, changing tags, and synchronizing tags to
- maildir flags. The <b>--keep</b> option may be used to settle for successful
+ This command returns exit status 0 on successful mail delivery,
+ non-zero otherwise. The default is to indicate failed mail delivery on
+ any errors, including message file delivery to the filesystem, message
+ indexing to Notmuch database, changing tags, and synchronizing tags to
+ maildir flags. The <b>--keep</b> option may be used to settle for successful
message file delivery.
This command supports the following special exit status code for errors
- most likely to be temporary in nature, e.g. failure to get a database
+ most likely to be temporary in nature, e.g. failure to get a database
write lock.
<b>75</b> <b>(EX</b>_<b>TEMPFAIL)</b>
<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-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/'>notmuch-tag</a>(1)
</pre>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
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.
+ This option turns that optimization off.
</pre>
<h2>EXIT STATUS</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
</pre>
+<h2>EXAMPLES</h2>
+<pre>
+ A user just received an encrypted message without indexing its cleart‐
+ ext. After reading it (via <b>notmuch</b> <b>show</b> <b>--decrypt=true</b>), they decide
+ that they want to index its cleartext so that they can easily find it
+ later and read it without having to have access to their secret keys:
+
+ notmuch reindex --decrypt=true id:1234567@example.com
+
+ 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:
+
+ notmuch config set index.decrypt true
+ notmuch reindex tag:encrypted and not property:index.decryption=success
+
+ Later, the user changes their mind, and wants to stop indexing cleart‐
+ ext (perhaps their threat model has changed, or their trust in their
+ index store has been shaken). They also want to clear all of their old
+ cleartext from the index. Note that they compact the database after‐
+ ward as a workaround for <u>https://trac.xapian.org/ticket/742</u>:
+
+ notmuch config set index.decrypt false
+ notmuch reindex property:index.decryption=success
+ notmuch compact
+</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-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-insert-1/'>notmuch-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</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/'>not‐</a>
- <a href='../notmuch-s
how-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+ <a href='../notmuch-1/'>notmuch</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/'>notmuch-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-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/'>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)
</pre>
<h2>AUTHOR</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
message having multiple filenames.
% notmuch search date:today.. and tag:bad-news
- thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread)
- thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread)
- thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread)
+ thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
+ thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
+ thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)
</pre>
<h2>EXIT STATUS</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
results to those whose value matches a regular expression (see
<b>regex</b>(7)) delimited with //, for example:
- notmuch search 'from:/bob@.*[.]example[.]com/'
+ notmuch search 'from:"/bob@.*[.]example[.]com/"'
<b>from:<name-or-address></b> <b>or</b> <b>from:/<regex>/</b>
The <b>from:</b> prefix is used to match the name or address of the
messages). These thread ID values can be seen in the first col‐
umn of output from <b>notmuch</b> <b>search</b>
+ <b>thread:{<notmuch</b> <b>query>}</b>
+ If notmuch is built with <b>Xapian</b> <b>Field</b> <b>Processors</b> (see below),
+ threads may be searched for indirectly by providing an arbitrary
+ notmuch query in <b>{}</b>. For example, the following returns threads
+ containing a message from mallory and one (not necessarily the
+ same message) with Subject containing the word "crypto".
+
+ % notmuch search 'thread:"{from:mallory}" and thread:"{subject:crypto}"'
+
+ The performance of such queries can vary wildly. To understand
+ this, the user should think of the query <b>thread:{<something>}</b> as
+ expanding to all of the thread IDs which match <b><something></b>; not‐
+ much then performs a second search using the expanded query.
+
<b>path:<directory-path></b> <b>or</b> <b>path:<directory-path>/**</b> <b>or</b> <b>path:/<regex>/</b>
The <b>path:</b> prefix searches for email messages that are in partic‐
- ular directories within the mail store. The directory must be
- specified relative to the top-level maildir (and without the
+ ular directories within the mail store. The directory must be
+ 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
+ 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
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
+ <b>path:</b> will find a message if <u>any</u> copy of that message is in the
specific directory.
<b>folder:<maildir-folder></b> <b>or</b> <b>folder:/<regex>/</b>
- The <b>folder:</b> prefix searches for email messages by maildir or MH
- folder. For MH-style folders, this is equivalent to <b>path:</b>. For
+ The <b>folder:</b> prefix searches for email messages by maildir or MH
+ folder. For MH-style folders, this is equivalent to <b>path:</b>. For
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
+ 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,
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>.
- <b>folder:</b> will find a message if <u>any</u> copy of that message is in
+ <b>folder:</b> will find a message if <u>any</u> copy of that message is in
the specific folder.
<b>date:<since>..<until></b> <b>or</b> <b>date:<date></b>
- The <b>date:</b> prefix can be used to restrict the results to only
- messages within a particular time range (based on the Date:
+ The <b>date:</b> prefix can be used to restrict the results to only
+ messages within a particular time range (based on the Date:
header).
- See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expres‐
+ See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expres‐
sion, and supported syntax for <since> and <until> date and time
expressions.
- The time range can also be specified using timestamps with a
- syntax of:
+ The time range can also be specified using timestamps without
+ including the date prefix using a syntax of:
<initial-timestamp>..<final-timestamp>
- Each timestamp is a number representing the number of seconds
- since 1970-01-01 00:00:00 UTC.
+ Each timestamp is a number representing the number of seconds
+ since 1970-01-01 00:00:00 UTC. Specifying a time range this way
+ is considered legacy and predates the date prefix.
<b>lastmod:<initial-revision>..<final-revision></b>
The <b>lastmod:</b> prefix can be used to restrict the result by the
will not.
</pre>
+<h3> Quoting</h3>
+<pre>
+ Double quotes are also used by the notmuch query parser to protect
+ boolean terms, regular expressions, or subqueries containing spaces or
+ other special characters, e.g.
+
+ tag:"a tag"
+
+ folder:"/^.*/(Junk|Spam)$/"
+
+ thread:"{from:mallory and date:2009}"
+
+ As with phrases, you need to protect the double quotes from the shell
+ e.g.
+
+ % notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
+ % notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
+</pre>
+
<h2>DATE AND TIME SEARCH</h2>
<pre>
- notmuch understands a variety of standard and natural ways of express‐
+ notmuch understands a variety of standard and natural ways of express‐
ing dates and times, both in absolute terms ("2012-10-24") and in rela‐
- tive terms ("yesterday"). Any number of relative terms can be combined
- ("1 hour 25 minutes") and an absolute date/time can be combined with
- relative terms to further adjust it. A non-exhaustive description of
+ tive terms ("yesterday"). Any number of relative terms can be combined
+ ("1 hour 25 minutes") and an absolute date/time can be combined with
+ relative terms to further adjust it. A non-exhaustive description of
the syntax supported for absolute and relative terms is given below.
</pre>
<pre>
date:<since>..<until>
- The above expression restricts the results to only messages from
+ The above expression restricts the results to only messages from
<since> to <until>, based on the Date: header.
- <since> and <until> can describe imprecise times, such as "yesterday".
- In this case, <since> is taken as the earliest time it could describe
+ <since> and <until> can describe imprecise times, such as "yesterday".
+ In this case, <since> is taken as the earliest time it could describe
(the beginning of yesterday) and <until> is taken as the latest time it
- could describe (the end of yesterday). Similarly, date:january..febru‐
+ could describe (the end of yesterday). Similarly, date:january..febru‐
ary matches from the beginning of January to the end of February.
+ If specifying a time range using timestamps in conjunction with the
+ date prefix, each timestamp must be preceded by @ (ASCII hex 40). As
+ above, each timestamp is a number representing the number of seconds
+ since 1970-01-01 00:00:00 UTC. For example:
+ date:@<initial-timestamp>..@<final-timestamp>
+
date:<expr>..! can be used as a shorthand for date:<expr>..<expr>. The
expansion takes place before interpretation, and thus, for example,
date:monday..! matches from the beginning of Monday until the end of
· named queries e.g. "query:my_special_query"
· regular expression searches, e.g. "subject:/^\[SPAM\]/"
+
+ · thread subqueries, e.g. "thread:{from:bob}"
</pre>
<h2>SEE ALSO</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
supported with --format=json and --format=sexp), and the multi‐
part/signed part will be replaced by the signed data.
- <b>--decrypt=(false|auto|true)</b>
+ <b>--decrypt=(false|auto|true|stash)</b>
If <b>true</b>, decrypt any MIME encrypted parts found in the selected
content (i.e. "multipart/encrypted" parts). Status of the
decryption will be reported (currently only supported with
the multipart/encrypted 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
+ <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
+ the cleartext of the message, enabling automatic decryption in
+ the future.
+
+ 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 keys.
Use <b>false</b> to avoid even automatic decryption.
- Non-automatic decryption expects a functioning <b>gpg-agent</b>(1) to
- provide any needed credentials. Without one, the decryption will
+ Non-automatic decryption (<b>stash</b> or <b>true</b>, in the absence of a
+ stashed session key) expects a functioning <b>gpg-agent</b>(1) to pro‐
+ vide any needed credentials. Without one, the decryption will
fail.
- Note: <b>true</b> implies --verify.
+ Note: setting either <b>true</b> or <b>stash</b> here implies <b>--verify</b>.
+
+ Here is a table that summarizes each of these policies:
+
+ ┌──────────────┬───────┬──────┬──────┬───────┐
+ │ │ false │ auto │ true │ stash │
+ ├──────────────┼───────┼──────┼──────┼───────┤
+ │Show cleart‐ │ │ X │ X │ X │
+ │ext if ses‐ │ │ │ │ │
+ │sion key is │ │ │ │ │
+ │already known │ │ │ │ │
+ ├──────────────┼───────┼──────┼──────┼───────┤
+ │Use secret │ │ │ X │ X │
+ │keys to show │ │ │ │ │
+ │cleartext │ │ │ │ │
+ ├──────────────┼───────┼──────┼──────┼───────┤
+ │Stash any │ │ │ │ X │
+ │newly recov‐ │ │ │ │ │
+ │ered session │ │ │ │ │
+ │keys, rein‐ │ │ │ │ │
+ │dexing mes‐ │ │ │ │ │
+ │sage if found │ │ │ │ │
+ └──────────────┴───────┴──────┴──────┴───────┘
+
+ Note: <b>--decrypt=stash</b> requires write access to the database.
+ Otherwise, <b>notmuch</b> <b>show</b> operates entirely in read-only mode.
Default: <b>auto</b>
<b>--exclude=(true|false)</b>
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
+ 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
+ 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>
The default is <b>--exclude=true.</b>
<b>--body=(true|false)</b>
- If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the
- messages in the output; if false, bodies are omitted.
- <b>--body=false</b> is only implemented for the json and sexp formats
+ If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the
+ messages in the output; if false, bodies are omitted.
+ <b>--body=false</b> is only implemented for the json and sexp formats
and it is incompatible with <b>--part</b> <b>></b> <b>0.</b>
This is useful if the caller only needs the headers as body-less
output is much faster and substantially smaller.
<b>--include-html</b>
- Include "text/html" parts as part of the output (currently only
- supported with --format=json and --format=sexp). By default,
- unless <b>--part=N</b> is used to select a specific part or
+ Include "text/html" parts as part of the output (currently only
+ supported with --format=json and --format=sexp). By default,
+ unless <b>--part=N</b> is used to select a specific part or
<b>--include-html</b> is used to include all "text/html" parts, no part
with content type "text/html" is included in the output.
- A common use of <b>notmuch</b> <b>show</b> is to display a single thread of email
+ A common use of <b>notmuch</b> <b>show</b> is to display a single thread of email
messages. For this, use a search term of "thread:<thread-id>" as can be
seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
</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-hooks-5/'>much-hooks</a>(5),
<a href='../notmuch-insert-1/'>notmuch-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
+ <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-new-1/'>notmuch-new</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-tag-1/'>not‐</a>
<a href='../notmuch-tag-1/'>much-tag</a>(1)
</pre>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
2009-2018, Carl Worth and many others
</pre>
-<h2>0.26</h2>
+<h2>0.27</h2>
projects / notmuch-wiki / commitdiff