git.notmuchmail.org Git - notmuch/blob - man/man1/notmuch-search.1

   1 .TH NOTMUCH-SEARCH 1 2012-08-20 "Notmuch 0.14"
   2 .SH NAME
   3 notmuch-search \- search for messages matching the given search terms
   4 .SH SYNOPSIS
   5
   6 .B notmuch search
   7 .RI  [  options "...] <" search-term ">..."
   8
   9 .SH DESCRIPTION
  10
  11 Search for messages matching the given search terms, and display as
  12 results the threads containing the matched messages.
  13
  14 The output consists of one line per thread, giving a thread ID, the
  15 date of the newest (or oldest, depending on the sort option) matched
  16 message in the thread, the number of matched messages and total
  17 messages in the thread, the names of all participants in the thread,
  18 and the subject of the newest (or oldest) message.
  19
  20 See \fBnotmuch-search-terms\fR(7)
  21 for details of the supported syntax for <search-terms>.
  22
  23 Supported options for
  24 .B search
  25 include
  26 .RS 4
  27 .TP 4
  28 .BR \-\-format= ( json | sexp | text )
  29
  30 Presents the results in either JSON, S-Expressions or plain-text (default).
  31 .RE
  32
  33 .RS 4
  34 .TP 4
  35 .BR \-\-format-version=N
  36
  37 Use the specified structured output format version.  This is intended
  38 for programs that invoke \fBnotmuch\fR(1) internally.  If omitted, the
  39 latest supported version will be used.
  40 .RE
  41
  42 .RS 4
  43 .TP 4
  44 .B \-\-output=(summary|threads|messages|files|tags)
  45
  46 .RS 4
  47 .TP 4
  48 .B summary
  49
  50 Output a summary of each thread with any message matching the search
  51 terms. The summary includes the thread ID, date, the number of
  52 messages in the thread (both the number matched and the total number),
  53 the authors of the thread and the subject.
  54 .RE
  55 .RS 4
  56 .TP 4
  57 .B threads
  58
  59 Output the thread IDs of all threads with any message matching the
  60 search terms, either one per line (\-\-format=text) or as a JSON array
  61 (\-\-format=json) or an S-Expression list (\-\-format=sexp).
  62 .RE
  63 .RS 4
  64 .TP 4
  65 .B messages
  66
  67 Output the message IDs of all messages matching the search terms,
  68 either one per line (\-\-format=text) or as a JSON array
  69 (\-\-format=json) or as an S-Expression list (\-\-format=sexp).
  70 .RE
  71 .RS 4
  72 .TP 4
  73 .B files
  74
  75 Output the filenames of all messages matching the search terms, either
  76 one per line (\-\-format=text) or as a JSON array (\-\-format=json) or
  77 as an S-Expression list (\-\-format=sexp).
  78 .RE
  79 .RS 4
  80 .TP 4
  81 .B tags
  82
  83 Output all tags that appear on any message matching the search terms,
  84 either one per line (\-\-format=text) or as a JSON array (\-\-format=json)
  85 or as an S-Expression list (\-\-format=sexp).
  86 .RE
  87 .RE
  88
  89 .RS 4
  90 .TP 4
  91 .BR \-\-sort= ( newest\-first | oldest\-first )
  92
  93 This option can be used to present results in either chronological order
  94 .RB ( oldest\-first )
  95 or reverse chronological order
  96 .RB ( newest\-first ).
  97
  98 Note: The thread order will be distinct between these two options
  99 (beyond being simply reversed). When sorting by
 100 .B oldest\-first
 101 the threads will be sorted by the oldest message in each thread, but
 102 when sorting by
 103 .B newest\-first
 104 the threads will be sorted by the newest message in each thread.
 105
 106 By default, results will be displayed in reverse chronological order,
 107 (that is, the newest results will be displayed first).
 108 .RE
 109
 110 .RS 4
 111 .TP 4
 112 .BR \-\-offset=[\-]N
 113
 114 Skip displaying the first N results. With the leading '\-', start at the Nth
 115 result from the end.
 116 .RE
 117
 118 .RS 4
 119 .TP 4
 120 .BR \-\-limit=N
 121
 122 Limit the number of displayed results to N.
 123 .RE
 124
 125 .RS 4
 126 .TP 4
 127 .BR \-\-exclude=(true|false|flag)
 128
 129 Specify whether to omit messages matching search.tag_exclude from the
 130 search results (the default) or not. The extra option
 131 .B flag
 132 only has an effect when
 133 .B --output=summary
 134 In this case all matching threads are returned but the "match count"
 135 is the number of matching non-excluded messages in the thread.
 136 .RE
 137
 138 .SH EXIT STATUS
 139
 140 This command supports the following special exit status codes
 141
 142 .TP
 143 .B 20
 144 The requested format version is too old.
 145 .TP
 146 .B 21
 147 The requested format version is too new.
 148
 149 .SH SEE ALSO
 150
 151 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
 152 \fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1),
 153 \fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
 154 \fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1),
 155 \fBnotmuch-tag\fR(1)