From 0b22ed1b4e640539ae8e6f78f1ea88e54426a50d Mon Sep 17 00:00:00 2001 From: Tomi Ollila Date: Sat, 19 Jan 2013 19:15:09 +0200 Subject: [PATCH] manpages 0.15 --- manpages.mdwn | 2 - manpages/notmuch-1.mdwn | 2 +- manpages/notmuch-config-1.mdwn | 2 +- manpages/notmuch-count-1.mdwn | 2 +- manpages/notmuch-dump-1.mdwn | 61 +++++++++-- manpages/notmuch-hooks-5.mdwn | 2 +- manpages/notmuch-new-1.mdwn | 2 +- manpages/notmuch-reply-1.mdwn | 65 ++++++++---- manpages/notmuch-restore-1.mdwn | 55 +++++++--- manpages/notmuch-search-1.mdwn | 80 +++++++++----- manpages/notmuch-search-terms-7.mdwn | 149 +++++++++++++++++++++++---- manpages/notmuch-setup-1.mdwn | 2 +- manpages/notmuch-show-1.mdwn | 118 +++++++++++++-------- manpages/notmuch-tag-1.mdwn | 79 ++++++++++++-- 14 files changed, 463 insertions(+), 158 deletions(-) diff --git a/manpages.mdwn b/manpages.mdwn index 1953ff6..6bb01fa 100644 --- a/manpages.mdwn +++ b/manpages.mdwn @@ -14,5 +14,3 @@ Manual page index * notmuch-tag(1) - add/remove tags for all messages matching the search terms * notmuch-hooks(5) - hooks for notmuch * notmuch-search-terms(7) - syntax for notmuch queries - -

Notmuch 0.14

