X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.1;h=e573749cd5988391c8d537ff3b8e5d90c6bbfde6;hp=c5a7711fcf13459b854acd26b82ab633633b47a5;hb=357b48d34b9cd32473d39321b1ae460d05f5c7cd;hpb=793cbf80495b8230e0b4de6ac609e2ca88b7dd4b diff --git a/notmuch.1 b/notmuch.1 index c5a7711f..e573749c 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,29 +146,12 @@ Supported options for include .RS 4 .TP 4 -.BR \-\-max\-threads= - -Restricts displayed search results to a subset of the complete results -that would match the terms. With this option, no more than -thread results will be displayed. If this option is not used, then all -matching threads will be displayed. See also the -.B \-\-first -option. - -.TP -.BR \-\-first= - -Omits the first threads from the search results that would -otherwise be displayed. Together with the -.BR \-\-max\-threads -option, this can be used to perform incremental searches. For example, -the first 50 thread results can be displayed with -.B "\-\-first=0 \-\-max\-threads=50" -and the next 50 could be displayed with -.B "\-\-first=50 \-\-max\-threads=50" -etc. +.BR \-\-format= ( json | text ) -.TP +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 @@ -192,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). @@ -200,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. @@ -210,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 @@ -218,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 @@ -230,13 +239,14 @@ See the .B "SEARCH SYNTAX" section below for details of the supported syntax for . .RE +.RE The .B reply command is useful for preparing a template for an email reply. - -.TP -.BR reply " ..." +.RS 4 +.TP 4 +.BR reply " [options...] ..." Constructs a reply template for a set of messages. @@ -259,6 +269,21 @@ each line with '> ' and included in the body. The resulting message template is output to stdout. +Supported options for +.B reply +include +.RS +.TP 4 +.BR \-\-format= ( default | headers\-only ) +.RS +.TP 4 +.BR default +Includes subject and quoted message body. +.TP +.BR headers-only +Only produces In-Reply-To, References, To, Cc, and Bcc headers. +.RE + See the .B "SEARCH SYNTAX" section below for details of the supported syntax for . @@ -271,6 +296,7 @@ once. For example, when a series of patches are sent in a single thread, replying to the entire thread allows for the reply to comment on issue found in multiple patches. .RE +.RE The .B tag @@ -347,7 +373,7 @@ terms to match against specific portions of an email, (where attachment: - tag: + tag: (or is:) id: @@ -376,7 +402,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 @@ -423,6 +449,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