1 Return-Path: <bremner@tethera.net>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id F0B26431FC2
\r
6 for <notmuch@notmuchmail.org>; Sat, 8 Dec 2012 14:57:57 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id Q2rIM14wg02q for <notmuch@notmuchmail.org>;
\r
16 Sat, 8 Dec 2012 14:57:56 -0800 (PST)
\r
17 Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238])
\r
18 (using TLSv1 with cipher AES256-SHA (256/256 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id 751FC429E4A
\r
21 for <notmuch@notmuchmail.org>; Sat, 8 Dec 2012 14:57:43 -0800 (PST)
\r
22 Received: from fctnnbsc30w-142167090129.dhcp-dynamic.fibreop.nb.bellaliant.net
\r
23 ([142.167.90.129] helo=zancas.localnet)
\r
24 by tesseract.cs.unb.ca with esmtpsa
\r
25 (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72)
\r
26 (envelope-from <bremner@tethera.net>)
\r
27 id 1ThTL4-00066m-Hi; Sat, 08 Dec 2012 18:57:42 -0400
\r
28 Received: from bremner by zancas.localnet with local (Exim 4.80)
\r
29 (envelope-from <bremner@tethera.net>)
\r
30 id 1ThTKz-0000r6-1M; Sat, 08 Dec 2012 18:57:37 -0400
\r
31 From: david@tethera.net
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [Patch v5 10/11] notmuch-{dump,
\r
34 restore}.1: document new format options
\r
35 Date: Sat, 8 Dec 2012 18:57:00 -0400
\r
36 Message-Id: <1355007421-3069-11-git-send-email-david@tethera.net>
\r
37 X-Mailer: git-send-email 1.7.10.4
\r
38 In-Reply-To: <1355007421-3069-1-git-send-email-david@tethera.net>
\r
39 References: <1355007421-3069-1-git-send-email-david@tethera.net>
\r
41 Cc: David Bremner <bremner@debian.org>
\r
42 X-BeenThere: notmuch@notmuchmail.org
\r
43 X-Mailman-Version: 2.1.13
\r
45 List-Id: "Use and development of the notmuch mail system."
\r
46 <notmuch.notmuchmail.org>
\r
47 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
48 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
49 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
50 List-Post: <mailto:notmuch@notmuchmail.org>
\r
51 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
52 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
53 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
54 X-List-Received-Date: Sat, 08 Dec 2012 22:57:58 -0000
\r
56 From: David Bremner <bremner@debian.org>
\r
58 More or less arbitrarily, notmuch-dump.1 gets the more detailed
\r
59 description of the format.
\r
61 man/man1/notmuch-dump.1 | 59 ++++++++++++++++++++++++++++++++++++++++++++
\r
62 man/man1/notmuch-restore.1 | 59 +++++++++++++++++++++++++++++++++++++++-----
\r
63 2 files changed, 112 insertions(+), 6 deletions(-)
\r
65 diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1
\r
66 index 230deec..770b00f 100644
\r
67 --- a/man/man1/notmuch-dump.1
\r
68 +++ b/man/man1/notmuch-dump.1
\r
69 @@ -5,6 +5,7 @@ notmuch-dump \- creates a plain-text dump of the tags of each message
\r
73 +.RB [ "\-\-format=(sup|batch-tag)" "] [--]"
\r
74 .RI "[ --output=<" filename "> ] [--]"
\r
75 .RI "[ <" search-term ">...]"
\r
77 @@ -19,6 +20,64 @@ recreated from the messages themselves. The output of notmuch dump is
\r
78 therefore the only critical thing to backup (and much more friendly to
\r
79 incremental backup than the native database files.)
\r
82 +.B \-\-format=(sup|batch-tag)
\r
84 +Notmuch restore supports two plain text dump formats, both with one message-id
\r
85 +per line, followed by a list of tags.
\r
93 +dump file format is specifically chosen to be
\r
94 +compatible with the format of files produced by sup-dump.
\r
95 +So if you've previously been using sup for mail, then the
\r
96 +.B "notmuch restore"
\r
97 +command provides you a way to import all of your tags (or labels as
\r
99 +Each line has the following form
\r
102 +.RI < message-id >
\r
107 +with zero or more tags are separated by spaces. Note that (malformed)
\r
108 +message-ids may contain arbitrary non-null characters. Note also
\r
109 +that tags with spaces will not be correctly restored with this format.
\r
120 +dump format is intended to more robust against malformed message-ids
\r
121 +and tags containing whitespace or non-\fBascii\fR(7) characters.
\r
122 +Each line has the form
\r
125 +.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" encoded-message-id >
\r
127 +where encoded means that every byte not matching the regex
\r
128 +.B [A-Za-z0-9@=.,_+-]
\r
131 +where nn is the two digit hex encoding.
\r
132 +The astute reader will notice this is a special case of the batch input
\r
133 +format for \fBnotmuch-tag\fR(1); note that the single message-id query is
\r
134 +mandatory for \fBnotmuch-restore\fR(1).
\r
139 With no search terms, a dump of all messages in the database will be
\r
140 generated. A "--" argument instructs notmuch that the
\r
141 remaining arguments are search terms.
\r
142 diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1
\r
143 index 2fa8733..6bba628 100644
\r
144 --- a/man/man1/notmuch-restore.1
\r
145 +++ b/man/man1/notmuch-restore.1
\r
146 @@ -6,6 +6,7 @@ notmuch-restore \- restores the tags from the given file (see notmuch dump)
\r
148 .B "notmuch restore"
\r
149 .RB [ "--accumulate" ]
\r
150 +.RB [ "--format=(auto|batch-tag|sup)" ]
\r
151 .RI "[ --input=<" filename "> ]"
\r
154 @@ -15,19 +16,51 @@ Restores the tags from the given file (see
\r
156 The input is read from the given filename, if any, or from stdin.
\r
158 -Note: The dump file format is specifically chosen to be
\r
160 +Supported options for
\r
167 +The union of the existing and new tags is applied, instead of
\r
168 +replacing each message's tags as they are read in from the dump file.
\r
173 +.B \-\-format=(sup|batch-tag|auto)
\r
175 +Notmuch restore supports two plain text dump formats, with each line
\r
176 +specifying a message-id and a set of tags.
\r
177 +For details of the actual formats, see \fBnotmuch-dump\fR(1).
\r
185 +dump file format is specifically chosen to be
\r
186 compatible with the format of files produced by sup-dump.
\r
187 So if you've previously been using sup for mail, then the
\r
188 .B "notmuch restore"
\r
189 command provides you a way to import all of your tags (or labels as
\r
192 -The --accumulate switch causes the union of the existing and new tags to be
\r
193 -applied, instead of replacing each message's tags as they are read in from the
\r
200 -See \fBnotmuch-search-terms\fR(7)
\r
201 -for details of the supported syntax for <search-terms>.
\r
204 +dump format is intended to more robust against malformed message-ids
\r
205 +and tags containing whitespace or non-\fBascii\fR(7) characters. This
\r
206 +format hex-escapes all characters those outside of a small character
\r
207 +set, intended to be suitable for e.g. pathnames in most UNIX-like
\r
210 .B "notmuch restore"
\r
211 updates the maildir flags according to tag changes if the
\r
212 @@ -36,6 +69,20 @@ configuration option is enabled. See \fBnotmuch-config\fR(1) for
\r
221 +This option (the default) tries to guess the format from the
\r
222 +input. For correctly formed input in either supported format, this
\r
223 +heuristic, based the fact that batch-tag format contains no parentheses,
\r
224 +should be accurate.
\r
232 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
\r
projects / notmuch-archives.git / blob