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

More variables about tags configuration can be found in Custom backend Tags Feature

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

More functions about tags can be found in Custom backend Tags Feature

6. Commands

virtual-mailboxes description notmuch-URI { description notmuch-URI ...}
unvirtual-mailboxes{ * | mailbox ... }

More commands about tags can be found in Custom backend Tags Feature

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 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
# 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
# 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 ...}
#
# --------------------------------------------------------------------------
# vim: syntax=neomuttrc

9. See Also

10. Known Bugs

None

11. Credits

Search by Algolia