1NOTMUCH-SEARCH(1)                   notmuch                  NOTMUCH-SEARCH(1)
2
3
4

NAME

6       notmuch-search - search for messages matching the given search terms
7

SYNOPSIS

9       notmuch search [option ...] <search-term> ...
10

DESCRIPTION

12       Search for messages matching the given search terms, and display as re‐
13       sults the threads containing the matched messages.
14
15       The output consists of one line per thread, giving  a  thread  ID,  the
16       date  of  the  newest (or oldest, depending on the sort option) matched
17       message in the thread, the number of matched messages  and  total  mes‐
18       sages  in  the thread, the names of all participants in the thread, and
19       the subject of the newest (or oldest) message.
20
21       See notmuch-search-terms  for  details  of  the  supported  syntax  for
22       <search-terms>.
23
24       Supported options for search include
25
26       --format=(json|sexp|text|text0)
27              Presents  the  results  in  either  JSON, S-Expressions, newline
28              character separated plain-text (default), or null character sep‐
29              arated  plain-text  (compatible  with  xargs(1)  -0 option where
30              available).
31
32       --format-version=N
33              Use the specified structured output format version. This is  in‐
34              tended  for programs that invoke notmuch internally. If omitted,
35              the latest supported version will be used.
36
37       --output=(summary|threads|messages|files|tags)
38
39              summary (default)
40                     Output a summary of each thread with any message matching
41                     the  search  terms.  The  summary includes the thread ID,
42                     date, the number of messages in the thread (both the num‐
43                     ber  matched  and  the  total number), the authors of the
44                     thread and the subject. In the case where a  thread  con‐
45                     tains  multiple files for some messages, the total number
46                     of files is printed in parentheses (see below for an  ex‐
47                     ample).
48
49              threads
50                     Output  the  thread  IDs  of all threads with any message
51                     matching the search terms, either one  per  line  (--for‐
52                     mat=text), separated by null characters (--format=text0),
53                     as a JSON array (--format=json), or an S-Expression  list
54                     (--format=sexp).
55
56              messages
57                     Output  the  message  IDs  of  all  messages matching the
58                     search terms, either one per line (--format=text),  sepa‐
59                     rated  by null characters (--format=text0), as a JSON ar‐
60                     ray (--format=json), or as an S-Expression  list  (--for‐
61                     mat=sexp).
62
63              files  Output  the filenames of all messages matching the search
64                     terms, either one per line (--format=text), separated  by
65                     null characters (--format=text0), as a JSON array (--for‐
66                     mat=json), or as an S-Expression list (--format=sexp).
67
68                     Note that each message may have multiple filenames  asso‐
69                     ciated  with  it.  All of them are included in the output
70                     (unless limited with the --duplicate=N option). This  may
71                     be  particularly  confusing for folder: or path: searches
72                     in a specified directory, as the messages may have dupli‐
73                     cates  in other directories that are included in the out‐
74                     put, although these  files  alone  would  not  match  the
75                     search.
76
77              tags   Output  all  tags that appear on any message matching the
78                     search terms, either one per line (--format=text),  sepa‐
79                     rated  by null characters (--format=text0), as a JSON ar‐
80                     ray (--format=json), or as an S-Expression  list  (--for‐
81                     mat=sexp).
82
83       --sort=(newest-first|oldest-first)
84              This option can be used to present results in either chronologi‐
85              cal order (oldest-first) or reverse  chronological  order  (new‐
86              est-first).
87
88              Note:  The  thread  order will be distinct between these two op‐
89              tions (beyond being  simply  reversed).  When  sorting  by  old‐
90              est-first  the  threads  will be sorted by the oldest message in
91              each thread, but when sorting by newest-first the  threads  will
92              be sorted by the newest message in each thread.
93
94              By  default,  results will be displayed in reverse chronological
95              order, (that is, the newest results will be displayed first).
96
97       --offset=[-]N
98              Skip displaying the first N results. With the leading '-', start
99              at the Nth result from the end.
100
101       --limit=N
102              Limit the number of displayed results to N.
103
104       --exclude=(true|false|all|flag)
105              A message is called "excluded" if it matches at least one tag in
106              search.exclude_tags that  does  not  appear  explicitly  in  the
107              search  terms.  This  option  specifies whether to omit excluded
108              messages in the search process.
109
110              true (default)
111                     Prevent excluded messages from matching the search terms.
112
113              all    Additionally prevent excluded messages from appearing  in
114                     displayed  results,  in effect behaving as though the ex‐
115                     cluded messages do not exist.
116
117              false  Allow excluded messages to match search terms and  appear
118                     in  displayed results. Excluded messages are still marked
119                     in the relevant outputs.
120
121              flag   Only has an effect when --output=summary. The  output  is
122                     almost  identical  to false, but the "match count" is the
123                     number of matching non-excluded messages in  the  thread,
124                     rather than the number of matching messages.
125
126       --duplicate=N
127              For --output=files, output the Nth filename associated with each
128              message matching the query (N is 1-based). If N is greater  than
129              the  number  of  files  associated with the message, don't print
130              anything.
131
132              For --output=messages,  only  output  message  IDs  of  messages
133              matching the search terms that have at least N filenames associ‐
134              ated with them.
135
136              Note that this option is orthogonal with the folder: search pre‐
137              fix. The prefix matches messages based on filenames. This option
138              filters filenames of the matching messages.
139

EXAMPLE

141       The following shows an example of the summary output format,  with  one
142       message having multiple filenames.
143
144          % notmuch search date:today.. and tag:bad-news
145          thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
146          thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
147          thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)
148

EXIT STATUS

150       This command supports the following special exit status codes
151
152       20     The requested format version is too old.
153
154       21     The requested format version is too new.
155

SEE ALSO

157       notmuch,  notmuch-address  notmuch-config, notmuch-count, notmuch-dump,
158       notmuch-hooks,     notmuch-insert,     notmuch-new,      notmuch-reply,
159       notmuch-restore, notmuch-search-terms, notmuch-show, notmuch-tag
160

AUTHOR

162       Carl Worth and many others
163
165       2009-2023, Carl Worth and many others
166
167
168
169
1700.38                             Sep 12, 2023                NOTMUCH-SEARCH(1)
Impressum