X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=notmuch.1;h=c1aa4e329c43f0e377539b6ed454b95c1555b2ea;hp=0e6a2edcc2c76c17f796a4d6f375bb4411e4bfef;hb=59b251ef940609dac7e17528065a39544463e0b4;hpb=7d9851e293fad762cd959e9be819e48a26087cdc diff --git a/notmuch.1 b/notmuch.1 index 0e6a2edc..c1aa4e32 100644 --- a/notmuch.1 +++ b/notmuch.1 @@ -126,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 @@ -150,6 +150,53 @@ include Presents the results in either JSON or plain-text (default). .RE + +.RS 4 +.TP 4 +.B \-\-output=(summary|threads|messages|files|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 files + +Output the filenames 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 ) @@ -201,32 +248,101 @@ matched message will be displayed. .RS 4 .TP 4 -.B \-\-format=(json|text) +.B \-\-format=(text|json|mbox|raw) .RS 4 .TP 4 -.B text +.BR text " (default for messages)" -The default plain-text format has text-content MIME parts +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. - +or close the component. For a multipart MIME message, these parts will +be nested. .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 +The output is formatted with Javascript Object Notation (JSON). This +format is more robust than the text format for automated +processing. The nested structure of multipart MIME messages is +reflected in nested JSON output. 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: + +.nf +.nh +http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html +.hy +.fi +. +.RE +.RS 4 +.TP 4 +.BR raw " (default for a single part, see \-\-part)" + +For a message, the original, raw content of the email message is +output. Consumers of this format should expect to implement MIME +decoding and similar functions. + +For a single part (\-\-part) the raw part content is output after +performing any necessary MIME decoding. + +The raw format must only be used with search terms matching single +message. +.RE +.RE + +.RS 4 +.TP 4 +.B \-\-part=N + +Output the single decoded MIME part N of a single message. The search +terms must match only a single message. Message parts are numbered in +a depth-first walk of the message MIME structure, and are identified +in the 'json' or 'text' output formats. +.RE + +.RS 4 +.TP 4 +.B \-\-verify + +Compute and report the validity of any MIME cryptographic signatures +found in the selected content (ie. "multipart/signed" parts). Status +of the signature will be reported (currently only supported with +--format=json), and the multipart/signed part will be replaced by the +signed data. +.RE + +.RS 4 +.TP 4 +.B \-\-decrypt + +Decrypt any MIME encrypted parts found in the selected content +(ie. "multipart/encrypted" parts). Status of the decryption will be +reported (currently only supported with --format=json) and the +multipart/encrypted part will be replaced by the decrypted +content. +.RE + A common use of .B notmuch show is to display a single thread of email messages. For this, use a @@ -239,6 +355,17 @@ See the .B "SEARCH SYNTAX" section below for details of the supported syntax for . .RE +.RS 4 +.TP 4 +.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 @@ -379,6 +506,44 @@ See the 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. @@ -387,6 +552,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): @@ -405,6 +573,8 @@ terms to match against specific portions of an email, (where thread: + folder: + The .B from: prefix is used to match the name or address of the sender of an email @@ -448,6 +618,13 @@ internally by notmuch (and do not appear in email messages). These thread ID values can be seen in the first column of output from .B "notmuch search" +The +.B folder: +prefix can be used to search for email message files that are +contained within particular directories within the mail store. Only +the directory components below the top-level mail database path are +available to be searched. + In addition to individual terms, multiple terms can be combined with Boolean operators ( .BR and ", " or ", " not