From: Tomi Ollila Date: Wed, 13 Jun 2018 20:24:38 +0000 (+0300) Subject: manpages updates for release 0.27 X-Git-Url: https://git.notmuchmail.org/git?p=notmuch-wiki;a=commitdiff_plain;h=47c9a681445722a5b996786fb97df71747615bb7 manpages updates for release 0.27 --- diff --git a/manpages.mdwn b/manpages.mdwn index b677ae1..905b0e8 100644 --- a/manpages.mdwn +++ b/manpages.mdwn @@ -24,4 +24,4 @@ The manual pages are licensed under [the GNU General Public License](https://www.gnu.org/licenses/gpl.txt), either version 3.0 or at your option any later version. -

0.26

+

0.27

diff --git a/manpages/notmuch-1.mdwn b/manpages/notmuch-1.mdwn index cb5242f..cfcb031 100644 --- a/manpages/notmuch-1.mdwn +++ b/manpages/notmuch-1.mdwn @@ -187,4 +187,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-address-1.mdwn b/manpages/notmuch-address-1.mdwn index a62ef71..f612e88 100644 --- a/manpages/notmuch-address-1.mdwn +++ b/manpages/notmuch-address-1.mdwn @@ -130,4 +130,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-compact-1.mdwn b/manpages/notmuch-compact-1.mdwn index dada006..7d84e9b 100644 --- a/manpages/notmuch-compact-1.mdwn +++ b/manpages/notmuch-compact-1.mdwn @@ -64,4 +64,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn index 6a91a06..3f68efe 100644 --- a/manpages/notmuch-config-1.mdwn +++ b/manpages/notmuch-config-1.mdwn @@ -241,4 +241,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-count-1.mdwn b/manpages/notmuch-count-1.mdwn index f28687a..828bff9 100644 --- a/manpages/notmuch-count-1.mdwn +++ b/manpages/notmuch-count-1.mdwn @@ -77,4 +77,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-dump-1.mdwn b/manpages/notmuch-dump-1.mdwn index c939daa..d86c5c8 100644 --- a/manpages/notmuch-dump-1.mdwn +++ b/manpages/notmuch-dump-1.mdwn @@ -117,4 +117,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-emacs-mua-1.mdwn b/manpages/notmuch-emacs-mua-1.mdwn index a12594a..e99c9f6 100644 --- a/manpages/notmuch-emacs-mua-1.mdwn +++ b/manpages/notmuch-emacs-mua-1.mdwn @@ -92,4 +92,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-hooks-5.mdwn b/manpages/notmuch-hooks-5.mdwn index f616177..e589de2 100644 --- a/manpages/notmuch-hooks-5.mdwn +++ b/manpages/notmuch-hooks-5.mdwn @@ -66,4 +66,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-insert-1.mdwn b/manpages/notmuch-insert-1.mdwn index bf44bdc..e7b05b6 100644 --- a/manpages/notmuch-insert-1.mdwn +++ b/manpages/notmuch-insert-1.mdwn @@ -51,22 +51,28 @@ --no-hooks Prevent hooks from being run. + --world-readable + 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. + --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 + 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 + 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 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 --decrypt=true or + index is adequately protected. DO NOT USE --decrypt=true or --decrypt=nostash without considering the security of your index. @@ -75,15 +81,15 @@

EXIT STATUS

-       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 --keep 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 --keep 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.
 
        75 (EX_TEMPFAIL)
@@ -95,7 +101,7 @@
 
 
SEE ALSO

 
-       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not‐
+       notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
        much-hooks(5), notmuch-reply(1), notmuch-restore(1), notmuch-search(1),
        notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1)
 

@@ -110,4 +116,4 @@
        2009-2018, Carl Worth and many others
-

0.26

+

0.27

diff --git a/manpages/notmuch-new-1.mdwn b/manpages/notmuch-new-1.mdwn index 345f510..2c64aad 100644 --- a/manpages/notmuch-new-1.mdwn +++ b/manpages/notmuch-new-1.mdwn @@ -59,6 +59,11 @@ index. See also index.decrypt in notmuch-config(1). + + --full-scan + By default notmuch-new uses directory modification times + (mtimes) to optimize the scanning of directories for new mail. + This option turns that optimization off.

EXIT STATUS

@@ -87,4 +92,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-properties-7.mdwn b/manpages/notmuch-properties-7.mdwn index 45af3a3..eb7537c 100644 --- a/manpages/notmuch-properties-7.mdwn +++ b/manpages/notmuch-properties-7.mdwn @@ -126,4 +126,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-reindex-1.mdwn b/manpages/notmuch-reindex-1.mdwn index 2ca91be..a6beb8d 100644 --- a/manpages/notmuch-reindex-1.mdwn +++ b/manpages/notmuch-reindex-1.mdwn @@ -47,12 +47,41 @@ See also index.decrypt in notmuch-config(1). +

EXAMPLES

+
+       A user just received an encrypted message without indexing its  cleart‐
+       ext.   After  reading it (via notmuch show --decrypt=true), 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 https://trac.xapian.org/ticket/742:
+
+          notmuch config set index.decrypt false
+          notmuch reindex property:index.decryption=success
+          notmuch compact
+
+

SEE ALSO

-       notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
-       much-hooks(5),   notmuch-insert(1),  notmuch-new(1),  notmuch-reply(1),
-       notmuch-restore(1),  notmuch-search(1),  notmuch-search-terms(7),  not‐
-       much-show(1), notmuch-tag(1)
+       notmuch(1),  notmuch-compact(1),  notmuch-config(1),  notmuch-count(1),
+       notmuch-dump(1), notmuch-hooks(5),  notmuch-insert(1),  notmuch-new(1),
+       notmuch-reply(1),     notmuch-restore(1),    notmuch-search(1),    not‐
+       much-search-terms(7), notmuch-show(1), notmuch-tag(1)

