Notmuch Feature

Email search engine

1. Support

Since: NeoMutt 2016-03-17

Dependencies:

2. Introduction

Notmuch is an email fulltext indexing and tagging engine.

3. Using NotMuch

3.1. Folders URI

notmuch://[<path>][?<item>=<name>[& ...]]

The <path> is an absolute path to the directory where the notmuch database is found as returned by notmuch config get database.pathcommand. Note that the <path> should NOT include .notmuchdirectory name.

If the "<path>" is not defined then $nm_default_urior $folderis used, for example:

set nm_default_uri = "notmuch:///home/foo/maildir"
virtual-mailboxes "My INBOX" "notmuch://?query=tag:inbox"

3.2. Items

query=<string>

See SEARCH SYNTAX in notmuch man page. Don't forget to use andand oroperators in your queries.

Note that proper URI should not contain blank space and all badchars should be encoded, for example

tag:AAA and tag:BBB--encoding-> tag:AAA%20and%20tag:BBB

but mutt config file parser is smart enough to accept space in quoted strings. It means that you can use

notmuch:///foo?query=tag:AAA and tag:BBB

in your config files to keep things readable.

For more details about Xapian queries, see: https://xapian.org/docs/queryparser.html

limit=<number>

Restricts number of messages/threads in the result. The default limit is nm_db_limit.

type=<threads|messages>

Reads all matching messages or whole-threads. The default is 'messages' or nm_query_type.

3.3. Format String for the NotMuch Browser

Default:

%2C %?n?%4n/&     ?%4m %f

This variable allows you to customize the browser display to your personal taste. This string is similar to $index_format, but has its own set of printf(3)-like sequences:

%C current file number
%f folder name (description)
%m number of messages in the mailbox *
%n number of unread messages in the mailbox *
%N N if mailbox has new mail, blank otherwise
%>X right justify the rest of the string and pad with character X
%|X pad to the end of the line with character X
%*X soft-fill with character Xas pad

For an explanation of soft-fill, see the $index_formatdocumentation.

* = can be optionally printed if nonzero

4. Variables

Table 26.1. Notmuch Variables

Name Type Default
nm_db_limit number 0
nm_default_uri string (empty)
nm_exclude_tags string (empty)
nm_hidden_tags string unread,draft,flagged,passed,replied,attachment,signed,encrypted
nm_open_timeout number 5
nm_query_type string messages
nm_record boolean no
nm_record_tags string (empty)
nm_unread_tag string unread
vfolder_format string %6n(%6N) %f
virtual_spoolfile boolean no

5. Functions

Notmuch adds the following functions to Mutt. By default, none of them are bound to keys.

Table 26.2. Notmuch Functions

Menus Function Description
index,pager <change-vfolder> open a different virtual folder
index,pager <entire-thread> read entire thread of the current message
index,pager <modify-labels> modify (notmuch) tags
index,pager <modify-labels-then-hide> modify labels and then hide message
index,pager <sidebar-toggle-virtual> toggle between mailboxes and virtual mailboxes
index,pager <vfolder-from-query> generate virtual folder from query
index,pager <windowed-vfolder-from-query> generate virtual folder from query with window applied
index,pager <windowed-vfolder-forward> generate virtual folder by moving the query's time window forward
index,pager <windowed-vfolder-backward> generate virtual folder by moving the query's time window backward

6. Commands

virtual-mailboxes description notmuch-URI { description notmuch-URI ...}
unvirtual-mailboxes{ * | mailbox ... }
tag-transforms tag transformed-string { tag transformed-string ...}
tag-formats tag format-string { tag format-string ...}

7. Colors

Adds these to index-color patch:

Table 26.3. Index Colors

Object Pattern Highlights
index_tag yes an individual message tag, %G, uses tag name
index_tags no the transformed message tags, %g

8. Muttrc

# Example NeoMutt config file for the notmuch feature.