diff --git a/manpages/notmuch-1.mdwn b/manpages/notmuch-1.mdwn index 98d0d81..3e9ad06 100644 --- a/manpages/notmuch-1.mdwn +++ b/manpages/notmuch-1.mdwn @@ -119,4 +119,4 @@ (server: irc.freenode.net, channel: #notmuch). -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn index e54a4f0..b9850cf 100644 --- a/manpages/notmuch-config-1.mdwn +++ b/manpages/notmuch-config-1.mdwn @@ -117,4 +117,4 @@ notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1) -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-count-1.mdwn b/manpages/notmuch-count-1.mdwn index b917808..9d9767f 100644 --- a/manpages/notmuch-count-1.mdwn +++ b/manpages/notmuch-count-1.mdwn @@ -48,4 +48,4 @@ notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1) -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-dump-1.mdwn b/manpages/notmuch-dump-1.mdwn index 92424b6..743be97 100644 --- a/manpages/notmuch-dump-1.mdwn +++ b/manpages/notmuch-dump-1.mdwn @@ -7,7 +7,8 @@

SYNOPSIS

-       notmuch dump [ --output=<filename> ] [--] [ <search-term>...]
+       notmuch  dump  [--format=(sup|batch-tag)]  [--] [ --output=<filename> ]
+       [--] [ <search-term>...]

DESCRIPTION

@@ -16,24 +17,62 @@ 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. + --format=(sup|batch-tag) - See notmuch-search-terms(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. + + sup The sup 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 notmuch + restore command provides you a way to import all of your tags + (or labels as sup calls them). Each line has the following + form + + <message-id> ( <tag> ... ) + + 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. + + batch-tag + + The batch-tag dump format is intended to more robust against + malformed message-ids and tags containing whitespace or non- + ascii(7) characters. Each line has the form + + +<encoded-tag> +<encoded-tag> ... -- id:<quoted-message-id> + + Tags are hex-encoded by replacing every byte not matching the + regex [A-Za-z0-9@=.,_+-] with %nn 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 notmuch-tag(1); note that + the single message-id query is mandatory for notmuch- + restore(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 notmuch-search-terms(7) for details of the supported syntax for + <search-terms>.

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-hooks-5.mdwn b/manpages/notmuch-hooks-5.mdwn index 207c29f..a813dfd 100644 --- a/manpages/notmuch-hooks-5.mdwn +++ b/manpages/notmuch-hooks-5.mdwn @@ -45,4 +45,4 @@ notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1) -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-new-1.mdwn b/manpages/notmuch-new-1.mdwn index 6977e21..fee5cea 100644 --- a/manpages/notmuch-new-1.mdwn +++ b/manpages/notmuch-new-1.mdwn @@ -50,4 +50,4 @@ notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1) -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-reply-1.mdwn b/manpages/notmuch-reply-1.mdwn index 9fe2795..0d9f8c2 100644 --- a/manpages/notmuch-reply-1.mdwn +++ b/manpages/notmuch-reply-1.mdwn @@ -34,7 +34,7 @@ Supported options for reply include - --format=(default|json|headers-only) + --format=(default|json|sexp|headers-only) default Includes subject and quoted message body. @@ -45,48 +45,69 @@ put can be used by a client to create a reply message intelligently. + sexp + 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. + headers-only - Only produces In-Reply-To, References, To, Cc, and Bcc + Only produces In-Reply-To, References, To, Cc, and Bcc headers. + --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke notmuch(1) internally. If + omitted, the latest supported version will be used. + --reply-to=(all|sender) all (default) Replies to all addresses. sender - 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. --decrypt - 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 notmuch-search-terms(7) for details of the supported syntax for + See notmuch-search-terms(7) for details of the supported syntax for <search-terms>. - Note: It is most common to use notmuch reply with a search string - matching a single message, (such as id:<message-id>), but it can be + Note: It is most common to use notmuch reply 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. + + +

EXIT STATUS

+
+       This command supports the following special exit status codes
+
+       20     The requested format version is too old.
+
+       21     The requested format version is too new.

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-restore-1.mdwn b/manpages/notmuch-restore-1.mdwn index 555ae6a..87869c9 100644 --- a/manpages/notmuch-restore-1.mdwn +++ b/manpages/notmuch-restore-1.mdwn @@ -8,7 +8,8 @@

SYNOPSIS

-       notmuch restore [--accumulate] [ --input=<filename> ]
+       notmuch  restore   [--accumulate]   [--format=(auto|batch-tag|sup)]   [
+       --input=<filename> ]

DESCRIPTION

@@ -17,28 +18,50 @@ 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 notmuch restore command provides you a way - to import all of your tags (or labels as sup calls them). + Supported options for restore 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. + --accumulate - See notmuch-search-terms(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. - notmuch restore updates the maildir flags according to tag changes if - the maildir.synchronize_flags configuration option is enabled. See not- - much-config(1) for details. + --format=(sup|batch-tag|auto) + + 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 notmuch-dump(1). + + sup The sup 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 not- + much restore command provides you a way to import all of + your tags (or labels as sup calls them). + + batch-tag + + The batch-tag dump format is intended to more robust + against malformed message-ids and tags containing whites- + pace or non-ascii(7) characters. See notmuch-dump(1) for + details on this format. + + notmuch restore updates the maildir flags according to tag + changes if the maildir.synchronize_flags configuration + option is enabled. See notmuch-config(1) for details. + + auto + + 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.

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn index b042815..5afb0f7 100644 --- a/manpages/notmuch-search-1.mdwn +++ b/manpages/notmuch-search-1.mdwn @@ -26,62 +26,77 @@ Supported options for search include - --format=(json|text) + --format=(json|sexp|text|text0) - 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 xargs(1) -0 option where + available). + + --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke notmuch(1) internally. If + omitted, the latest supported version will be used. --output=(summary|threads|messages|files|tags) summary - 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. threads - 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). messages - 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). files 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). tags - 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). --sort=(newest-first|oldest-first) This option can be used to present results in either chronolog- - ical order (oldest-first) or reverse chronological order + ical order (oldest-first) or reverse chronological order (newest-first). - Note: The thread order will be distinct between these two - options (beyond being simply reversed). When sorting by old- - est-first the threads will be sorted by the oldest message in - each thread, but when sorting by newest-first the threads will + Note: The thread order will be distinct between these two + options (beyond being simply reversed). When sorting by old- + est-first the threads will be sorted by the oldest message in + each thread, but when sorting by newest-first 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). --offset=[-]N - 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. --limit=N @@ -90,18 +105,27 @@ --exclude=(true|false|flag) - Specify whether to omit messages matching search.tag_exclude - from the search results (the default) or not. The extra option - flag only has an effect when --output=summary In this case all + Specify whether to omit messages matching search.tag_exclude + from the search results (the default) or not. The extra option + flag only has an effect when --output=summary In this case all matching threads are returned but the "match count" is the num- ber of matching non-excluded messages in the thread. +

EXIT STATUS