AUTHOR

@@ -65,4 +94,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-reply-1.mdwn b/manpages/notmuch-reply-1.mdwn index ff43d28..30910bc 100644 --- a/manpages/notmuch-reply-1.mdwn +++ b/manpages/notmuch-reply-1.mdwn @@ -129,4 +129,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-restore-1.mdwn b/manpages/notmuch-restore-1.mdwn index 1b22757..b4ae210 100644 --- a/manpages/notmuch-restore-1.mdwn +++ b/manpages/notmuch-restore-1.mdwn @@ -102,4 +102,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn index b7ba7db..4adb33b 100644 --- a/manpages/notmuch-search-1.mdwn +++ b/manpages/notmuch-search-1.mdwn @@ -147,9 +147,9 @@ 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)

EXIT STATUS

@@ -179,4 +179,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn index 0259d42..e6b87a3 100644 --- a/manpages/notmuch-search-terms-7.mdwn +++ b/manpages/notmuch-search-terms-7.mdwn @@ -45,7 +45,7 @@ results to those whose value matches a regular expression (see regex(7)) delimited with //, for example: - notmuch search 'from:/bob@.*[.]example[.]com/' + notmuch search 'from:"/bob@.*[.]example[.]com/"' from:<name-or-address> or from:/<regex>/ The from: prefix is used to match the name or address of the @@ -86,50 +86,65 @@ messages). These thread ID values can be seen in the first col‐ umn of output from notmuch search + thread:{<notmuch query>} + If notmuch is built with Xapian Field Processors (see below), + threads may be searched for indirectly by providing an arbitrary + notmuch query in {}. 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 thread:{<something>} as + expanding to all of the thread IDs which match <something>; not‐ + much then performs a second search using the expanded query. + path:<directory-path> or path:<directory-path>/** or path:/<regex>/ The path: 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, path: 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. path:"" 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. path:"" matches messages in the root of the mail store and, likewise, path:** matches all messages. - path: will find a message if any copy of that message is in the + path: will find a message if any copy of that message is in the specific directory. folder:<maildir-folder> or folder:/<regex>/ - The folder: prefix searches for email messages by maildir or MH - folder. For MH-style folders, this is equivalent to path:. For + The folder: prefix searches for email messages by maildir or MH + folder. For MH-style folders, this is equivalent to path:. 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++, folder:"" 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++, folder:"" 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 folder:.classes.topology. For "file system" maildir, the inbox is typically folder:INBOX and nested folders are separated by slashes, such as folder:classes/topology. - folder: will find a message if any copy of that message is in + folder: will find a message if any copy of that message is in the specific folder. date:<since>..<until> or date:<date> - The date: prefix can be used to restrict the results to only - messages within a particular time range (based on the Date: + The date: prefix can be used to restrict the results to only + messages within a particular time range (based on the Date: header). - See DATE AND TIME SEARCH below for details on the range expres‐ + See DATE AND TIME SEARCH 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. lastmod:<initial-revision>..<final-revision> The lastmod: prefix can be used to restrict the result by the @@ -260,13 +275,32 @@ will not. +

  Quoting

+
+       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}'
+
+

DATE AND TIME SEARCH

-       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.
@@ -274,15 +308,21 @@ 
        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
@@ -391,6 +431,8 @@
        · named queries e.g. "query:my_special_query"
 
        · regular expression searches, e.g. "subject:/^\[SPAM\]/"
+
+       · thread subqueries, e.g. "thread:{from:bob}"

SEE ALSO

@@ -411,4 +453,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn index 4902b5a..39f1845 100644 --- a/manpages/notmuch-show-1.mdwn +++ b/manpages/notmuch-show-1.mdwn @@ -110,7 +110,7 @@ supported with --format=json and --format=sexp), and the multi‐ part/signed part will be replaced by the signed data. - --decrypt=(false|auto|true) + --decrypt=(false|auto|true|stash) If true, 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 @@ -118,50 +118,81 @@ the multipart/encrypted part will be replaced by the decrypted content. - If auto, and a session key is already known for the message, - then it will be decrypted, but notmuch will not try to access + stash behaves like true, 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 auto, 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 false to avoid even automatic decryption. - Non-automatic decryption expects a functioning gpg-agent(1) to - provide any needed credentials. Without one, the decryption will + Non-automatic decryption (stash or true, in the absence of a + stashed session key) expects a functioning gpg-agent(1) to pro‐ + vide any needed credentials. Without one, the decryption will fail. - Note: true implies --verify. + Note: setting either true or stash here implies --verify. + + 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: --decrypt=stash requires write access to the database. + Otherwise, notmuch show operates entirely in read-only mode. 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 + 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 --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 + 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 "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 + 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 seen in the first column of output from the notmuch search command. @@ -177,8 +208,8 @@

SEE ALSO

-       notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
-       much-hooks(5),   notmuch-insert(1),  notmuch-new(1),  notmuch-reply(1),
+       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not‐
+       much-hooks(5),  notmuch-insert(1),  notmuch-new(1),   notmuch-reply(1),
        notmuch-restore(1),  notmuch-search(1),  notmuch-search-terms(7),  not‐
        much-tag(1)
@@ -193,4 +224,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27

diff --git a/manpages/notmuch-tag-1.mdwn b/manpages/notmuch-tag-1.mdwn index 354ce46..45d9e55 100644 --- a/manpages/notmuch-tag-1.mdwn +++ b/manpages/notmuch-tag-1.mdwn @@ -116,4 +116,4 @@ 2009-2018, Carl Worth and many others -

0.26

+

0.27