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 4D8AB431FB6
\r
6 for <notmuch@notmuchmail.org>; Sat, 24 Nov 2012 13:20:52 -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 AwAm-4F-Q7+y for <notmuch@notmuchmail.org>;
\r
16 Sat, 24 Nov 2012 13:20:50 -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 9CFFB429E27
\r
21 for <notmuch@notmuchmail.org>; Sat, 24 Nov 2012 13:20:34 -0800 (PST)
\r
22 Received: from fctnnbsc30w-156034089108.dhcp-dynamic.fibreop.nb.bellaliant.net
\r
23 ([156.34.89.108] 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 1TcN9N-0006SW-J0; Sat, 24 Nov 2012 17:20:34 -0400
\r
28 Received: from bremner by zancas.localnet with local (Exim 4.80)
\r
29 (envelope-from <bremner@tethera.net>)
\r
30 id 1TcN9I-0008Dd-3v; Sat, 24 Nov 2012 17:20:28 -0400
\r
31 From: david@tethera.net
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [Patch v2 16/17] notmuch-{dump,
\r
34 restore}.1: document new format options
\r
35 Date: Sat, 24 Nov 2012 17:20:16 -0400
\r
36 Message-Id: <1353792017-31459-17-git-send-email-david@tethera.net>
\r
37 X-Mailer: git-send-email 1.7.10.4
\r
38 In-Reply-To: <1353792017-31459-1-git-send-email-david@tethera.net>
\r
39 References: <1353792017-31459-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, 24 Nov 2012 21:20:52 -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 | 58 +++++++++++++++++++++++++++++++++++++++++++
\r
62 man/man1/notmuch-restore.1 | 59 +++++++++++++++++++++++++++++++++++++++-----
\r
63 2 files changed, 111 insertions(+), 6 deletions(-)
\r
65 diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1
\r
66 index 230deec..9f59905 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,63 @@ 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" "> ... -- " "" " <" 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).
\r
138 With no search terms, a dump of all messages in the database will be
\r
139 generated. A "--" argument instructs notmuch that the
\r
140 remaining arguments are search terms.
\r
141 diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1
\r
142 index 2fa8733..3860829 100644
\r
143 --- a/man/man1/notmuch-restore.1
\r
144 +++ b/man/man1/notmuch-restore.1
\r
145 @@ -6,6 +6,7 @@ notmuch-restore \- restores the tags from the given file (see notmuch dump)
\r
147 .B "notmuch restore"
\r
148 .RB [ "--accumulate" ]
\r
149 +.RB [ "--format=(auto|batch-tag|sup)" ]
\r
150 .RI "[ --input=<" filename "> ]"
\r
153 @@ -15,19 +16,51 @@ Restores the tags from the given file (see
\r
155 The input is read from the given filename, if any, or from stdin.
\r
157 -Note: The dump file format is specifically chosen to be
\r
159 +Supported options for
\r
166 +The union of the existing and new tags is applied, instead of
\r
167 +replacing each message's tags as they are read in from the dump file.
\r
172 +.B \-\-format=(sup|batch-tag|auto)
\r
174 +Notmuch restore supports two plain text dump formats, with one message-id
\r
175 +per line, and a list of tags.
\r
176 +For details of the actual formats, see \fBnotmuch-dump\fR(1).
\r
184 +dump file format is specifically chosen to be
\r
185 compatible with the format of files produced by sup-dump.
\r
186 So if you've previously been using sup for mail, then the
\r
187 .B "notmuch restore"
\r
188 command provides you a way to import all of your tags (or labels as
\r
191 -The --accumulate switch causes the union of the existing and new tags to be
\r
192 -applied, instead of replacing each message's tags as they are read in from the
\r
199 -See \fBnotmuch-search-terms\fR(7)
\r
200 -for details of the supported syntax for <search-terms>.
\r
203 +dump format is intended to more robust against malformed message-ids
\r
204 +and tags containing whitespace or non-\fBascii\fR(7) characters. This
\r
205 +format hex-escapes all characters those outside of a small character
\r
206 +set, intended to be suitable for e.g. pathnames in most UNIX-like
\r
209 .B "notmuch restore"
\r
210 updates the maildir flags according to tag changes if the
\r
211 @@ -36,6 +69,20 @@ configuration option is enabled. See \fBnotmuch-config\fR(1) for
\r
220 +This option (the default) tries to guess the format from the
\r
221 +input. For correctly formed input in either supported format, this
\r
222 +heuristic, based the fact that batch-tag format contains no parentheses,
\r
223 +should be accurate.
\r
231 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
\r
projects / notmuch-archives.git / blob