Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NOTMUCH-SEARCH(1)		    notmuch		     NOTMUCH-SEARCH(1)

NAME
       notmuch-search -	search for messages matching the given search terms

SYNOPSIS
       notmuch search [option ...] <search-term> ...

DESCRIPTION
       Search for messages matching the	given search terms, and	display	as re-
       sults the threads containing the	matched	messages.

       The output consists of one line per thread, giving  a  thread  ID,  the
       date  of	 the  newest (or oldest, depending on the sort option) matched
       message in the thread, the number of matched messages  and  total  mes-
       sages  in  the thread, the names	of all participants in the thread, and
       the subject of the newest (or oldest) message.

       See notmuch-search-terms(7) for details of  the	supported  syntax  for
       <search-terms>.

       Supported options for search include

       --format=(json|sexp|text|text0)
	      Presents	the  results  in  either  JSON,	S-Expressions, newline
	      character	separated plain-text (default),	or null	character sep-
	      arated  plain-text  (compatible  with  xargs(1)  -0 option where
	      available).

       --format-version=N
	      Use the specified	structured output format version. This is  in-
	      tended  for programs that	invoke notmuch(1) internally. If omit-
	      ted, the latest supported	version	will be	used.

       --output=(summary|threads|messages|files|tags)

	      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 num-
		     ber  matched  and	the  total number), the	authors	of the
		     thread and	the subject. In	the case where a  thread  con-
		     tains  multiple files for some messages, the total	number
		     of	files is printed in parentheses	(see below for an  ex-
		     ample).

	      threads
		     Output  the  thread  IDs  of all threads with any message
		     matching the search terms,	either one  per	 line  (--for-
		     mat=text),	separated by null characters (--format=text0),
		     as	a JSON array (--format=json), or an S-Expression  list
		     (--format=sexp).

	      messages
		     Output  the  message  IDs	of  all	 messages matching the
		     search terms, either one per line (--format=text),	 sepa-
		     rated  by null characters (--format=text0), as a JSON ar-
		     ray (--format=json), or as	an S-Expression	 list  (--for-
		     mat=sexp).

	      files  Output  the filenames of all messages matching the	search
		     terms, either one per line	(--format=text), separated  by
		     null characters (--format=text0), as a JSON array (--for-
		     mat=json),	or as an S-Expression list (--format=sexp).

		     Note that each message may	have multiple filenames	 asso-
		     ciated  with  it.	All of them are	included in the	output
		     (unless limited with the --duplicate=N option). This  may
		     be	 particularly  confusing for folder: or	path: searches
		     in	a specified directory, as the messages may have	dupli-
		     cates  in other directories that are included in the out-
		     put, although these  files	 alone	would  not  match  the
		     search.

	      tags   Output  all  tags that appear on any message matching the
		     search terms, either one per line (--format=text),	 sepa-
		     rated  by null characters (--format=text0), as a JSON ar-
		     ray (--format=json), or as	an S-Expression	 list  (--for-
		     mat=sexp).

       --sort=(newest-first|oldest-first)
	      This option can be used to present results in either chronologi-
	      cal order	(oldest-first) or reverse  chronological  order	 (new-
	      est-first).

	      Note:  The  thread  order	will be	distinct between these two op-
	      tions (beyond being  simply  reversed).  When  sorting  by  old-
	      est-first	 the  threads  will be sorted by the oldest message in
	      each thread, but when sorting by newest-first the	 threads  will
	      be sorted	by the newest message in each thread.

	      By  default,  results will be displayed in reverse chronological
	      order, (that is, the newest results will be displayed first).

       --offset=[-]N
	      Skip displaying the first	N results. With	the leading '-', start
	      at the Nth result	from the end.

       --limit=N
	      Limit the	number of displayed results to N.

       --exclude=(true|false|all|flag)
	      A	message	is called "excluded" if	it matches at least one	tag in
	      search.exclude_tags that	does  not  appear  explicitly  in  the
	      search  terms.  This  option  specifies whether to omit excluded
	      messages in the search process.

	      true (default)
		     Prevent excluded messages from matching the search	terms.

	      all    Additionally prevent excluded messages from appearing  in
		     displayed	results,  in effect behaving as	though the ex-
		     cluded messages do	not exist.

	      false  Allow excluded messages to	match search terms and	appear
		     in	 displayed results. Excluded messages are still	marked
		     in	the relevant outputs.

	      flag   Only has an effect	when --output=summary. The  output  is
		     almost  identical	to false, but the "match count"	is the
		     number of matching	non-excluded messages in  the  thread,
		     rather than the number of matching	messages.

       --duplicate=N
	      For --output=files, output the Nth filename associated with each
	      message matching the query (N is 1-based). If N is greater  than
	      the  number  of  files  associated with the message, don't print
	      anything.

	      For --output=messages,  only  output  message  IDs  of  messages
	      matching the search terms	that have at least N filenames associ-
	      ated with	them.

	      Note that	this option is orthogonal with the folder: search pre-
	      fix. The prefix matches messages based on	filenames. This	option
	      filters filenames	of the matching	messages.

EXAMPLE
       The following shows an example of the summary output format,  with  one
       message having multiple filenames.

	  % notmuch search date:today..	and tag:bad-news
	  thread:0000000000063c10 Today	[1/1] Some Persun; To the bone (bad-news inbox unread)
	  thread:0000000000063c25 Today	[1/1(2)] Ann Other; Bears (bad-news inbox unread)
	  thread:0000000000063c00 Today	[1/1] A	Thurd; Bites, stings, sad feelings (bad-news unread)

EXIT STATUS
       This command supports the following special exit	status codes

       20     The requested format version is too old.

       21     The requested format version is too new.

SEE ALSO
       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not-
       much-hooks(5),  notmuch-insert(1),  notmuch-new(1),   notmuch-reply(1),
       notmuch-restore(1),   notmuch-search-terms(7),	notmuch-show(1),  not-
       much-tag(1) notmuch-address(1)

AUTHOR
       Carl Worth and many others

COPYRIGHT
       2009-2020, Carl Worth and many others

0.31.3				 Feb 28, 2021		     NOTMUCH-SEARCH(1)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | EXIT STATUS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=notmuch-search&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help