From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 6FA4B431FB6 for ; Tue, 25 Dec 2012 11:43:26 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: 0.001 X-Spam-Level: X-Spam-Status: No, score=0.001 tagged_above=-999 required=5 tests=[WEIRD_QUOTING=0.001] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id pe9l27d3vXi6 for ; Tue, 25 Dec 2012 11:43:24 -0800 (PST) Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 43A78429E37 for ; Tue, 25 Dec 2012 11:43:16 -0800 (PST) Received: from fctnnbsc30w-156034082078.dhcp-dynamic.fibreop.nb.bellaliant.net ([156.34.82.78] helo=zancas.localnet) by tesseract.cs.unb.ca with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1TnaPC-0001iQ-5i; Tue, 25 Dec 2012 15:43:15 -0400 Received: from bremner by zancas.localnet with local (Exim 4.80) (envelope-from ) id 1TnaP3-0005nh-Lk; Tue, 25 Dec 2012 15:43:05 -0400 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [PATCH 10/11] man: document notmuch tag --batch, --input options Date: Tue, 25 Dec 2012 15:42:46 -0400 Message-Id: <1356464567-21779-11-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1356464567-21779-1-git-send-email-david@tethera.net> References: <1356464567-21779-1-git-send-email-david@tethera.net> X-Spam_bar: - X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 25 Dec 2012 19:43:26 -0000 From: Jani Nikula --- man/man1/notmuch-tag.1 | 92 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/man/man1/notmuch-tag.1 b/man/man1/notmuch-tag.1 index 9444aa4..3aa2fa5 100644 --- a/man/man1/notmuch-tag.1 +++ b/man/man1/notmuch-tag.1 @@ -6,6 +6,11 @@ notmuch-tag \- add/remove tags for all messages matching the search terms .B notmuch tag .RI "+<" tag ">|\-<" tag "> [...] [\-\-] <" search-term "> [...]" +.B notmuch tag +.RI "--batch" +.RI "[ --input=<" filename "> ]" + + .SH DESCRIPTION Add/remove tags for all messages matching the search terms. @@ -30,6 +35,93 @@ updates the maildir flags according to tag changes if the configuration option is enabled. See \fBnotmuch-config\fR(1) for details. +Supported options for +.B tag +include +.RS 4 +.TP 4 +.BR \-\-batch + +Read batch tagging operations from a file (stdin by default). This is more +efficient than repeated +.B notmuch tag +invocations. See +.B TAG FILE FORMAT +below for the input format. This option is not compatible with +specifying tagging on the command line. +.RE + +.RS 4 +.TP 4 +.BR "\-\-input=" + +Read input from given file, instead of from stdin. Implies +.BR --batch . + +.SH TAG FILE FORMAT + +The input must consist of lines of the format: + +.RI "+<" tag ">|\-<" tag "> [...] [\-\-] <" query ">" + +Each line is interpreted similarly to +.B notmuch tag +command line arguments. The delimiter is one or more spaces ' '. Any +characters in +.RI < tag > +.B may +be hex-encoded with %NN where NN is the hexadecimal value of the +character. To hex-encode a character with a multi-byte UTF-8 encoding, +hex-encode each byte. +Any spaces in +.B must +be hex-encoded as %20. Any characters that are not +part of +.RI < tag > +.B must not +be hex-encoded. + +In the future tag:"tag with spaces" style quoting may be supported for +.RI < tag > +as well; +for this reason all double quote characters in +.RI < tag > +.B should +be hex-encoded. + +The +.RI < query > +should be quoted using Xapian boolean term quoting rules: if a term +contains whitespace or a close paren or starts with a double quote, it +must be enclosed in double quotes (not including any prefix) and +double quotes inside the term must be doubled (see below for +examples). + +Leading and trailing space ' ' is ignored. Empty lines and lines +beginning with '#' are ignored. + +.SS EXAMPLE + +The following shows a valid input to batch tagging. Note that only the +isolated '*' acts as a wildcard. Also note the two different quotings +of the tag +.B space in tags +. +.RS +.nf ++winner * ++foo::bar%25 -- (One and Two) or (One and tag:winner) ++found::it -- tag:foo::bar% +# ignore this line and the next + ++space%20in%20tags -- Two +# add tag '(tags)', among other stunts. ++crazy{ +(tags) +&are +#possible\ -- tag:"space in tags" ++match*crazy -- tag:crazy{ ++some_tag -- id:"this is ""nauty)""" +.fi +.RE + .SH SEE ALSO \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), -- 1.7.10.4