* <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>
(server: irc.freenode.net, channel: #notmuch).
</pre>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
<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>
<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>
<h2>SYNOPSIS</h2>
<pre>
- <b>notmuch</b> <b>dump</b> [ --output=<<u>filename</u>> ] [--] [ <<u>search-term</u>>...]
+ <b>notmuch</b> <b>dump</b> [<b>--format=(sup|batch-tag)</b>] [--] [ --output=<<u>filename</u>> ]
+ [--] [ <<u>search-term</u>>...]
</pre>
<h2>DESCRIPTION</h2>
Output is to the given filename, if any, or to stdout.
- These tags are the only data in the notmuch database that can'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'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.)
- With no search terms, a dump of all messages in the database will be
- generated. A "--" 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
- <search-terms>.
+ 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'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
+
+ <<u>message-id</u>> <b>(</b> <<u>tag</u>> ... <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
+
+ +<<u>encoded-tag</u>> +<<u>encoded-tag</u>> ... -- id:<<u>quoted-message-id</u>>
+
+ 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 "--" 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
+ <search-terms>.
</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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
<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>
<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>
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.
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>
- Only produces In-Reply-To, References, To, Cc, and Bcc
+ Only produces In-Reply-To, References, To, Cc, and Bcc
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>
- Replies only to the sender. If replying to user's own
- message (Reply-to: or From: header is one of the user's
- configured email addresses), try To:, Cc:, and Bcc:
- headers in this order, and copy values from the first
- that contains something other than only the user's
+ Replies only to the sender. If replying to user's own
+ message (Reply-to: or From: header is one of the user's
+ configured email addresses), try To:, Cc:, and Bcc:
+ headers in this order, and copy values from the first
+ that contains something other than only the user's
addresses.
<b>--decrypt</b>
- Decrypt any MIME encrypted parts found in the selected
- content (ie. "multipart/encrypted" 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. "multipart/encrypted" 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
<search-terms>.
- Note: It is most common to use <b>notmuch</b> <b>reply</b> with a search string
- matching a single message, (such as id:<message-id>), 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:<message-id>), but it can be
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>
- <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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
<h2>SYNOPSIS</h2>
<pre>
- <b>notmuch</b> <b>restore</b> [<b>--accumulate</b>] [ --input=<<u>filename</u>> ]
+ <b>notmuch</b> <b>restore</b> [<b>--accumulate</b>] [<b>--format=(auto|batch-tag|sup)</b>] [
+ --input=<<u>filename</u>> ]
</pre>
<h2>DESCRIPTION</h2>
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'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'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
- <search-terms>.
+ The union of the existing and new tags is applied, instead of
+ replacing each message's tags as they are read in from the dump
+ file.
- <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'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>
- <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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
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>
- 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 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>
- 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>
- 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
- 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>
- 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-
- ical order (<b>oldest-first</b>) or reverse chronological order
+ ical order (<b>oldest-first</b>) or reverse chronological order
(<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.
- 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>
- Skip displaying the first N results. With the leading '-',
+ Skip displaying the first N results. With the leading '-',
start at the Nth result from the end.
<b>--limit=N</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 "match count" 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>
- <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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
folder:<directory-path>
+ date:<since>..<until>
+
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.
- 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:<since>..<until>
- 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 <since> and <until> date and time expressions.
+
+ The time range can also be specified using timestamps with 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. 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 ("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
+ the syntax supported for absolute and relative terms is given below.
+
+ <b>The</b> <b>range</b> <b>expression</b>
+
+ date:<since>..<until>
+
+ 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 "yes-
+ terday". 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 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 '_', or (in most cases) '-', 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's
+ possible to specify date:..<until> or date:<since>.. 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 ".." (for example date:yesterday)
+ won't work, as it's not interpreted as a range expression at
+ all. You can achieve the expected result by duplicating the
+ expr both sides of ".." (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 "last" or
+ "this" (e.g., "last week" or "this month").
+
+ 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>
- <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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
(server: irc.freenode.net, channel: #notmuch).
</pre>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
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)
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>
- All matching messages are output in the traditional, Unix
- mbox format with each message being prefixed by a line
- beginning with "From " and a blank line separating each
- message. Lines in the message content beginning with "From
- " (preceded by zero or more '>' characters) have an
- additional '>' character added. This reversible escaping is
+ All matching messages are output in the traditional, Unix
+ mbox format with each message being prefixed by a line
+ beginning with "From " and a blank line separating each
+ message. Lines in the message content beginning with "From
+ " (preceded by zero or more '>' characters) have an addi-
+ tional '>' character added. This reversible escaping is
termed "mboxrd" format and described in detail here:
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
<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.
- 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.
- 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.
+ <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
- 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 'json' or 'text' 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 'json', 'sexp' or 'text' output
+ formats.
<b>--verify</b>
- Compute and report the validity of any MIME cryptographic sig-
- natures found in the selected content (ie. "multipart/signed"
+ Compute and report the validity of any MIME cryptographic sig-
+ natures found in the selected content (ie. "multipart/signed"
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>
- Decrypt any MIME encrypted parts found in the selected content
- (ie. "multipart/encrypted" 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. "multipart/encrypted" 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>
- 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).
- 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-
- 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>
- 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> ><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> ><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.
- 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>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>
- <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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
<h2>SYNOPSIS</h2>
<pre>
- <b>notmuch</b> <b>tag</b> +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>search-term</u>>...
+ <b>notmuch</b> <b>tag</b> +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>search-term</u>> [...]
+
+ <b>notmuch</b> <b>tag</b> --batch [ --input=<<u>filename</u>> ]
</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
- <search-terms>.
+ <<u>search-term</u>>.
Tags prefixed by '+' are added while those prefixed by '-' 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 <search-terms> is recognized by the first argument
- that begins with neither '+' nor '-'. Support for an initial search
- term beginning with '+' or '-' is provided by allowing the user to
+ The beginning of the search terms is recognized by the first argument
+ that begins with neither '+' nor '-'. Support for an initial search
+ term beginning with '+' or '-' is provided by allowing the user to
specify a "--" 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.
+
+ 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><filename>
+
+ 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:
+
+ +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>query</u>>
+
+ Each line is interpreted similarly to <b>notmuch</b> <b>tag</b> command line argu-
+ ments. The delimiter is one or more spaces ' '. Any characters in <<u>tag</u>>
+ <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 <tag> <b>must</b> be hex-encoded as %20.
+ Any characters that are not part of <<u>tag</u>> <b>must</b> <b>not</b> be hex-encoded.
+
+ In the future tag:"tag with spaces" style quoting may be supported for
+ <<u>tag</u>> as well; for this reason all double quote characters in <<u>tag</u>>
+ <b>should</b> be hex-encoded.
+
+ The <<u>query</u>> 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 ' ' is ignored. Empty lines and lines begin-
+ ning with '#' are ignored.
+</pre>
+
+<h3> EXAMPLE</h3>
+<pre>
+ The following shows a valid input to batch tagging. Note that only the
+ isolated '*' 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 '(tags)', among other stunts.
+ +crazy{ +(tags) +&are +#possible -- tag:"space in tags"
+ +match*crazy -- tag:crazy{
+ +some_tag -- id:"this is ""nauty)"""
</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>
-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.15</h2>
projects / obsolete / notmuch-wiki / commitdiff