X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.1;h=9d0473d5941423b310bf3c0af9389c2d49399064;hp=04bd0cf184cbaf4689dcdecb919fc9a02a46b0ac;hb=248e6f8c04ba88806ad7e8cd07f1c68493dc1a52;hpb=a2a522a758518d19e0cf4b96cf3c55287b0fbf4f diff --git a/notmuch.1 b/notmuch.1 index 04bd0cf1..9d0473d5 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 @@ -154,6 +146,12 @@ Supported options for include .RS 4 .TP 4 +.BR \-\-format= ( json | text ) + +Presents the results in either JSON or plain-text (default). +.RE +.RS 4 +.TP 4 .BR \-\-sort= ( newest\-first | oldest\-first ) This option can be used to present results in either chronological order @@ -169,6 +167,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 +177,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,7 +187,27 @@ 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=(json|text) + +.RS 4 +.TP 4 +.B text + +The default plain-text format has 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 @@ -195,6 +215,18 @@ 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 + +Format output as Javascript Object Notation (JSON). JSON output always +includes all messages in a matching thread; in effect +.B \-\-format=json +implies +.B \-\-entire\-thread + +.RE A common use of .B notmuch show is to display a single thread of email messages. For this, use a @@ -207,6 +239,7 @@ See the .B "SEARCH SYNTAX" section below for details of the supported syntax for . .RE +.RE The .B reply @@ -320,6 +353,32 @@ 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 + .SH SEARCH SYNTAX Several notmuch commands accept a common syntax for search terms. @@ -340,7 +399,7 @@ terms to match against specific portions of an email, (where attachment: - tag: + tag: (or is:) id: @@ -369,7 +428,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 @@ -416,6 +475,13 @@ specify a date range to return messages from 2009-10-01 until the current time: $(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