--- /dev/null
+Return-Path: <jani@nikula.org>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 41AC7431FAE\r
+ for <notmuch@notmuchmail.org>; Sun, 2 Dec 2012 05:41:01 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id m4QxtjW8g+zv for <notmuch@notmuchmail.org>;\r
+ Sun, 2 Dec 2012 05:40:56 -0800 (PST)\r
+Received: from mail-lb0-f181.google.com (mail-lb0-f181.google.com\r
+ [209.85.217.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
+ (No client certificate requested)\r
+ by olra.theworths.org (Postfix) with ESMTPS id 6C6BB431FAF\r
+ for <notmuch@notmuchmail.org>; Sun, 2 Dec 2012 05:40:56 -0800 (PST)\r
+Received: by mail-lb0-f181.google.com with SMTP id ge1so1767585lbb.26\r
+ for <notmuch@notmuchmail.org>; Sun, 02 Dec 2012 05:40:55 -0800 (PST)\r
+X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;\r
+ d=google.com; s=20120113;\r
+ h=from:to:cc:subject:in-reply-to:references:user-agent:date\r
+ :message-id:mime-version:content-type:x-gm-message-state;\r
+ bh=mNdZAAAJJcUkE8u73nEW9Ev8FaS+H5xlbRRcA9V65R8=;\r
+ b=RofEJtvuRJ7/OHM5J1OeVMiZypDGWYnq/lfYBd8M07IUmBRcZE+2iIB3dDqPMW4mSW\r
+ d73JcGcH/WFKlNRJDgk2IpcFNc9mVcHYG3aXtPftB/9Vk86tAQ0DBP9mlRxp7DqGAfVh\r
+ FNQr19TWblEUS1Wh5MzmzeX0oBSgS9h87rITSTapAiKbxPgGJiaKJf21QQ37P3UvE94X\r
+ 2e4sx7WXEudVc/RkL4a3NvazFsFxzUsHBp/kCFekmqiDi0m0YLQjQAp+Xu2Va1nIp9/R\r
+ GZvsuWorEXaC+GwR9KWaHfnZ1RDabuKgK2v1BCm3mdSsREzWjfY0xr+bqyH+L/sjl4MQ\r
+ gY2A==\r
+Received: by 10.152.124.111 with SMTP id mh15mr6640542lab.20.1354455654902;\r
+ Sun, 02 Dec 2012 05:40:54 -0800 (PST)\r
+Received: from localhost (dsl-hkibrasgw4-fe51df00-27.dhcp.inet.fi.\r
+ [80.223.81.27])\r
+ by mx.google.com with ESMTPS id d5sm4151516lbk.10.2012.12.02.05.40.53\r
+ (version=SSLv3 cipher=OTHER); Sun, 02 Dec 2012 05:40:54 -0800 (PST)\r
+From: Jani Nikula <jani@nikula.org>\r
+To: david@tethera.net, notmuch@notmuchmail.org\r
+Subject: Re: [Patch v2 16/17] notmuch-{dump,\r
+ restore}.1: document new format options\r
+In-Reply-To: <1353792017-31459-17-git-send-email-david@tethera.net>\r
+References: <1353792017-31459-1-git-send-email-david@tethera.net>\r
+ <1353792017-31459-17-git-send-email-david@tethera.net>\r
+User-Agent: Notmuch/0.14+124~g3b17402 (http://notmuchmail.org) Emacs/23.4.1\r
+ (i686-pc-linux-gnu)\r
+Date: Sun, 02 Dec 2012 15:40:51 +0200\r
+Message-ID: <87wqx0d124.fsf@nikula.org>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+X-Gm-Message-State:\r
+ ALoCoQkOeGYqc/hhrnsFXpYNsPPDMq+mkmbrBpB7r8RZtRuziA3yH21biPwfR5oJYLl0+PUDbuwd\r
+Cc: David Bremner <bremner@debian.org>\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sun, 02 Dec 2012 13:41:01 -0000\r
+\r
+On Sat, 24 Nov 2012, david@tethera.net wrote:\r
+> From: David Bremner <bremner@debian.org>\r
+>\r
+> More or less arbitrarily, notmuch-dump.1 gets the more detailed\r
+> description of the format.\r
+> ---\r
+> man/man1/notmuch-dump.1 | 58 +++++++++++++++++++++++++++++++++++++++++++\r
+> man/man1/notmuch-restore.1 | 59 +++++++++++++++++++++++++++++++++++++++-----\r
+> 2 files changed, 111 insertions(+), 6 deletions(-)\r
+>\r
+> diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1\r
+> index 230deec..9f59905 100644\r
+> --- a/man/man1/notmuch-dump.1\r
+> +++ b/man/man1/notmuch-dump.1\r
+> @@ -5,6 +5,7 @@ notmuch-dump \- creates a plain-text dump of the tags of each message\r
+> .SH SYNOPSIS\r
+> \r
+> .B "notmuch dump"\r
+> +.RB [ "\-\-format=(sup|batch-tag)" "] [--]"\r
+> .RI "[ --output=<" filename "> ] [--]"\r
+> .RI "[ <" search-term ">...]"\r
+> \r
+> @@ -19,6 +20,63 @@ recreated from the messages themselves. The output of notmuch dump is\r
+> therefore the only critical thing to backup (and much more friendly to\r
+> incremental backup than the native database files.)\r
+> \r
+> +.TP 4\r
+> +.B \-\-format=(sup|batch-tag)\r
+> +\r
+> +Notmuch restore supports two plain text dump formats, both with one message-id\r
+> +per line, followed by a list of tags.\r
+\r
+"followed by tags" is not entirely accurate for batch-tag.\r
+\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B sup\r
+> +\r
+> +The\r
+> +.B sup\r
+> +dump file format is specifically chosen to be\r
+> +compatible with the format of files produced by sup-dump.\r
+> +So if you've previously been using sup for mail, then the\r
+> +.B "notmuch restore"\r
+> +command provides you a way to import all of your tags (or labels as\r
+> +sup calls them).\r
+> +Each line has the following form\r
+\r
+Should we deprecate the sup format for new dumps at the same time? Issue\r
+a warning message on dumping too (unless --format is explicitly\r
+specified), telling about the new batch-tag format. I think we should\r
+eventually make batch-tag the default.\r
+\r
+> +\r
+> +.RS 4\r
+> +.RI < message-id >\r
+> +.B (\r
+> +.RI < tag "> ..."\r
+> +.B )\r
+> +\r
+> +with zero or more tags are separated by spaces. Note that (malformed)\r
+> +message-ids may contain arbitrary non-null characters. Note also\r
+> +that tags with spaces will not be correctly restored with this format.\r
+> +\r
+> +.RE\r
+> +\r
+> +.RE\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B batch-tag\r
+> +\r
+> +The\r
+> +.B batch-tag\r
+> +dump format is intended to more robust against malformed message-ids\r
+> +and tags containing whitespace or non-\fBascii\fR(7) characters.\r
+> +Each line has the form\r
+> +\r
+> +.RS 4\r
+> +.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " <" encoded-message-id >\r
+\r
+Mention that the id: prefix is present in dump and required in restore.\r
+\r
+BR,\r
+Jani.\r
+\r
+> +\r
+> +where encoded means that every byte not matching the regex\r
+> +.B [A-Za-z0-9+-_@=.:,]\r
+> +is replace by\r
+> +.B %nn\r
+> +where nn is the two digit hex encoding.\r
+> +The astute reader will notice this is a special case of the batch input\r
+> +format for \fBnotmuch-tag\fR(1).\r
+> +\r
+> +.RE\r
+> +\r
+> +\r
+> With no search terms, a dump of all messages in the database will be\r
+> generated. A "--" argument instructs notmuch that the\r
+> remaining arguments are search terms.\r
+> diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1\r
+> index 2fa8733..3860829 100644\r
+> --- a/man/man1/notmuch-restore.1\r
+> +++ b/man/man1/notmuch-restore.1\r
+> @@ -6,6 +6,7 @@ notmuch-restore \- restores the tags from the given file (see notmuch dump)\r
+> \r
+> .B "notmuch restore"\r
+> .RB [ "--accumulate" ]\r
+> +.RB [ "--format=(auto|batch-tag|sup)" ]\r
+> .RI "[ --input=<" filename "> ]"\r
+> \r
+> .SH DESCRIPTION\r
+> @@ -15,19 +16,51 @@ Restores the tags from the given file (see\r
+> \r
+> The input is read from the given filename, if any, or from stdin.\r
+> \r
+> -Note: The dump file format is specifically chosen to be\r
+> +\r
+> +Supported options for\r
+> +.B restore\r
+> +include\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B \-\-accumulate\r
+> +\r
+> +The union of the existing and new tags is applied, instead of\r
+> +replacing each message's tags as they are read in from the dump file.\r
+> +\r
+> +.RE\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B \-\-format=(sup|batch-tag|auto)\r
+> +\r
+> +Notmuch restore supports two plain text dump formats, with one message-id\r
+> +per line, and a list of tags.\r
+> +For details of the actual formats, see \fBnotmuch-dump\fR(1).\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B sup\r
+> +\r
+> +The\r
+> +.B sup\r
+> +dump file format is specifically chosen to be\r
+> compatible with the format of files produced by sup-dump.\r
+> So if you've previously been using sup for mail, then the\r
+> .B "notmuch restore"\r
+> command provides you a way to import all of your tags (or labels as\r
+> sup calls them).\r
+> \r
+> -The --accumulate switch causes the union of the existing and new tags to be\r
+> -applied, instead of replacing each message's tags as they are read in from the\r
+> -dump file.\r
+> +.RE\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B batch-tag\r
+> \r
+> -See \fBnotmuch-search-terms\fR(7)\r
+> -for details of the supported syntax for <search-terms>.\r
+> +The\r
+> +.B batch-tag\r
+> +dump format is intended to more robust against malformed message-ids\r
+> +and tags containing whitespace or non-\fBascii\fR(7) characters. This\r
+> +format hex-escapes all characters those outside of a small character\r
+> +set, intended to be suitable for e.g. pathnames in most UNIX-like\r
+> +systems.\r
+> \r
+> .B "notmuch restore"\r
+> updates the maildir flags according to tag changes if the\r
+> @@ -36,6 +69,20 @@ configuration option is enabled. See \fBnotmuch-config\fR(1) for\r
+> details.\r
+> \r
+> .RE\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B auto\r
+> +\r
+> +This option (the default) tries to guess the format from the\r
+> +input. For correctly formed input in either supported format, this\r
+> +heuristic, based the fact that batch-tag format contains no parentheses,\r
+> +should be accurate.\r
+> +\r
+> +.RE\r
+> +\r
+> +.RE\r
+> +\r
+> .SH SEE ALSO\r
+> \r
+> \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),\r
+> -- \r
+> 1.7.10.4\r
+>\r
+> _______________________________________________\r
+> notmuch mailing list\r
+> notmuch@notmuchmail.org\r
+> http://notmuchmail.org/mailman/listinfo/notmuch\r
projects / notmuch-archives.git / commitdiff