]> git.cworth.org Git - obsolete/notmuch-wiki/commitdiff
manpages 0.15
authorTomi Ollila <tomi.ollila@iki.fi>
Sat, 19 Jan 2013 17:15:09 +0000 (19:15 +0200)
committerTomi Ollila <tomi.ollila@iki.fi>
Sat, 19 Jan 2013 17:15:09 +0000 (19:15 +0200)
14 files changed:
manpages.mdwn
manpages/notmuch-1.mdwn
manpages/notmuch-config-1.mdwn
manpages/notmuch-count-1.mdwn
manpages/notmuch-dump-1.mdwn
manpages/notmuch-hooks-5.mdwn
manpages/notmuch-new-1.mdwn
manpages/notmuch-reply-1.mdwn
manpages/notmuch-restore-1.mdwn
manpages/notmuch-search-1.mdwn
manpages/notmuch-search-terms-7.mdwn
manpages/notmuch-setup-1.mdwn
manpages/notmuch-show-1.mdwn
manpages/notmuch-tag-1.mdwn

index 1953ff692a3d1e53b5fbfacac8729e0464471d26..6bb01fac00411709c556dd73e42a00e21c80ca76 100644 (file)
@@ -14,5 +14,3 @@ Manual page index
 * <a href='notmuch-tag-1/'>notmuch-tag</a>(1) - add/remove tags for all messages matching the search terms
 * <a href='notmuch-hooks-5/'>notmuch-hooks</a>(5) - hooks for notmuch
 * <a href='notmuch-search-terms-7/'>notmuch-search-terms</a>(7) - syntax for notmuch queries
 * <a href='notmuch-tag-1/'>notmuch-tag</a>(1) - add/remove tags for all messages matching the search terms
 * <a href='notmuch-hooks-5/'>notmuch-hooks</a>(5) - hooks for notmuch
 * <a href='notmuch-search-terms-7/'>notmuch-search-terms</a>(7) - syntax for notmuch queries
