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

FreeBSD Manual Pages

  
 
  

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

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

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

DESCRIPTION
       Shows all messages matching the search terms.

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

       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

       --entire-thread=(true|false)
	      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.

       --format=(text|json|sexp|mbox|raw)

	      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:
			http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html

	      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.

       --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.

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

	      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.

       --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).

	      Only  threads  as	 a  whole are reordered.  Ordering of messages
	      within each thread will not be affected by this flag, since that
	      order is always determined by the	thread's replies.

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

       --verify
	      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.

       --decrypt=(false|auto|true|stash)
	      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-
	      tent.

	      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
	      fail.

	      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

       --exclude=(true|false)
	      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
	      flag).

	      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.

       --body=(true|false)
	      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-html
	      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(1) command.

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

AUTHOR
       Carl Worth and many others

COPYRIGHT
       2009-2021, Carl Worth and many others

0.33				 Nov 04, 2021		       NOTMUCH-SHOW(1)

NAME | SYNOPSIS | DESCRIPTION | 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-show&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help