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

FreeBSD Manual Pages


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

       notmuch-show - show messages matching the given search terms

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

       Shows all messages matching the search terms.

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

       The messages will be grouped and	sorted based  on  the  threading  (all
       replies to a particular message will appear immediately after that mes-
       sage 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).

       Supported options for show include

	      If true, notmuch show outputs all	messages in the	thread of  any
	      message matching the search terms; if false, it outputs only the
	      matching messages. For --format=json and --format=sexp this  de-
	      faults to	true. For other	formats, this defaults to false.


	      text (default for	messages)
		     The  default  plain-text format has all text-content MIME
		     parts decoded. Various components in  the	output,	 (mes-
		     sage,  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. For
		     a multipart MIME message, these parts will	be nested.

	      json   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	multi-
		     part MIME messages	is reflected in	nested JSON output. By
		     default JSON output includes all messages in  a  matching
		     thread;  that  is,	 by  default, --format=json sets --en-
		     tire-thread. The caller can  disable  this	 behaviour  by
		     setting --entire-thread=false.  The JSON output is	always
		     encoded as	UTF-8 and any message content included in  the
		     output will be charset-converted to UTF-8.

	      sexp   The  output  is formatted as the Lisp s-expression	(sexp)
		     equivalent	of the JSON format above. Objects are  format-
		     ted  as  property	lists whose keys are keywords (symbols
		     preceded by a colon). True	is formatted  as  t  and  both
		     false  and	 null  are  formatted as nil. As for JSON, the
		     s-expression output is always encoded as UTF-8.

	      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:

	      raw (default if --part is	given)
		     Write  the	 raw bytes of the given	MIME part of a message
		     to	standard out. For this format, it is an	error to spec-
		     ify a query that matches more than	one message.

		     If	 the  specified	 part is a leaf	part, this outputs the
		     body of the part after performing content transfer	decod-
		     ing  (but	no  charset  conversion). This is suitable for
		     saving attachments, for example.

		     For a multipart or	message	part, the output includes  the
		     part  headers  as	well  as the body (including all child
		     parts). No	decoding is performed  because	multipart  and
		     message  parts  cannot  have non-trivial content transfer
		     encoding. Consumers of this may need  to  implement  MIME
		     decoding and similar functions.

	      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  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',	'sexp' or 'text'  output  for-

	      Note that	even a message with no MIME structure or a single body
	      part still has two MIME parts:  part  0  is  the	whole  message
	      (headers and body) and part 1 is just the	body.

	      Compute and report the validity of any MIME cryptographic	signa-
	      tures found in the selected  content  (e.g.,  "multipart/signed"
	      parts). Status of	the signature will be reported (currently only
	      supported	with --format=json and --format=sexp), and the	multi-
	      part/signed part will be replaced	by the signed data.

	      If  true,	decrypt	any MIME encrypted parts found in the selected
	      content (e.g., "multipart/encrypted" parts). Status of  the  de-
	      cryption	will be	reported (currently only supported with	--for-
	      mat=json and --format=sexp) and  on  successful  decryption  the
	      multipart/encrypted  part	will be	replaced by the	decrypted con-

	      stash behaves like true, but upon	successful decryption it  will
	      also  stash the message's	session	key in the database, and index
	      the cleartext of the message, enabling automatic	decryption  in
	      the future.

	      If  auto,	 and  a	 session key is	already	known for the message,
	      then it will be decrypted, but notmuch will not  try  to	access
	      the user's keys.

	      Use false	to avoid even automatic	decryption.

	      Non-automatic  decryption	 (stash	 or  true, in the absence of a
	      stashed session key) expects a functioning gpg-agent(1) to  pro-
	      vide  any	 needed	 credentials. Without one, the decryption will

	      Note: setting either true	or stash here implies --verify.

	      Here is a	table that summarizes each of these policies:

		       |	      |	false |	auto | true | stash |
		       |Show  cleart- |	      |	X    | X    | X	    |
		       |ext  if	 ses- |	      |	     |	    |	    |
		       |sion  key  is |	      |	     |	    |	    |
		       |already	known |	      |	     |	    |	    |
		       |Use    secret |	      |	     | X    | X	    |
		       |keys to	 show |	      |	     |	    |	    |
		       |cleartext     |	      |	     |	    |	    |
		       |Stash	  any |	      |	     |	    | X	    |
		       |newly  recov- |	      |	     |	    |	    |
		       |ered  session |	      |	     |	    |	    |
		       |keys,	rein- |	      |	     |	    |	    |
		       |dexing	 mes- |	      |	     |	    |	    |
		       |sage if	found |	      |	     |	    |	    |

	      Note: --decrypt=stash requires write  access  to	the  database.
	      Otherwise, notmuch show operates entirely	in read-only mode.

	      Default: auto

	      Specify	whether	 to  omit  threads  only  matching  search.ex-
	      clude_tags from the search results (the default) or not. In  ei-
	      ther  case  the excluded message will be marked with the exclude
	      flag (except when	output=mbox when there is nowhere to  put  the

	      If  --entire-thread  is  specified then complete threads are re-
	      turned regardless	(with the excluded flag	being set when	appro-
	      priate)  but  threads that only match in an excluded message are
	      not returned when	--exclude=true.

	      The default is --exclude=true.

	      If true (the default) notmuch show includes the  bodies  of  the
	      messages	 in   the   output;  if	 false,	 bodies	 are  omitted.
	      --body=false is only implemented for the	text,  json  and  sexp
	      formats and it is	incompatible with --part > 0.

	      This is useful if	the caller only	needs the headers as body-less
	      output is	much faster and	substantially smaller.

	      Include "text/html" parts	as part	of the output (currently  only
	      supported	 with --format=text, --format=json and --format=sexp).
	      By default, unless --part=N is used to select a specific part or
	      --include-html is	used to	include	all "text/html"	parts, no part
	      with content type	"text/html" is included	in the output.

       A common	use of notmuch show is to display a  single  thread  of	 email
       messages. For this, use a search	term of	"thread:<thread-id>" as	can be
       seen in the first column	of output from the notmuch search command.

       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.

       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(1),	notmuch-search-terms(7),  not-

       Carl Worth and many others

       2009-2020, Carl Worth and many others

0.31.3				 Feb 28, 2021		       NOTMUCH-SHOW(1)


Want to link to this manual page? Use this URL:

home | help