X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.1;h=1919176e79ca52aa64e3113bace55b7a5c671263;hp=04bd0cf184cbaf4689dcdecb919fc9a02a46b0ac;hb=6dcb7592e32ed5140ea0c0357ce78d6a37af6066;hpb=a2a522a758518d19e0cf4b96cf3c55287b0fbf4f diff --git a/notmuch.1 b/notmuch.1 index 04bd0cf1..1919176e 100644 --- a/notmuch.1 +++ b/notmuch.1 @@ -109,14 +109,6 @@ whenever new mail is delivered and you wish to incorporate it into the database. These subsequent runs will be much quicker than the initial run. -Note: -.B notmuch new -runs (other than the first run) will skip any read-only directories, -so you can use that to mark directories that will not receive any new -mail (and make -.B notmuch new -even faster). - Invoking .B notmuch with no command argument will run @@ -134,7 +126,7 @@ syntax. See the section below for more details on the supported syntax. The -.BR search " and "show +.BR search ", " show " and " count commands are used to query the email database. .RS 4 .TP 4 @@ -152,6 +144,52 @@ and the subject of the newest (or oldest) message. Supported options for .B search include +.RS 4 +.TP 4 +.BR \-\-format= ( json | text ) + +Presents the results in either JSON or plain-text (default). +.RE + +.RS 4 +.TP 4 +.B \-\-output=(summary|threads|messages|tags) + +.RS 4 +.TP 4 +.B summary + +Output a summary of each thread with any message matching the search +terms. The summary includes the thread ID, date, the number of +messages in the thread (both the number matched and the total number), +the authors of the thread and the subject. +.RE +.RS 4 +.TP 4 +.B threads + +Output the thread IDs of all threads with any message matching the +search terms, either one per line (--format=text) or as a JSON array +(--format=json). +.RE +.RS 4 +.TP 4 +.B messages + +Output the message IDs of all messages matching the search terms, +either one per line (--format=text) or as a JSON array +(--format=json). +.RE +.RS 4 +.TP 4 +.B tags + +Output all tags that appear on any message matching the search terms, +either one per line (--format=text) or as a JSON array +(--format=json). +.RE +.RE + .RS 4 .TP 4 .BR \-\-sort= ( newest\-first | oldest\-first ) @@ -169,6 +207,8 @@ when sorting by .B newest\-first the threads will be sorted by the newest message in each thread. +.RE +.RS 4 By default, results will be displayed in reverse chronological order, (that is, the newest results will be displayed first). @@ -177,7 +217,7 @@ See the section below for details of the supported syntax for . .RE .TP -.BR show " ..." +.BR show " [options...] ..." Shows all messages matching the search terms. @@ -187,14 +227,59 @@ message in date order). The output is not indented by default, but depth tags are printed so that proper indentation can be performed by a post-processor (such as the emacs interface to notmuch). -The output format is plain-text, with all text-content MIME parts +Supported options for +.B show +include +.RS 4 +.TP 4 +.B \-\-entire\-thread + +By default only those messages that match the search terms will be +displayed. With this option, all messages in the same thread as any +matched message will be displayed. +.RE + +.RS 4 +.TP 4 +.B \-\-format=(text|json|mbox) + +.RS 4 +.TP 4 +.B text + +The default plain-text format has all text-content MIME parts decoded. Various components in the output, .RB ( message ", " header ", " body ", " attachment ", and MIME " part ), will be delimited by easily-parsed markers. Each marker consists of a Control-L character (ASCII decimal 12), the name of the marker, and then either an opening or closing brace, ('{' or '}'), to either open or close the component. +.RE +.RS 4 +.TP 4 +.B json +The output is formatted with Javascript Object Notation (JSON). This +format is more robust than the text format for automated +processing. JSON output always includes all messages in a matching +thread; in effect +.B \-\-format=json +implies +.B \-\-entire\-thread + +.RE +.RS 4 +.TP 4 +.B mbox + +All matching messages are output in the traditional, Unix mbox format +with each message being prefixed by a line beginning with "From " and +a blank line separating each message. Lines in the message content +beginning with "From " (preceded by zero or more '>' characters) have +an additional '>' character added. This reversible escaping +is termed "mboxrd" format and described in detail here: +http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html +.RE A common use of .B notmuch show is to display a single thread of email messages. For this, use a @@ -207,6 +292,17 @@ See the .B "SEARCH SYNTAX" section below for details of the supported syntax for . .RE +.TP +.BR count " ..." + +Count messages matching the search terms. + +The number of matching messages is output to stdout. + +With no search terms, a count of all messages in the database will be +displayed. +.RE +.RE The .B reply @@ -223,12 +319,12 @@ takes an existing set of messages and constructs a suitable mail template. The Reply-to header (if any, otherwise From:) is used for the To: address. Vales from the To: and Cc: headers are copied, but not including any of the current user's email addresses (as configured -in primary_mail or other_email in the .notmuch-config file) in the +in primary_mail or other_email in the .notmuch\-config file) in the recipient list It also builds a suitable new subject, including Re: at the front (if not already present), and adding the message IDs of the messages being -replied to to the References list and setting the In-Reply-To: field +replied to to the References list and setting the In\-Reply\-To: field correctly. Finally, the original contents of the emails are quoted by prefixing @@ -247,8 +343,8 @@ include .BR default Includes subject and quoted message body. .TP -.BR headers-only -Only produces In-Reply-To, References, To, Cc, and Bcc headers. +.BR headers\-only +Only produces In\-Reply\-To, References, To, Cc, and Bcc headers. .RE See the @@ -272,18 +368,18 @@ contents. .RS 4 .TP 4 -.BR tag " +|- [...] [--] ..." +.BR tag " +|\- [...] [\-\-] ..." Add/remove tags for all messages matching the search terms. -Tags prefixed by '+' are added while those prefixed by '-' are +Tags prefixed by '+' are added while those prefixed by '\-' are removed. For each message, tag removal is performed before tag addition. The beginning of is recognized by the first -argument that begins with neither '+' nor '-'. Support for -an initial search term beginning with '+' or '-' is provided -by allowing the user to specify a "--" argument to separate +argument that begins with neither '+' nor '\-'. Support for +an initial search term beginning with '+' or '\-' is provided +by allowing the user to specify a "\-\-" argument to separate the tags from the search terms. See the @@ -320,6 +416,70 @@ So if you've previously been using sup for mail, then the .B "notmuch restore" command provides you a way to import all of your tags (or labels as sup calls them). +.RE + +The +.B part +command can used to output a single part of a multi-part MIME message. + +.RS 4 +.TP 4 +.BR part " \-\-part= ..." + +Output a single MIME part of a message. + +A single decoded MIME part, with no encoding or framing, is output to +stdout. The search terms must match only a single message, otherwise +this command will fail. + +The part number should match the part "id" field output by the +"\-\-format=json" option of "notmuch show". If the message specified by +the search terms does not include a part with the specified "id" there +will be no output. + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE + +The +.B config +command can be used to get or set settings int the notmuch +configuration file. + +.RS 4 +.TP 4 +.BR "config get "
. + +The value of the specified configuration item is printed to stdout. If +the item has multiple values, each value is separated by a newline +character. + +Available configuration items include at least + + database.path + + user.name + + user.primary_email + + user.other_email + + new.tags +.RE + +.RS 4 +.TP 4 +.BR "config set "
. " [values ...]" + +The specified configuration item is set to the given value. To +specify a multiple-value item, provide each value as a separate +command-line argument. + +If no values are provided, the specified configuration item will be +removed from the configuration file. +.RE + .SH SEARCH SYNTAX Several notmuch commands accept a common syntax for search terms. @@ -328,6 +488,9 @@ which will match all messages that contain all of the given terms/phrases in the body, the subject, or any of the sender or recipient headers. +As a special case, a search string consisting of exactly a single +asterisk ("*") will match all messages. + In addition to free text, the following prefixes can be used to force terms to match against specific portions of an email, (where indicate user-supplied values): @@ -340,7 +503,7 @@ terms to match against specific portions of an email, (where attachment: - tag: + tag: (or is:) id: @@ -369,7 +532,7 @@ prefix can be used to search for specific filenames (or extensions) of attachments to email messages. For -.BR tag: , +.BR tag: " and " is: valid tag values include .BR inbox " and " unread by default for new messages added by @@ -379,7 +542,7 @@ as well as any other tag values added manually with For .BR id: , -message ID values are the literal contents of the Message-ID: header +message ID values are the literal contents of the Message\-ID: header of email messages, but without the '<', '>' delimiters. The @@ -408,14 +571,21 @@ particular time range, (based on the Date: header) with a syntax of: .. Each timestamp is a number representing the number of seconds since -1970-01-01 00:00:00 UTC. This is not the most convenient means of +1970\-01\-01 00:00:00 UTC. This is not the most convenient means of expressing date ranges, but until notmuch is fixed to accept a more convenient form, one can use the date program to construct timestamps. For example, with the bash shell the folowing syntax would -specify a date range to return messages from 2009-10-01 until the +specify a date range to return messages from 2009\-10\-01 until the current time: - $(date +%s -d 2009-10-01)..$(date +%s) + $(date +%s \-d 2009\-10\-01)..$(date +%s) +.SH ENVIRONMENT +The following environment variables can be used to control the +behavior of notmuch. +.TP +.B NOTMUCH_CONFIG +Specifies the location of the notmuch configuration file. Notmuch will +use ${HOME}/.notmuch\-config if this variable is not set. .SH SEE ALSO The emacs-based interface to notmuch (available as .B notmuch.el