-
-<h2>Notmuch 0.14</h2>
index 98d0d815a62c75b77aec0862db15048af0bd6fe9..3e9ad0687e64824292cc96aa453934358dd9a2aa 100644 (file)
        (server: irc.freenode.net, channel: #notmuch).
 </pre>
 
        (server: irc.freenode.net, channel: #notmuch).
 </pre>
 
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index e54a4f09e5facf5589f5afd73eee2fe3a0c47e6c..b9850cf65c907dc2ba33bfae1979b6e1738fe14f 100644 (file)
        <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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index b917808624f94e2f165f087ab98bb2401413d23a..9d9767f182245886bcf1e3926c400eb104fbf364 100644 (file)
@@ -48,4 +48,4 @@
        <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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 92424b6f3d81ab828bfff10fda807612c0d83bb0..743be97f87469d3b97431ed42096913432ddb0b0 100644 (file)
@@ -7,7 +7,8 @@
 
 <h2>SYNOPSIS</h2>
 <pre>
 
 <h2>SYNOPSIS</h2>
 <pre>
-       <b>notmuch</b> <b>dump</b> [ --output=&lt;<u>filename</u>&gt; ] [--] [ &lt;<u>search-term</u>&gt;...]
+       <b>notmuch</b>  <b>dump</b>  [<b>--format=(sup|batch-tag)</b>]  [--] [ --output=&lt;<u>filename</u>&gt; ]
+       [--] [ &lt;<u>search-term</u>&gt;...]
 </pre>
 
 <h2>DESCRIPTION</h2>
 </pre>
 
 <h2>DESCRIPTION</h2>
 
        Output is to the given filename, if any, or to stdout.
 
 
        Output is to the given filename, if any, or to stdout.
 
-       These  tags  are  the  only  data in the notmuch database that can&apos;t be
-       recreated from the messages themselves.  The output of notmuch dump  is
-       therefore  the only critical thing to backup (and much more friendly to
+       These tags are the only data in the  notmuch  database  that  can&apos;t  be
+       recreated  from the messages themselves.  The output of notmuch dump is
+       therefore the only critical thing to backup (and much more friendly  to
        incremental backup than the native database files.)
 
        incremental backup than the native database files.)
 
-       With no search terms, a dump of all messages in the  database  will  be
-       generated.   A &quot;--&quot; argument instructs notmuch that the remaining argu-
-       ments are search terms.
+       <b>--format=(sup|batch-tag)</b>
 
 
-       See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
-       &lt;search-terms&gt;.
+           Notmuch restore supports two plain text dump formats, both with one
+           message-id per line, followed by a list of tags.
+
+           <b>sup</b>  The <b>sup</b> dump file format is specifically chosen to be compati-
+               ble  with  the  format  of  files  produced by sup-dump.  So if
+               you&apos;ve previously been using sup for  mail,  then  the  <b>notmuch</b>
+               <b>restore</b>  command  provides you a way to import all of your tags
+               (or labels as sup calls them).  Each  line  has  the  following
+               form
+
+               &lt;<u>message-id</u>&gt; <b>(</b> &lt;<u>tag</u>&gt; ...  <b>)</b>
+
+               with zero or more tags are separated by spaces. Note that (mal-
+               formed) message-ids may contain arbitrary non-null  characters.
+               Note  also that tags with spaces will not be correctly restored
+               with this format.
+
+           <b>batch-tag</b>
+
+               The <b>batch-tag</b> dump format is intended to  more  robust  against
+               malformed  message-ids  and  tags containing whitespace or non-
+               <b>ascii</b>(7) characters.  Each line has the form
+
+               +&lt;<u>encoded-tag</u>&gt; +&lt;<u>encoded-tag</u>&gt; ... --  id:&lt;<u>quoted-message-id</u>&gt;
+
+               Tags are hex-encoded by replacing every byte not  matching  the
+               regex <b>[A-Za-z0-9@=.,</b>_<b>+-]</b> with <b>%nn</b> 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 whites-
+               pace 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 <a href='../notmuch-tag-1/'>notmuch-tag</a>(1); note that
+               the  single  message-id  query  is   mandatory   for   <a href='../notmuch-restore-1/'>notmuch-</a>
+               <a href='../notmuch-restore-1/'>restore</a>(1).
+
+           With  no  search terms, a dump of all messages in the database will
+           be generated.  A &quot;--&quot; argument instructs notmuch that the remaining
+           arguments are search terms.
+
+           See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for
+           &lt;search-terms&gt;.
 </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-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-new-1/'>not-</a>
 </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-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-new-1/'>not-</a>
-       <a href='../notmuch-new-1/'>much-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-new-1/'>much-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/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 </pre>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 207c29fa1166584f376b7e435a6edb5ac3b4f2f0..a813dfd235d46a7ffde93b44babacdd41eb75f6c 100644 (file)
@@ -45,4 +45,4 @@
        <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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 6977e21354ee2176adadc970855230e39e212d5b..fee5ceabd814881c1e45d828ae00748304c29a9d 100644 (file)
@@ -50,4 +50,4 @@
        <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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 9fe27951786a7d14b0ed632ce1824dff79a5557e..0d9f8c2d5ecef019fe6669ad34b4d69b28a9ecad 100644 (file)
@@ -34,7 +34,7 @@
 
        Supported options for <b>reply</b> include
 
 
        Supported options for <b>reply</b> include
 
-              <b>--format=</b>(<b>default</b>|<b>json</b>|<b>headers-only</b>)
+              <b>--format=</b>(<b>default</b>|<b>json</b>|<b>sexp</b>|<b>headers-only</b>)
 
                   <b>default</b>
                       Includes subject and quoted message body.
 
                   <b>default</b>
                       Includes subject and quoted message body.
                       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
                       intelligently.
 
+                  <b>sexp</b>
+                      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.
+
                   <b>headers-only</b>
                   <b>headers-only</b>
-                      Only produces In-Reply-To, References, To, Cc,  and  Bcc
+                      Only  produces  In-Reply-To, References, To, Cc, and Bcc
                       headers.
 
                       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.
+
               <b>--reply-to=</b>(<b>all</b>|<b>sender</b>)
 
                   <b>all</b> (default)
                       Replies to all addresses.
 
                   <b>sender</b>
               <b>--reply-to=</b>(<b>all</b>|<b>sender</b>)
 
                   <b>all</b> (default)
                       Replies to all addresses.
 
                   <b>sender</b>
-                      Replies  only  to  the sender. If replying to user&apos;s own
-                      message (Reply-to: or From: header is one of the  user&apos;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&apos;s
+                      Replies only to the sender. If replying  to  user&apos;s  own
+                      message  (Reply-to: or From: header is one of the user&apos;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&apos;s
                       addresses.
 
               <b>--decrypt</b>
 
                       addresses.
 
               <b>--decrypt</b>
 
-                  Decrypt any MIME  encrypted  parts  found  in  the  selected
-                  content  (ie.  &quot;multipart/encrypted&quot;  parts).  Status of the
-                  decryption will be reported (currently only  supported  with
-                  --format=json)  and  the  multipart/encrypted  part  will be
-                  replaced by the decrypted content.
+                  Decrypt  any MIME encrypted parts found in the selected con-
+                  tent  (ie.  &quot;multipart/encrypted&quot;  parts).  Status  of   the
+                  decryption  will  be reported (currently only supported with
+                  --format=json and --format=sexp) and the multipart/encrypted
+                  part will be replaced by the decrypted content.
 
 
-       See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
+       See  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for  details  of the supported syntax for
        &lt;search-terms&gt;.
 
        &lt;search-terms&gt;.
 
-       Note:  It  is  most  common  to  use <b>notmuch</b> <b>reply</b> with a search string
-       matching a single message, (such as id:&lt;message-id&gt;),  but  it  can  be
+       Note: It is most common to use  <b>notmuch</b>  <b>reply</b>  with  a  search  string
+       matching  a  single  message,  (such as id:&lt;message-id&gt;), but it can be
        useful to reply to several messages at once. For example, when a series
        useful to reply to several messages at once. For example, when a series
-       of patches are sent in a single thread, replying to the  entire  thread
-       allows  for  the  reply to comment on issues found in multiple patches.
-       The default format supports replying to multiple messages at once,  but
-       the JSON format does not.
+       of  patches  are sent in a single thread, replying to the entire thread
+       allows for the reply to comment on issues found  in  multiple  patches.
+       The  default format supports replying to multiple messages at once, but
+       the JSON and S-Expression formats do not.
+</pre>
+
+<h2>EXIT STATUS</h2>
+<pre>
+       This command supports the following special exit status codes
+
+       <b>20</b>     The requested format version is too old.
+
+       <b>21</b>     The requested format version is too new.
 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
 </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-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</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-new-1/'>notmuch-new</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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 555ae6ac0393846f5430f40c20252dd4447222f8..87869c9b61f8882212e0f7ed8dcd2d636fe44cdb 100644 (file)
@@ -8,7 +8,8 @@
 
 <h2>SYNOPSIS</h2>
 <pre>
 
 <h2>SYNOPSIS</h2>
 <pre>
-       <b>notmuch</b> <b>restore</b> [<b>--accumulate</b>] [ --input=&lt;<u>filename</u>&gt; ]
+       <b>notmuch</b>  <b>restore</b>   [<b>--accumulate</b>]   [<b>--format=(auto|batch-tag|sup)</b>]   [
+       --input=&lt;<u>filename</u>&gt; ]
 </pre>
 
 <h2>DESCRIPTION</h2>
 </pre>
 
 <h2>DESCRIPTION</h2>
 
        The input is read from the given filename, if any, or from stdin.
 
 
        The input is read from the given filename, if any, or from stdin.
 
-       Note: The dump file format is specifically chosen to be compatible with
-       the format of files produced by sup-dump.  So if you&apos;ve previously been
-       using sup for mail, then the <b>notmuch</b> <b>restore</b> command provides you a way
-       to import all of your tags (or labels as sup calls them).
+       Supported options for <b>restore</b> include
 
 
-       The  --accumulate  switch causes the union of the existing and new tags
-       to be applied, instead of replacing each message&apos;s  tags  as  they  are
-       read in from the dump file.
+           <b>--accumulate</b>
 
 
-       See  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for  details  of the supported syntax for
-       &lt;search-terms&gt;.
+               The  union  of the existing and new tags is applied, instead of
+               replacing each message&apos;s tags as they are read in from the dump
+               file.
 
 
-       <b>notmuch</b> <b>restore</b> updates the maildir flags according to tag  changes  if
-       the <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>not-</a>
-       <a href='../notmuch-config-1/'>much-config</a>(1) for details.
+           <b>--format=(sup|batch-tag|auto)</b>
+
+               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 <a href='../notmuch-dump-1/'>notmuch-dump</a>(1).
+
+               <b>sup</b>  The <b>sup</b> dump file format is specifically chosen to be com-
+                   patible with the format of files produced by sup-dump.   So
+                   if you&apos;ve previously been using sup for mail, then the <b>not-</b>
+                   <b>much</b> <b>restore</b> command provides you a way to  import  all  of
+                   your tags (or labels as sup calls them).
+
+               <b>batch-tag</b>
+
+                   The  <b>batch-tag</b>  dump  format  is  intended  to  more robust
+                   against malformed message-ids and tags  containing  whites-
+                   pace  or  non-<b>ascii</b>(7) characters.  See <a href='../notmuch-dump-1/'>notmuch-dump</a>(1) for
+                   details on this format.
+
+                   <b>notmuch</b> <b>restore</b> updates the maildir flags according to  tag
+                   changes   if  the  <b>maildir.synchronize</b>_<b>flags</b>  configuration
+                   option is enabled. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for details.
+
+               <b>auto</b>
+
+                   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  for-
+                   mat contains no parentheses, should be accurate.
 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
 </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-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</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-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</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>
 
        <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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index b0428151d1eb3a8831d1488344a843edc186941c..5afb0f731022dcdfc7166d5bfd22a11e48c30aa0 100644 (file)
 
        Supported options for <b>search</b> include
 
 
        Supported options for <b>search</b> include
 
-           <b>--format=</b>(<b>json</b>|<b>text</b>)
+           <b>--format=</b>(<b>json</b>|<b>sexp</b>|<b>text</b>|<b>text0</b>)
 
 
-               Presents the results in either JSON or plain-text (default).
+               Presents  the  results  in  either JSON, S-Expressions, newline
+               character separated plain-text  (default),  or  null  character
+               separated  plain-text (compatible with <b>xargs</b>(1) -0 option where
+               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.
 
            <b>--output=(summary|threads|messages|files|tags)</b>
 
                <b>summary</b>
 
 
            <b>--output=(summary|threads|messages|files|tags)</b>
 
                <b>summary</b>
 
-                   Output  a  summary of each thread with any message matching
+                   Output a summary of each thread with any  message  matching
                    the search terms. The summary includes the thread ID, date,
                    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
+                   the number of messages  in  the  thread  (both  the  number
+                   matched  and  the  total number), the authors of the thread
                    and the subject.
 
                <b>threads</b>
 
                    and the subject.
 
                <b>threads</b>
 
-                   Output  the  thread  IDs  of  all  threads with any message
-                   matching the search terms,  either  one  per  line  (--for-
-                   mat=text) or as a JSON array (--format=json).
+                   Output the thread IDs  of  all  threads  with  any  message
+                   matching  the  search  terms,  either  one per line (--for-
+                   mat=text), separated by null  characters  (--format=text0),
+                   as  a  JSON  array (--format=json), or an S-Expression list
+                   (--format=sexp).
 
                <b>messages</b>
 
 
                <b>messages</b>
 
-                   Output  the message IDs of all messages matching the search
-                   terms, either one per line (--format=text)  or  as  a  JSON
-                   array (--format=json).
+                   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  (--for-
+                   mat=json), or as an S-Expression list (--format=sexp).
 
                <b>files</b>
 
                    Output  the  filenames  of all messages matching the search
 
                <b>files</b>
 
                    Output  the  filenames  of all messages matching the search
-                   terms, either one per line (--format=text)  or  as  a  JSON
-                   array (--format=json).
+                   terms, either one per line  (--format=text),  separated  by
+                   null  characters  (--format=text0), as a JSON array (--for-
+                   mat=json), or as an S-Expression list (--format=sexp).
 
                <b>tags</b>
 
 
                <b>tags</b>
 
-                   Output  all  tags  that  appear on any message matching the
-                   search terms, either one per line (--format=text) or  as  a
-                   JSON array (--format=json).
+                   Output all tags that appear on  any  message  matching  the
+                   search  terms,  either  one per line (--format=text), sepa-
+                   rated by null characters (--format=text0), as a JSON  array
+                   (--format=json),   or   as  an  S-Expression  list  (--for-
+                   mat=sexp).
 
            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
 
                This option can be used to present results in either chronolog-
 
            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
 
                This option can be used to present results in either chronolog-
-               ical  order  (<b>oldest-first</b>)  or  reverse  chronological   order
+               ical   order  (<b>oldest-first</b>)  or  reverse  chronological  order
                (<b>newest-first</b>).
 
                (<b>newest-first</b>).
 
-               Note:  The  thread  order  will  be  distinct between these two
-               options (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
+               Note: The thread order  will  be  distinct  between  these  two
+               options  (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.
 
                be sorted by the newest message in each thread.
 
-               By  default, results will be displayed in reverse chronological
+               By default, results will be displayed in reverse  chronological
                order, (that is, the newest results will be displayed first).
 
            <b>--offset=[-]N</b>
 
                order, (that is, the newest results will be displayed first).
 
            <b>--offset=[-]N</b>
 
-               Skip displaying the first N  results.  With  the  leading  &apos;-&apos;,
+               Skip  displaying  the  first  N  results. With the leading &apos;-&apos;,
                start at the Nth result from the end.
 
            <b>--limit=N</b>
                start at the Nth result from the end.
 
            <b>--limit=N</b>
 
            <b>--exclude=(true|false|flag)</b>
 
 
            <b>--exclude=(true|false|flag)</b>
 
-               Specify  whether  to  omit messages matching search.tag_exclude
-               from the search results (the default) or not. The extra  option
-               <b>flag</b>  only has an effect when <b>--output=summary</b> In this case all
+               Specify whether to omit  messages  matching  search.tag_exclude
+               from  the search results (the default) or not. The extra option
+               <b>flag</b> only has an effect when <b>--output=summary</b> In this case  all
                matching threads are returned but the &quot;match count&quot; is the num-
                ber of matching non-excluded messages in the thread.
 </pre>
 
                matching threads are returned but the &quot;match count&quot; is the num-
                ber of matching non-excluded messages in the thread.
 </pre>
 
+<h2>EXIT STATUS</h2>
+<pre>
+       This command supports the following special exit status codes
+
+       <b>20</b>     The requested format version is too old.
+
+       <b>21</b>     The requested format version is too new.
+</pre>
+
 <h2>SEE ALSO</h2>
 <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-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-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>
 
        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <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-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>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index f7d047c0cb1bd3b2c437b0860c4c3c3b5288a24b..595ef29b964542263e36deb0d18319860b8dce26 100644 (file)
@@ -50,6 +50,8 @@
 
             folder:&lt;directory-path&gt;
 
 
             folder:&lt;directory-path&gt;
 
+            date:&lt;since&gt;..&lt;until&gt;
+
        The  <b>from:</b> prefix is used to match the name or address of the sender of
        an email message.
 
        The  <b>from:</b> prefix is used to match the name or address of the sender of
        an email message.
 
        the  directory  components  below  the top-level mail database path are
        available to be searched.
 
        the  directory  components  below  the top-level mail database path are
        available to be searched.
 
-       In addition to individual terms, multiple terms can  be  combined  with
-       Boolean  operators  ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will
-       be implicitly connected by a logical AND if  no  explicit  operator  is
-       provided,  (except  that  terms with a common prefix will be implicitly
-       combined with OR until we get Xapian defect #402 fixed).
+       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) with a range
+       syntax of:
 
 
-       Parentheses can also be used to control the combination of the  Boolean
-       operators,  but  will  have  to be protected from interpretation by the
-       shell, (such as by putting quotation  marks  around  any  parenthesized
-       expression).
+            date:&lt;since&gt;..&lt;until&gt;
 
 
-       Finally, results can be restricted to only messages within a particular
-       time range, (based on the Date: header) with a syntax of:
+       See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expression, and
+       supported syntax for &lt;since&gt; and &lt;until&gt; date and time expressions.
+
+       The time range can also be specified using timestamps with a syntax of:
 
             &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
 
        Each timestamp is a number representing the  number  of  seconds  since
 
             &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
 
        Each timestamp is a number representing the  number  of  seconds  since
-       1970-01-01  00:00:00  UTC.  This  is  not  the most convenient means of
-       expressing date ranges, but until notmuch is fixed  to  accept  a  more
-       convenient  form, one can use the date program to construct timestamps.
-       For example, with the bash shell the following syntax would  specify  a
-       date range to return messages from 2009-10-01 until the current time:
+       1970-01-01 00:00:00 UTC.
+
+       In  addition  to  individual terms, multiple terms can be combined with
+       Boolean operators ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the  query  will
+       be  implicitly  connected  by  a logical AND if no explicit operator is
+       provided, (except that terms with a common prefix  will  be  implicitly
+       combined with OR until we get Xapian defect #402 fixed).
+
+       Parentheses  can also be used to control the combination of the Boolean
+       operators, but will have to be protected  from  interpretation  by  the
+       shell,  (such  as  by  putting quotation marks around any parenthesized
+       expression).
+</pre>
+
+<h2>DATE AND TIME SEARCH</h2>
+<pre>
+       notmuch understands a variety of standard and natural ways of  express-
+       ing dates and times, both in absolute terms (&quot;2012-10-24&quot;) and in rela-
+       tive terms (&quot;yesterday&quot;). Any number of relative terms can be  combined
+       (&quot;1  hour  25  minutes&quot;) 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.
+
+           <b>The</b> <b>range</b> <b>expression</b>
+
+               date:&lt;since&gt;..&lt;until&gt;
+
+               The  above  expression  restricts  the results to only messages
+               from &lt;since&gt; to &lt;until&gt;, based on the Date: header.
+
+               &lt;since&gt; and &lt;until&gt; can describe imprecise times, such as &quot;yes-
+               terday&quot;.   In  this case, &lt;since&gt; is taken as the earliest time
+               it could describe (the beginning of yesterday) and  &lt;until&gt;  is
+               taken  as the latest time it could describe (the end of yester-
+               day). Similarly, date:january..february matches from the begin-
+               ning of January to the end of February.
+
+               Currently,  we  do not support spaces in range expressions. You
+               can replace the spaces with &apos;_&apos;, or (in most cases) &apos;-&apos;, or (in
+               some  cases)  leave the spaces out altogether. Examples in this
+               man page use spaces for clarity.
+
+               Open-ended ranges are supported (since Xapian 1.2.1), i.e. it&apos;s
+               possible  to  specify  date:..&lt;until&gt;  or date:&lt;since&gt;.. to not
+               limit the start or end  time,  respectively.  Pre-1.2.1  Xapian
+               does  not report an error on open ended ranges, but it does not
+               work as expected either.
+
+               Entering date:expr without &quot;..&quot;  (for  example  date:yesterday)
+               won&apos;t  work,  as  it&apos;s not interpreted as a range expression at
+               all. You can achieve the expected  result  by  duplicating  the
+               expr  both  sides of &quot;..&quot;  (for example date:yesterday..yester-
+               day).
+
+           <b>Relative</b> <b>date</b> <b>and</b> <b>time</b>
+               [N|number] (years|months|weeks|days|hours|hrs|minutes|mins|sec-
+               onds|secs) [...]
+
+               All refer to past, can be repeated and will be accumulated.
+
+               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,  hun-
+               dred.  Additionally,  the  unit  may  be  preceded by &quot;last&quot; or
+               &quot;this&quot; (e.g., &quot;last week&quot; or &quot;this month&quot;).
+
+               When combined with absolute date and time,  the  relative  date
+               and  time  specification  will  be  relative from the specified
+               absolute date and time.
+
+               Examples: 5M2d, two weeks
+
+           <b>Supported</b> <b>absolute</b> <b>time</b> <b>formats</b>
+               H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
+
+               H[H] (am|a.m.|pm|p.m.)
+
+               HHMMSS
+
+               now
+
+               noon
+
+               midnight
+
+               Examples: 17:05, 5pm
+
+           <b>Supported</b> <b>absolute</b> <b>date</b> <b>formats</b>
+               YYYY-MM[-DD]
+
+               DD-MM[-[YY]YY]
+
+               MM-YYYY
+
+               M[M]/D[D][/[YY]YY]
+
+               M[M]/YYYY
+
+               D[D].M[M][.[YY]YY]
+
+               D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
+
+               Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
+
+               Wee[kday]
+
+               Month names can be abbreviated at three or more characters.
+
+               Weekday names can be abbreviated at three or more characters.
+
+               Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
+
+           <b>Time</b> <b>zones</b>
+               (+|-)HH:MM
+
+               (+|-)HH[MM]
 
 
-            $(date +%s -d 2009-10-01)..$(date +%s)
+               Some time zone codes, e.g. UTC, EET.
 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
 </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-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-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 </pre>
 
        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <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-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 </pre>
 
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 98d0d815a62c75b77aec0862db15048af0bd6fe9..3e9ad0687e64824292cc96aa453934358dd9a2aa 100644 (file)
        (server: irc.freenode.net, channel: #notmuch).
 </pre>
 
        (server: irc.freenode.net, channel: #notmuch).
 </pre>
 
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index 2cbeff95535cf07900253f96210a1f13fdf056c3..f5df8494cf8506752f05c3d7f666bc9814c5dac6 100644 (file)
 
                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
 
                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> this defaults to true.
-               For other formats, this defaults to false.
+               the matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this
+               defaults to true.  For other formats, this defaults to false.
 
 
-           <b>--format=(text|json|mbox|raw)</b>
+           <b>--format=(text|json|sexp|mbox|raw)</b>
 
                <b>text</b> (default for messages)
 
 
                <b>text</b> (default for messages)
 
                    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
                    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,   <b>--format=json</b>   sets
-                   <b>--entire-thread</b> The caller can disable  this  behaviour  by
-                   setting <b>--entire-thread=false</b>
+                   thread; that is, by default,
+
+                   <b>--format=json</b>  sets  <b>--entire-thread</b> The caller can disable
+                   this behaviour by setting <b>--entire-thread=false</b>
+
+               <b>sexp</b>
+
+                   The output is formatted as  an  S-Expression  (sexp).  This
+                   format  is  more  robust than the text format for automated
+                   processing. The nested structure of multipart MIME messages
+                   is  reflected in nested S-Expression output. By default, S-
+                   Expression output  includes  all  messages  in  a  matching
+                   thread; that is, by default,
+
+                   <b>--format=sexp</b>  sets  <b>--entire-thread</b> The caller can disable
+                   this behaviour by setting <b>--entire-thread=false</b>
 
                <b>mbox</b>
 
 
                <b>mbox</b>
 
-                   All  matching  messages are output in the traditional, Unix
-                   mbox format with each message  being  prefixed  by  a  line
-                   beginning  with  &quot;From  &quot;  and a blank line separating each
-                   message. Lines in the message content beginning with  &quot;From
-                   &quot;  (preceded  by  zero  or  more  &apos;&gt;&apos;  characters)  have an
-                   additional &apos;&gt;&apos; character added. This reversible escaping is
+                   All matching messages are output in the  traditional,  Unix
+                   mbox  format  with  each  message  being prefixed by a line
+                   beginning with &quot;From &quot; and a  blank  line  separating  each
+                   message.  Lines in the message content beginning with &quot;From
+                   &quot; (preceded by zero or more &apos;&gt;&apos; characters) have  an  addi-
+                   tional  &apos;&gt;&apos;  character  added.  This reversible escaping is
                    termed &quot;mboxrd&quot; format and described in detail here:
 
                    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
                <b>raw</b> (default for a single part, see --part)
 
                    termed &quot;mboxrd&quot; format and described in detail here:
 
                    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
                <b>raw</b> (default for a single part, see --part)
 
-                   For  a  message  or an attached message part, the original,
-                   raw content of the email message is  output.  Consumers  of
-                   this  format  should  expect to implement MIME decoding and
+                   For a message or an attached message  part,  the  original,
+                   raw  content  of  the email message is output. Consumers of
+                   this format should expect to implement  MIME  decoding  and
                    similar functions.
 
                    similar functions.
 
-                   For a single part (--part) the raw part content  is  output
-                   after  performing  any  necessary MIME decoding.  Note that
+                   For  a  single part (--part) the raw part content is output
+                   after performing any necessary MIME  decoding.   Note  that
                    messages with a simple body still have two parts: part 0 is
                    the whole message and part 1 is the body.
 
                    messages with a simple body still have two parts: part 0 is
                    the whole message and part 1 is the body.
 
-                   For  a multipart part, the part headers and body (including
+                   For a multipart part, the part headers and body  (including
                    all child parts) is output.
 
                    The raw format must only be used with search terms matching
                    single message.
 
                    all child parts) is output.
 
                    The raw format must only be used with search terms matching
                    single message.
 
+           <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.
+
            <b>--part=N</b>
 
                Output the single decoded MIME part N of a single message.  The
            <b>--part=N</b>
 
                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 struc-
-               ture, and are identified in the &apos;json&apos; or  &apos;text&apos;  output  for-
-               mats.
+               search  terms  must match only a single message.  Message parts
+               are numbered in a depth-first walk of the message  MIME  struc-
+               ture, and are identified in the &apos;json&apos;, &apos;sexp&apos; or &apos;text&apos; output
+               formats.
 
            <b>--verify</b>
 
 
            <b>--verify</b>
 
-               Compute  and report the validity of any MIME cryptographic sig-
-               natures found in the selected content  (ie.  &quot;multipart/signed&quot;
+               Compute and report the validity of any MIME cryptographic  sig-
+               natures  found  in the selected content (ie. &quot;multipart/signed&quot;
                parts). Status of the signature will be reported (currently on-
                parts). Status of the signature will be reported (currently on-
-               ly supported with --format=json), and the multipart/signed part
-               will be replaced by the signed data.
+               ly  supported  with  --format=json  and --format=sexp), and the
+               multipart/signed part will be replaced by the signed data.
 
            <b>--decrypt</b>
 
 
            <b>--decrypt</b>
 
-               Decrypt  any MIME encrypted parts found in the selected content
-               (ie. &quot;multipart/encrypted&quot; parts).  Status  of  the  decryption
-               will  be reported (currently only supported with --format=json)
-               and the multipart/encrypted part will be replaced  by  the  de-
-               crypted content.  Implies --verify.
+               Decrypt any MIME encrypted parts found in the selected  content
+               (ie.  &quot;multipart/encrypted&quot;  parts).  Status  of the decryption
+               will be reported (currently only supported  with  --format=json
+               and --format=sexp) and the multipart/encrypted part will be re-
+               placed by the decrypted content.  Implies --verify.
 
            <b>--exclude=(true|false)</b>
 
 
            <b>--exclude=(true|false)</b>
 
-               Specify  whether  to  omit threads only matching search.tag_ex-
-               clude 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
+               Specify whether to omit threads  only  matching  search.tag_ex-
+               clude  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).
 
                flag).
 
-               If  --entire-thread  is specified then complete threads are re-
+               If --entire-thread is specified then complete threads  are  re-
                turned regardless (with the excluded flag being set when appro-
                turned regardless (with the excluded flag being set when appro-
-               priate)  but threads that only match in an excluded message are
+               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>
 
            <b>--body=(true|false)</b>
 
                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 format and it  is
-               incompatible with <b>--part</b> &gt<b>&</b>gt; <b>0.</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
+               and it is incompatible with <b>--part</b> &gt<b>&</b>gt; <b>0.</b>
 
 
-               This  is  useful  if the caller only needs the headers as body-
+               This is useful if the caller only needs the  headers  as  body-
                less output is much faster and substantially smaller.
 
                less output is much faster and substantially smaller.
 
-       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 &quot;thread:&lt;thread-id&gt;&quot; as can be
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
 
        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
 
+<h2>EXIT STATUS</h2>
+<pre>
+       This command supports the following special exit status codes
+
+       <b>20</b>     The requested format version is too old.
+
+       <b>21</b>     The requested format version is too new.
+</pre>
+
 <h2>SEE ALSO</h2>
 <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-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/'>notmuch-tag</a>(1)
 </pre>
 
        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <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/'>notmuch-tag</a>(1)
 </pre>
 
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
index eee032527ed505791cfd20767f6ba46e69556cd1..1f0b8ca41dd175e365419e43c8b2621bcaea369e 100644 (file)
@@ -8,7 +8,9 @@
 
 <h2>SYNOPSIS</h2>
 <pre>
 
 <h2>SYNOPSIS</h2>
 <pre>
-       <b>notmuch</b> <b>tag</b> +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>search-term</u>&gt;...
+       <b>notmuch</b> <b>tag</b> +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>search-term</u>&gt; [...]
+
+       <b>notmuch</b> <b>tag</b> --batch [ --input=&lt;<u>filename</u>&gt; ]
 </pre>
 
 <h2>DESCRIPTION</h2>
 </pre>
 
 <h2>DESCRIPTION</h2>
        Add/remove tags for all messages matching the search terms.
 
        See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
        Add/remove tags for all messages matching the search terms.
 
        See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
-       &lt;search-terms&gt;.
+       &lt;<u>search-term</u>&gt;.
 
        Tags prefixed by &apos;+&apos; are added while those prefixed by &apos;-&apos; are removed.
 
        Tags prefixed by &apos;+&apos; are added while those prefixed by &apos;-&apos; are removed.
-       For each message, tag removal is performed before tag addition.
+       For each message, tag changes are applied in the order they  appear  on
+       the command line.
 
 
-       The beginning of &lt;search-terms&gt; is recognized  by  the  first  argument
-       that  begins  with  neither  &apos;+&apos; nor &apos;-&apos;. Support for an initial search
-       term beginning with &apos;+&apos; or &apos;-&apos; is provided  by  allowing  the  user  to
+       The  beginning  of the search terms is recognized by the first argument
+       that begins with neither &apos;+&apos; nor &apos;-&apos;. Support  for  an  initial  search
+       term  beginning  with  &apos;+&apos;  or  &apos;-&apos; is provided by allowing the user to
        specify a &quot;--&quot; argument to separate the tags from the search terms.
 
        specify a &quot;--&quot; argument to separate the tags from the search terms.
 
-       <b>notmuch</b>  <b>tag</b>  updates the maildir flags according to tag changes if the
+       <b>notmuch</b> <b>tag</b> updates the maildir flags according to tag changes  if  the
        <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>notmuch-</a>
        <a href='../notmuch-config-1/'>config</a>(1) for details.
        <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>notmuch-</a>
        <a href='../notmuch-config-1/'>config</a>(1) for details.
+
+       Supported options for <b>tag</b> include
+
+           <b>--batch</b>
+
+               Read batch tagging operations from a file (stdin  by  default).
+               This  is  more efficient than repeated <b>notmuch</b> <b>tag</b> invocations.
+               See <b>TAG</b> <b>FILE</b> <b>FORMAT</b> below for the input format. This option  is
+               not compatible with specifying tagging on the command line.
+
+           <b>--input=</b>&lt;filename&gt;
+
+               Read  input  from  given  file,  instead of from stdin. Implies
+               <b>--batch</b>.
+</pre>
+
+<h2>TAG FILE FORMAT</h2>
+<pre>
+       The input must consist of lines of the format:
+
+       +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>query</u>&gt;
+
+       Each line is interpreted similarly to <b>notmuch</b> <b>tag</b>  command  line  argu-
+       ments. The delimiter is one or more spaces &apos; &apos;. Any characters in &lt;<u>tag</u>&gt;
+       <b>may</b> be hex-encoded with %NN where NN is the hexadecimal  value  of  the
+       character.  To hex-encode a character with a multi-byte UTF-8 encoding,
+       hex-encode each byte.  Any spaces in &lt;tag&gt; <b>must</b> be hex-encoded as  %20.
+       Any characters that are not part of &lt;<u>tag</u>&gt; <b>must</b> <b>not</b> be hex-encoded.
+
+       In  the future tag:&quot;tag with spaces&quot; style quoting may be supported for
+       &lt;<u>tag</u>&gt; as well; for this reason all double  quote  characters  in  &lt;<u>tag</u>&gt;
+       <b>should</b> be hex-encoded.
+
+       The  &lt;<u>query</u>&gt;  should be quoted using Xapian boolean term quoting rules:
+       if a term contains whitespace or a close paren or starts with a  double
+       quote,  it must be enclosed in double quotes (not including any prefix)
+       and double quotes inside the term must be doubled (see below for  exam-
+       ples).
+
+       Leading and trailing space &apos; &apos; is ignored. Empty lines and lines begin-
+       ning with &apos;#&apos; are ignored.
+</pre>
+
+<h3> &nbsp; EXAMPLE</h3>
+<pre>
+       The following shows a valid input to batch tagging. Note that only  the
+       isolated  &apos;*&apos;  acts as a wildcard. Also note the two different quotings
+       of the tag <b>space</b> <b>in</b> <b>tags</b>
+              +winner *
+              +foo::bar%25 -- (One and Two) or (One and tag:winner)
+              +found::it -- tag:foo::bar%
+              # ignore this line and the next
+
+              +space%20in%20tags -- Two
+              # add tag &apos;(tags)&apos;, among other stunts.
+              +crazy{ +(tags) +&amp;are +#possible -- tag:&quot;space in tags&quot;
+              +match*crazy -- tag:crazy{
+              +some_tag -- id:&quot;this is &quot;&quot;nauty)&quot;&quot;&quot;
 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
 </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-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/'>notmuch-show</a>(1),
 </pre>
 
        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <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/'>notmuch-show</a>(1),
 </pre>
 
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>