# --------------------------------------------------------------------------
# VARIABLES - shown with their default values
# --------------------------------------------------------------------------

# This variable specifies notmuch query limit.
set nm_db_limit = 0

# This variable specifies the default Notmuch database in format:
# notmuch://<absolute path>
set nm_default_uri = ""

# The messages tagged with these tags are excluded and not loaded
# from notmuch DB to mutt unless specified explicitly.
set nm_exclude_tags = ""

# This variable specifies private notmuch tags which should not be printed
# on screen (index, pager).
set nm_hidden_tags = "unread,draft,flagged,passed,replied,attachment,signed,encrypted"

# This option specifies timeout for Notmuch database. Default is 5 seconds.
set nm_open_timeout = 5

# This variable specifies notmuch query type, supported types: 'threads' and
# 'messages'.
set nm_query_type = messages

# Add messages stored to the mutt record (see $record in the mutt docs)
# also to notmuch DB.
set nm_record = no

# Tags that should be removed or added to the to the messages stored in the mutt record.
set nm_record_tags = ""

# This variable specifies notmuch tag which is used for unread messages.
set nm_unread_tag = unread

# This variable allows you to customize the file browser display for virtual
# folders to your personal taste.
set vfolder_format = "%6n(%6N) %f"

# When set, mutt will use the first virtual mailbox (see virtual-mailboxes)
# as a spoolfile.
set virtual_spoolfile = no

# setup time window preferences
# first setup the duration, and then the time unit of that duration
set nm_query_window_duration=2
set nm_query_window_timebase="week" # or "hour", "day", "week", "month", "year"

# --------------------------------------------------------------------------
# FUNCTIONS - shown with an example mapping
# --------------------------------------------------------------------------

# open a different virtual folder
bind index,pager X change-vfolder

# read entire thread of the current message
bind index,pager + entire-thread

# modify (notmuch) tags
bind index,pager \` modify-labels

# generate virtual folder from query
bind index,pager \eX vfolder-from-query

# generate virtual folder from query with time window
bind index,pager \\ windowed-vfolder-from-query
bind index,pager < windowed-vfolder-backward
bind index,pager > windowed-vfolder-forward

# modify labels and then hide message
# bind index,pager ??? modify-labels-then-hide

# toggle between mailboxes and virtual mailboxes
# bind index,pager ??? sidebar-toggle-virtual

# --------------------------------------------------------------------------
# COMMANDS - shown with an example
# --------------------------------------------------------------------------

# virtual-mailboxes description notmuch-URI { description notmuch-URI ...}
# virtual-mailboxes "Climbing" "notmuch://?query=climbing"

# unvirtual-mailboxes { * | mailbox ...}

# Replace some tags with icons
# tag-transforms tag transformed-string { tag transformed-string ...}
# tag-transforms "inbox"   "i"   \
#                "unread"  "u"   \
#                "replied" "↻ "  \
#                "sent"    "➥ "  \
#                "todo"    "T"   \
#                "deleted" "DEL" \
#                "invites" "CAL"

# See README.notmuch for an explanation
# tag-formats tag format-string { tag format-string ...}
# tag-formats "inbox"   "GI" \
#              "unread"  "GU" \
#              "replied" "GR" \
#              "sent"    "GS" \
#              "todo"    "Gt" \
#              "deleted" "GD" \
#              "invites" "Gi"

# set index_format='4C %S %[%y.%m.%d] %-18.18n %?GU?%GU& ? %?GR?%GR& ? %?GI?%GI& ? %s'

# --------------------------------------------------------------------------
# COLORS - some unpleasant examples are given
# --------------------------------------------------------------------------

# These symbols are added to the index-color feature:

# an individual message tag, %G, uses tag name
# this symbol uses a pattern
color index_tag red white "inbox"

# the transformed message tags, %g
# this symbol does not use a pattern
color index_tags green default

# --------------------------------------------------------------------------

# vim: syntax=muttrc

9. See Also

10. Known Bugs

None

11. Credits