55/375358b0b0334804e4d081748e9891d91e2c6d

   1 Return-Path: <jani@nikula.org>\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 41AC7431FAE\r
   6         for <notmuch@notmuchmail.org>; Sun,  2 Dec 2012 05:41:01 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\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 m4QxtjW8g+zv for <notmuch@notmuchmail.org>;\r
  16         Sun,  2 Dec 2012 05:40:56 -0800 (PST)\r
  17 Received: from mail-lb0-f181.google.com (mail-lb0-f181.google.com\r
  18         [209.85.217.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
  19         (No client certificate requested)\r
  20         by olra.theworths.org (Postfix) with ESMTPS id 6C6BB431FAF\r
  21         for <notmuch@notmuchmail.org>; Sun,  2 Dec 2012 05:40:56 -0800 (PST)\r
  22 Received: by mail-lb0-f181.google.com with SMTP id ge1so1767585lbb.26\r
  23         for <notmuch@notmuchmail.org>; Sun, 02 Dec 2012 05:40:55 -0800 (PST)\r
  24 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;\r
  25         d=google.com; s=20120113;\r
  26         h=from:to:cc:subject:in-reply-to:references:user-agent:date\r
  27         :message-id:mime-version:content-type:x-gm-message-state;\r
  28         bh=mNdZAAAJJcUkE8u73nEW9Ev8FaS+H5xlbRRcA9V65R8=;\r
  29         b=RofEJtvuRJ7/OHM5J1OeVMiZypDGWYnq/lfYBd8M07IUmBRcZE+2iIB3dDqPMW4mSW\r
  30         d73JcGcH/WFKlNRJDgk2IpcFNc9mVcHYG3aXtPftB/9Vk86tAQ0DBP9mlRxp7DqGAfVh\r
  31         FNQr19TWblEUS1Wh5MzmzeX0oBSgS9h87rITSTapAiKbxPgGJiaKJf21QQ37P3UvE94X\r
  32         2e4sx7WXEudVc/RkL4a3NvazFsFxzUsHBp/kCFekmqiDi0m0YLQjQAp+Xu2Va1nIp9/R\r
  33         GZvsuWorEXaC+GwR9KWaHfnZ1RDabuKgK2v1BCm3mdSsREzWjfY0xr+bqyH+L/sjl4MQ\r
  34         gY2A==\r
  35 Received: by 10.152.124.111 with SMTP id mh15mr6640542lab.20.1354455654902;\r
  36         Sun, 02 Dec 2012 05:40:54 -0800 (PST)\r
  37 Received: from localhost (dsl-hkibrasgw4-fe51df00-27.dhcp.inet.fi.\r
  38         [80.223.81.27])\r
  39         by mx.google.com with ESMTPS id d5sm4151516lbk.10.2012.12.02.05.40.53\r
  40         (version=SSLv3 cipher=OTHER); Sun, 02 Dec 2012 05:40:54 -0800 (PST)\r
  41 From: Jani Nikula <jani@nikula.org>\r
  42 To: david@tethera.net, notmuch@notmuchmail.org\r
  43 Subject: Re: [Patch v2 16/17] notmuch-{dump,\r
  44         restore}.1: document new format options\r
  45 In-Reply-To: <1353792017-31459-17-git-send-email-david@tethera.net>\r
  46 References: <1353792017-31459-1-git-send-email-david@tethera.net>\r
  47         <1353792017-31459-17-git-send-email-david@tethera.net>\r
  48 User-Agent: Notmuch/0.14+124~g3b17402 (http://notmuchmail.org) Emacs/23.4.1\r
  49         (i686-pc-linux-gnu)\r
  50 Date: Sun, 02 Dec 2012 15:40:51 +0200\r
  51 Message-ID: <87wqx0d124.fsf@nikula.org>\r
  52 MIME-Version: 1.0\r
  53 Content-Type: text/plain; charset=us-ascii\r
  54 X-Gm-Message-State:\r
  55  ALoCoQkOeGYqc/hhrnsFXpYNsPPDMq+mkmbrBpB7r8RZtRuziA3yH21biPwfR5oJYLl0+PUDbuwd\r
  56 Cc: David Bremner <bremner@debian.org>\r
  57 X-BeenThere: notmuch@notmuchmail.org\r
  58 X-Mailman-Version: 2.1.13\r
  59 Precedence: list\r
  60 List-Id: "Use and development of the notmuch mail system."\r
  61         <notmuch.notmuchmail.org>\r
  62 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  63         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  64 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  65 List-Post: <mailto:notmuch@notmuchmail.org>\r
  66 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  67 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  68         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  69 X-List-Received-Date: Sun, 02 Dec 2012 13:41:01 -0000\r
  70 \r
  71 On Sat, 24 Nov 2012, david@tethera.net wrote:\r
  72 > From: David Bremner <bremner@debian.org>\r
  73 >\r
  74 > More or less arbitrarily, notmuch-dump.1 gets the more detailed\r
  75 > description of the format.\r
  76 > ---\r
  77 >  man/man1/notmuch-dump.1    |   58 +++++++++++++++++++++++++++++++++++++++++++\r
  78 >  man/man1/notmuch-restore.1 |   59 +++++++++++++++++++++++++++++++++++++++-----\r
  79 >  2 files changed, 111 insertions(+), 6 deletions(-)\r
  80 >\r
  81 > diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1\r
  82 > index 230deec..9f59905 100644\r
  83 > --- a/man/man1/notmuch-dump.1\r
  84 > +++ b/man/man1/notmuch-dump.1\r
  85 > @@ -5,6 +5,7 @@ notmuch-dump \- creates a plain-text dump of the tags of each message\r
  86 >  .SH SYNOPSIS\r
  87 >  \r
  88 >  .B "notmuch dump"\r
  89 > +.RB  [ "\-\-format=(sup|batch-tag)"  "] [--]"\r
  90 >  .RI "[ --output=<" filename "> ] [--]"\r
  91 >  .RI "[ <" search-term ">...]"\r
  92 >  \r
  93 > @@ -19,6 +20,63 @@ recreated from the messages themselves.  The output of notmuch dump is\r
  94 >  therefore the only critical thing to backup (and much more friendly to\r
  95 >  incremental backup than the native database files.)\r
  96 >  \r
  97 > +.TP 4\r
  98 > +.B \-\-format=(sup|batch-tag)\r
  99 > +\r
 100 > +Notmuch restore supports two plain text dump formats, both with one message-id\r
 101 > +per line, followed by a list of tags.\r
 102 \r
 103 "followed by tags" is not entirely accurate for batch-tag.\r
 104 \r
 105 > +\r
 106 > +.RS 4\r
 107 > +.TP 4\r
 108 > +.B sup\r
 109 > +\r
 110 > +The\r
 111 > +.B sup\r
 112 > +dump file format is specifically chosen to be\r
 113 > +compatible with the format of files produced by sup-dump.\r
 114 > +So if you've previously been using sup for mail, then the\r
 115 > +.B "notmuch restore"\r
 116 > +command provides you a way to import all of your tags (or labels as\r
 117 > +sup calls them).\r
 118 > +Each line has the following form\r
 119 \r
 120 Should we deprecate the sup format for new dumps at the same time? Issue\r
 121 a warning message on dumping too (unless --format is explicitly\r
 122 specified), telling about the new batch-tag format. I think we should\r
 123 eventually make batch-tag the default.\r
 124 \r
 125 > +\r
 126 > +.RS 4\r
 127 > +.RI < message-id >\r
 128 > +.B (\r
 129 > +.RI < tag "> ..."\r
 130 > +.B )\r
 131 > +\r
 132 > +with zero or more tags are separated by spaces. Note that (malformed)\r
 133 > +message-ids may contain arbitrary non-null characters. Note also\r
 134 > +that tags with spaces will not be correctly restored with this format.\r
 135 > +\r
 136 > +.RE\r
 137 > +\r
 138 > +.RE\r
 139 > +.RS 4\r
 140 > +.TP 4\r
 141 > +.B batch-tag\r
 142 > +\r
 143 > +The\r
 144 > +.B batch-tag\r
 145 > +dump format is intended to more robust against malformed message-ids\r
 146 > +and tags containing whitespace or non-\fBascii\fR(7) characters.\r
 147 > +Each line has the form\r
 148 > +\r
 149 > +.RS 4\r
 150 > +.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " <" encoded-message-id >\r
 151 \r
 152 Mention that the id: prefix is present in dump and required in restore.\r
 153 \r
 154 BR,\r
 155 Jani.\r
 156 \r
 157 > +\r
 158 > +where encoded means that every byte not matching the regex\r
 159 > +.B [A-Za-z0-9+-_@=.:,]\r
 160 > +is replace by\r
 161 > +.B %nn\r
 162 > +where nn is the two digit hex encoding.\r
 163 > +The astute reader will notice this is a special case of the batch input\r
 164 > +format for \fBnotmuch-tag\fR(1).\r
 165 > +\r
 166 > +.RE\r
 167 > +\r
 168 > +\r
 169 >  With no search terms, a dump of all messages in the database will be\r
 170 >  generated.  A "--" argument instructs notmuch that the\r
 171 >  remaining arguments are search terms.\r
 172 > diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1\r
 173 > index 2fa8733..3860829 100644\r
 174 > --- a/man/man1/notmuch-restore.1\r
 175 > +++ b/man/man1/notmuch-restore.1\r
 176 > @@ -6,6 +6,7 @@ notmuch-restore \- restores the tags from the given file (see notmuch dump)\r
 177 >  \r
 178 >  .B "notmuch restore"\r
 179 >  .RB [ "--accumulate" ]\r
 180 > +.RB [ "--format=(auto|batch-tag|sup)" ]\r
 181 >  .RI "[ --input=<" filename "> ]"\r
 182 >  \r
 183 >  .SH DESCRIPTION\r
 184 > @@ -15,19 +16,51 @@ Restores the tags from the given file (see\r
 185 >  \r
 186 >  The input is read from the given filename, if any, or from stdin.\r
 187 >  \r
 188 > -Note: The dump file format is specifically chosen to be\r
 189 > +\r
 190 > +Supported options for\r
 191 > +.B restore\r
 192 > +include\r
 193 > +.RS 4\r
 194 > +.TP 4\r
 195 > +.B \-\-accumulate\r
 196 > +\r
 197 > +The union of the existing and new tags is applied, instead of\r
 198 > +replacing each message's tags as they are read in from the dump file.\r
 199 > +\r
 200 > +.RE\r
 201 > +.RS 4\r
 202 > +.TP 4\r
 203 > +.B \-\-format=(sup|batch-tag|auto)\r
 204 > +\r
 205 > +Notmuch restore supports two plain text dump formats, with one message-id\r
 206 > +per line, and a list of tags.\r
 207 > +For details of the actual formats, see \fBnotmuch-dump\fR(1).\r
 208 > +\r
 209 > +.RS 4\r
 210 > +.TP 4\r
 211 > +.B sup\r
 212 > +\r
 213 > +The\r
 214 > +.B sup\r
 215 > +dump file format is specifically chosen to be\r
 216 >  compatible with the format of files produced by sup-dump.\r
 217 >  So if you've previously been using sup for mail, then the\r
 218 >  .B "notmuch restore"\r
 219 >  command provides you a way to import all of your tags (or labels as\r
 220 >  sup calls them).\r
 221 >  \r
 222 > -The --accumulate switch causes the union of the existing and new tags to be\r
 223 > -applied, instead of replacing each message's tags as they are read in from the\r
 224 > -dump file.\r
 225 > +.RE\r
 226 > +.RS 4\r
 227 > +.TP 4\r
 228 > +.B batch-tag\r
 229 >  \r
 230 > -See \fBnotmuch-search-terms\fR(7)\r
 231 > -for details of the supported syntax for <search-terms>.\r
 232 > +The\r
 233 > +.B batch-tag\r
 234 > +dump format is intended to more robust against malformed message-ids\r
 235 > +and tags containing whitespace or non-\fBascii\fR(7) characters.  This\r
 236 > +format hex-escapes all characters those outside of a small character\r
 237 > +set, intended to be suitable for e.g. pathnames in most UNIX-like\r
 238 > +systems.\r
 239 >  \r
 240 >  .B "notmuch restore"\r
 241 >  updates the maildir flags according to tag changes if the\r
 242 > @@ -36,6 +69,20 @@ configuration option is enabled. See \fBnotmuch-config\fR(1) for\r
 243 >  details.\r
 244 >  \r
 245 >  .RE\r
 246 > +\r
 247 > +.RS 4\r
 248 > +.TP 4\r
 249 > +.B auto\r
 250 > +\r
 251 > +This option (the default) tries to guess the format from the\r
 252 > +input. For correctly formed input in either supported format, this\r
 253 > +heuristic, based the fact that batch-tag format contains no parentheses,\r
 254 > +should be accurate.\r
 255 > +\r
 256 > +.RE\r
 257 > +\r
 258 > +.RE\r
 259 > +\r
 260 >  .SH SEE ALSO\r
 261 >  \r
 262 >  \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),\r
 263 > -- \r
 264 > 1.7.10.4\r
 265 >\r
 266 > _______________________________________________\r
 267 > notmuch mailing list\r
 268 > notmuch@notmuchmail.org\r
 269 > http://notmuchmail.org/mailman/listinfo/notmuch\r