+
+       This command supports the following special exit status codes
+
+       20     The requested format version is too old.
+
+       21     The requested format version is too new.
+
+

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn index f7d047c..595ef29 100644 --- a/manpages/notmuch-search-terms-7.mdwn +++ b/manpages/notmuch-search-terms-7.mdwn @@ -50,6 +50,8 @@ folder:<directory-path> + date:<since>..<until> + The from: prefix is used to match the name or address of the sender of an email message. @@ -81,37 +83,146 @@ 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 ( and, or, not , 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 date: 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 DATE AND TIME SEARCH 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 ( and, or, not , 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). + + +

DATE AND TIME SEARCH

+
+       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.
+
+           The range expression
+
+               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).
+
+           Relative date and time
+               [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
+
+           Supported absolute time formats
+               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
+
+           Supported absolute date formats
+               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
+
+           Time zones
+               (+|-)HH:MM
+
+               (+|-)HH[MM]
 
-            $(date +%s -d 2009-10-01)..$(date +%s)
+               Some time zone codes, e.g. UTC, EET.

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-setup-1.mdwn b/manpages/notmuch-setup-1.mdwn index 98d0d81..3e9ad06 100644 --- a/manpages/notmuch-setup-1.mdwn +++ b/manpages/notmuch-setup-1.mdwn @@ -119,4 +119,4 @@ (server: irc.freenode.net, channel: #notmuch). -

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn index 2cbeff9..f5df849 100644 --- a/manpages/notmuch-show-1.mdwn +++ b/manpages/notmuch-show-1.mdwn @@ -29,10 +29,10 @@ If true, notmuch show outputs all messages in the thread of any message matching the search terms; if false, it outputs only - the matching messages. For --format=json this defaults to true. - For other formats, this defaults to false. + the matching messages. For --format=json and --format=sexp this + defaults to true. For other formats, this defaults to false. - --format=(text|json|mbox|raw) + --format=(text|json|sexp|mbox|raw) text (default for messages) @@ -52,99 +52,127 @@ 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, --format=json sets - --entire-thread The caller can disable this behaviour by - setting --entire-thread=false + thread; that is, by default, + + --format=json sets --entire-thread The caller can disable + this behaviour by setting --entire-thread=false + + sexp + + 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, + + --format=sexp sets --entire-thread The caller can disable + this behaviour by setting --entire-thread=false mbox - 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 raw (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. + --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke notmuch(1) internally. If + omitted, the latest supported version will be used. + --part=N 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. --verify - 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. --decrypt - 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. --exclude=(true|false) - 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 --exclude=true. The default is --exclude=true. --body=(true|false) - If true (the default) notmuch show includes the bodies of the - messages in the output; if false, bodies are omitted. - --body=false is only implemented for the json format and it is - incompatible with --part >&gt; 0. + If true (the default) notmuch show includes the bodies of the + messages in the output; if false, bodies are omitted. + --body=false is only implemented for the json and sexp formats + and it is incompatible with --part >&gt; 0. - 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 notmuch show is to display a single thread of email + A common use of notmuch show is to display a single thread of email messages. For this, use a search term of "thread:<thread-id>" as can be seen in the first column of output from the notmuch search command. +

EXIT STATUS

+
+       This command supports the following special exit status codes
+
+       20     The requested format version is too old.
+
+       21     The requested format version is too new.
+
+

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

diff --git a/manpages/notmuch-tag-1.mdwn b/manpages/notmuch-tag-1.mdwn index eee0325..1f0b8ca 100644 --- a/manpages/notmuch-tag-1.mdwn +++ b/manpages/notmuch-tag-1.mdwn @@ -8,7 +8,9 @@

SYNOPSIS

-       notmuch tag +<tag>|-<tag> [...] [--] <search-term>...
+       notmuch tag +<tag>|-<tag> [...] [--] <search-term> [...]
+
+       notmuch tag --batch [ --input=<filename> ]

DESCRIPTION

@@ -16,26 +18,85 @@ Add/remove tags for all messages matching the search terms. See notmuch-search-terms(7) for details of the supported syntax for - <search-terms>. + <search-term>. 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. - notmuch tag updates the maildir flags according to tag changes if the + notmuch tag updates the maildir flags according to tag changes if the maildir.synchronize_flags configuration option is enabled. See notmuch- config(1) for details. + + Supported options for tag include + + --batch + + Read batch tagging operations from a file (stdin by default). + This is more efficient than repeated notmuch tag invocations. + See TAG FILE FORMAT below for the input format. This option is + not compatible with specifying tagging on the command line. + + --input=<filename> + + Read input from given file, instead of from stdin. Implies + --batch. + + +

TAG FILE FORMAT

+
+       The input must consist of lines of the format:
+
+       +<tag>|-<tag> [...] [--] <query>
+
+       Each line is interpreted similarly to notmuch tag  command  line  argu-
+       ments. The delimiter is one or more spaces ' '. Any characters in <tag>
+       may 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> must be hex-encoded as  %20.
+       Any characters that are not part of <tag> must not be hex-encoded.
+
+       In  the future tag:"tag with spaces" style quoting may be supported for
+       <tag> as well; for this reason all double  quote  characters  in  <tag>
+       should be hex-encoded.
+
+       The  <query>  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.
+
+ +

  EXAMPLE

+
+       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 space in tags
+              +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)"""

SEE ALSO

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

Notmuch 0.14

+

Notmuch 0.15

-- 2.43.0