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 88E42431FAF
\r
6 for <notmuch@notmuchmail.org>; Sun, 18 Nov 2012 11:05:40 -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 PZl2lxSYNgts for <notmuch@notmuchmail.org>;
\r
16 Sun, 18 Nov 2012 11:05:39 -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 90D0E429E28
\r
21 for <notmuch@notmuchmail.org>; Sun, 18 Nov 2012 11:05:20 -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 1TaABD-00028H-Jv; Sun, 18 Nov 2012 15:05:19 -0400
\r
28 Received: from bremner by zancas.localnet with local (Exim 4.80)
\r
29 (envelope-from <bremner@tethera.net>)
\r
30 id 1TaAB8-0001JP-2k; Sun, 18 Nov 2012 15:05:14 -0400
\r
31 From: david@tethera.net
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [PATCH 16/16] notmuch-{dump,restore}.1: document new format options
\r
34 Date: Sun, 18 Nov 2012 15:04:58 -0400
\r
35 Message-Id: <1353265498-3839-17-git-send-email-david@tethera.net>
\r
36 X-Mailer: git-send-email 1.7.10.4
\r
37 In-Reply-To: <1353265498-3839-1-git-send-email-david@tethera.net>
\r
38 References: <1353265498-3839-1-git-send-email-david@tethera.net>
\r
40 Cc: David Bremner <bremner@debian.org>
\r
41 X-BeenThere: notmuch@notmuchmail.org
\r
42 X-Mailman-Version: 2.1.13
\r
44 List-Id: "Use and development of the notmuch mail system."
\r
45 <notmuch.notmuchmail.org>
\r
46 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
47 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
48 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
49 List-Post: <mailto:notmuch@notmuchmail.org>
\r
50 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
51 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
52 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
53 X-List-Received-Date: Sun, 18 Nov 2012 19:05:40 -0000
\r
55 From: David Bremner <bremner@debian.org>
\r
57 More or less arbitrarily, notmuch-dump.1 gets the more detailed
\r
58 description of the format.
\r
60 man/man1/notmuch-dump.1 | 58 +++++++++++++++++++++++++++++++++++++++++++
\r
61 man/man1/notmuch-restore.1 | 59 +++++++++++++++++++++++++++++++++++++++-----
\r
62 2 files changed, 111 insertions(+), 6 deletions(-)
\r
64 diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1
\r
65 index 230deec..b57c2c1 100644
\r
66 --- a/man/man1/notmuch-dump.1
\r
67 +++ b/man/man1/notmuch-dump.1
\r
68 @@ -5,6 +5,7 @@ notmuch-dump \- creates a plain-text dump of the tags of each message
\r
72 +.RB [ "\-\-format=(sup|batch-tag)" "] [--]"
\r
73 .RI "[ --output=<" filename "> ] [--]"
\r
74 .RI "[ <" search-term ">...]"
\r
76 @@ -19,6 +20,63 @@ recreated from the messages themselves. The output of notmuch dump is
\r
77 therefore the only critical thing to backup (and much more friendly to
\r
78 incremental backup than the native database files.)
\r
81 +.B \-\-format=(sup|batch-tag)
\r
83 +Notmuch restore supports two plain text dump formats, both with one message-id
\r
84 +per line, followed by a list of tags.
\r
92 +dump file format is specifically chosen to be
\r
93 +compatible with the format of files produced by sup-dump.
\r
94 +So if you've previously been using sup for mail, then the
\r
95 +.B "notmuch restore"
\r
96 +command provides you a way to import all of your tags (or labels as
\r
98 +Each line has the following form
\r
101 +.RI < message-id >
\r
106 +with zero or more tags are separated by spaces. Note that (malformed)
\r
107 +message-ids may contained arbitrary non-null characters. Note also
\r
108 +that tags with spaces will not be correctly restored with this format.
\r
119 +dump format is intended to more robust against malformed message-ids
\r
120 +and tags containing whitespace or non-\fBascii\fR(7) characters.
\r
121 +Each line has the form
\r
124 +.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " <" encoded-message-id >
\r
126 +where encoded means that every byte not matching the regex
\r
127 +.B [A-Za-z0-9+-_@=.:,]
\r
130 +where nn is the two digit hex encoding.
\r
131 +The astute reader will notice this is a special case of the batch input
\r
132 +format for \fBnotmuch-tag\fR(1).
\r
137 With no search terms, a dump of all messages in the database will be
\r
138 generated. A "--" argument instructs notmuch that the
\r
139 remaining arguments are search terms.
\r
140 diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1
\r
141 index 2fa8733..3860829 100644
\r
142 --- a/man/man1/notmuch-restore.1
\r
143 +++ b/man/man1/notmuch-restore.1
\r
144 @@ -6,6 +6,7 @@ notmuch-restore \- restores the tags from the given file (see notmuch dump)
\r
146 .B "notmuch restore"
\r
147 .RB [ "--accumulate" ]
\r
148 +.RB [ "--format=(auto|batch-tag|sup)" ]
\r
149 .RI "[ --input=<" filename "> ]"
\r
152 @@ -15,19 +16,51 @@ Restores the tags from the given file (see
\r
154 The input is read from the given filename, if any, or from stdin.
\r
156 -Note: The dump file format is specifically chosen to be
\r
158 +Supported options for
\r
165 +The union of the existing and new tags is applied, instead of
\r
166 +replacing each message's tags as they are read in from the dump file.
\r
171 +.B \-\-format=(sup|batch-tag|auto)
\r
173 +Notmuch restore supports two plain text dump formats, with one message-id
\r
174 +per line, and a list of tags.
\r
175 +For details of the actual formats, see \fBnotmuch-dump\fR(1).
\r
183 +dump file format is specifically chosen to be
\r
184 compatible with the format of files produced by sup-dump.
\r
185 So if you've previously been using sup for mail, then the
\r
186 .B "notmuch restore"
\r
187 command provides you a way to import all of your tags (or labels as
\r
190 -The --accumulate switch causes the union of the existing and new tags to be
\r
191 -applied, instead of replacing each message's tags as they are read in from the
\r
198 -See \fBnotmuch-search-terms\fR(7)
\r
199 -for details of the supported syntax for <search-terms>.
\r
202 +dump format is intended to more robust against malformed message-ids
\r
203 +and tags containing whitespace or non-\fBascii\fR(7) characters. This
\r
204 +format hex-escapes all characters those outside of a small character
\r
205 +set, intended to be suitable for e.g. pathnames in most UNIX-like
\r
208 .B "notmuch restore"
\r
209 updates the maildir flags according to tag changes if the
\r
210 @@ -36,6 +69,20 @@ configuration option is enabled. See \fBnotmuch-config\fR(1) for
\r
219 +This option (the default) tries to guess the format from the
\r
220 +input. For correctly formed input in either supported format, this
\r
221 +heuristic, based the fact that batch-tag format contains no parentheses,
\r
222 +should be accurate.
\r
230 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
\r
projects / notmuch-archives.git / blob