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.path command. Note that the <path> should NOT include .notmuch directory name.

If the "<path>" is not defined then $nm_default_uri or $folder is 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 operators ( and/ or) in your queries.

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

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

but NeoMutt 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 X as pad

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

* = 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 NeoMutt. By default, none of them are bound to keys.

Table 26.2. Notmuch Functions

Menus Function Description
index,pager <change-vfolder> switch to another virtual folder, a new folder maybe be specified by vfolder description (see virtual-mailboxes) or URI. the default is next vfolder with unread messages
index,pager <entire-thread> read entire thread of the current message
index,pager <modify-labels> add, remove, or toggle notmuch tags; [+]<tag> to add, -<tag> to remove, !<tag> to toggle(notmuch) tags. Note: Tab completion of tag names is available
index,pager <modify-labels-then-hide> add, remove, or toggle notmuch tags; [+]<tag> to add, -<tag> to remove, !<tag> to togglelabels and then hide or unhide the message by changing the "quasi-deleted" to match if it would be shown when requerying. Normal redisplay rules apply here, so the user must call <sync-mailbox> for the changes to be displayed. Note: Tab completion of tag names is available.
index,pager <sidebar-toggle-virtual> toggle between mailboxes and virtual mailboxes
index,pager <vfolder-from-query> generate virtual folder from notmuch search query. Note: TAB completion of 'tag:' names is available.
index,pager <vfolder-window-forward> generate virtual folder by moving the query's time window forward
index,pager <vfolder-window-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 feature:

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

# 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 NeoMutt 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 NeoMutt record (see $record in the NeoMutt docs) also to notmuch DB. If you reply to an email then the new email inherits tags from the original email.

set nm_record = no
# Tags that should be removed or added to the to the messages stored in the NeoMutt record.

example:
set record = "~/sent-mails"
set nm_record = yes
set nm_record_tags = "-inbox,archive,me"

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.
# %C   current folder 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 ``X'' as pad

set vfolder_format = "%6n(%6N) %f"
# When set, NeoMutt 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
# when set to 0 (the default) the search window feature is disabled
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
# modify (notmuch) tag non-interactively.
bind index,pager tt "<modify-labels>!todo\n" "Toggle the 'todo' tag"
# generate virtual folder from query
bind index,pager \eX vfolder-from-query
# generate virtual folder from query with time window
bind index,pager < vfolder-window-backward
bind index,pager > vfolder-window-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"

# The formats must start with 'G' and the entire sequence is case sensitive.
# tag-formats tag format-string { tag format-string ...}
# tag-formats "inbox"   "GI" \
#              "unread"  "GU" \
#              "replied" "GR" \
#              "sent"    "GS" \
#              "todo"    "Gt" \
#              "deleted" "GD" \
#              "invites" "Gi"

# Now instead of using '%g' in your $index_format, which lists all tags
# in a non-deterministic order, you can something like the following which puts
# a transformed tag name in a specific spot on the index line:
# set index_format='%4C %S %[%y.%m.%d] %-18.18n %?GU?%GU& ? %?GR?%GR& ? %?GI?%GI& ? %s'

# The %G formatting sequence may display all tags including tags hidden by
# nm_hidden_tags.
#
# --------------------------------------------------------------------------
# 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=neomuttrc

9. See Also

10. Known Bugs

None

11. Credits