notmuch support for mutt
------------------------
* notmuch is e-mail fulltext indexing and tagging engine; see
http://notmuchmail.org/ for more information.
* home page (wiki) and git:
https://github.com/karelzak/mutt-kz
Note that the master branch is rebased to be up to date with mutt upstream. Use
stable/v<version> branches for downstream packaging.
* mailing list:
https://admin.fedoraproject.org/mailman/listinfo/mutt-kz
* requirements:
notmuch >= 0.9
* compile:
$ git clone git://github.com/karelzak/mutt-kz.git
$ cd mutt-kz
$ ./prepare
$ ./configure --enable-notmuch [--enable-debug]
$ make
* 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"
Items:
query=<string>
See SEARCH SYNTAX in notmuch man page. Don't forget to use "and" and
"or" operators 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 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.
See http://xapian.org/docs/queryparser.html for more details about Xapian
queries.
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.
* commands:
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
- default key: X
vfolder-from-query:
- generate new virtual folder from notmuch search query
- default key: <Esc>X
- note: TAB completion of 'tag:' names is available
modify-labels:
- add or remove notmuch tags; [+]<tag> to add, -<tag> to remove
- default key: `
- note: TAB completion of tag names is available
- example: "+AAA +BBB -CCC"
modify-labels-then-hide:
- same as <modify-labels> but message is marked by <quasi-delete>
- not mapped to any key
- note: TAB completion of tag names is available
- example (add "archive" notmuch tag and remove message from screen):
macro index A "<modify-labels-then-hide>+archive -inbox\n<sync-mailbox>"
macro index I "<modify-labels-then-hide>-inbox\n<sync-mailbox>"
quasi-delete:
- delete message from mutt (usually after <sync-mailbox> function), but
don't touch message on disk
entire-thread:
- add to the current list of the messages all messages that belongs to the same thread
as the current message. This command is useful when you have a new email in your INBOX
and you want to see the rest of the archived thread.
- default key: +
* Pattern modifiers:
Many of Mutt's commands allow you to specify a pattern to match (limit,
tag-pattern, delete-pattern, color, etc.). The following notmuch specific
mutt pattern modifiers are available:
- '~Y EXPR': Messages which contain EXPR in the list of labels.
Example:
# Color red all messages labeled as 'spam'.
color index red default "~Y '\W?spam\W?'"
* muttrc:
Note that you can use notmuch specific mutt config file, see -F <config> in
mutt docs.
virtual-mailboxes <description> <uri> [ ...]
This command specifies one or more virtual folder. The folders are
accessible by command 'X'. It's possible to use the virtual mailbox
description as a sort key (e.g set sort_sidebar=desc)
example:
virtual-mailboxes "Linux Kernel" "notmuch:///whereis/db?query=tag:lkml&limit=1000" \
"Filesystems" "notmuch:///whereis/db?query=tag:fs" \
"Music" "notmuch:///another/db?query=tag:hard and tag:heavy"
The folder description is used for status line, folders browser, sidebar
and <change-vfolder> command (this command also accepts vfolder URI). The
folder-hook regex uses the URI.
virtual_spoolfile = <boolean>
When set, mutt will use the first virtual mailbox (see virtual-mailboxes)
as a spoolfile.
When set together with sidebar, mutt will use list of virtual folders in
the sidebar. It's possible to toggle between virtual and normal folders by
sidebar-toggle command.
tag-transforms <tag> <transform> [ ...]
This command specifies text transforms to be shown instead of the actual
tag names with '%g' in the index and pager formats. Note that Unicode
symbols can be used for transforms.
example:
tag-transforms "inbox" "i" \
"unread" "u" \
"replied" "↻ " \
"sent" "➥ " \
"todo" "T" \
"deleted" "DEL" \
"invites" "CAL"
tag-formats <tag> <format sequence> [ ...]
Specify index formatting sequences for individual tags for direct
placement in the $index_format. The formats must start with 'G' and
the entire sequence is case sensitive.
example:
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.
nm_record = <boolean>
Add messages stored to the mutt record (see $record in the mutt docs)
also to notmuch DB. If you reply to an email then the new email inherits
tags from the original email.
nm_record_tags = <comma delimited list>
Tags that should be removed or added to the to the messages stored in the mutt record.
example:
set record = "~/sent-mails"
set nm_record = yes
set nm_record_tags = "-inbox,archive,me"
nm_open_timeout = <seconds>
This option specifies timeout for Notmuch database. Default is 5 seconds.
nm_default_uri = <uri>
This variable specifies the default Notmuch database in format
notmuch://<absolute path>, the URI is used for notmuch queries (ESC+X) when the
current folder is not based on notmuch. If the default URI is not specified
then mutt will try to use $folder variable (see mutt manual for more details).
nm_hidden_tags = <comma delimited list>
This variable specifies private notmuch tags which should not be printed
on screen (index, pager).
Default is "unread,draft,flagged,passed,replied,attachment".
nm_exclude_tags = <comma delimited list>
The messages tagged with these tags are excluded and not loaded
from notmuch DB to mutt unless specified explicitly.
Not set by default.
nm_unread_tag = <name>
This variable specifies notmuch tag which is used for unread messages. The
variable is used to count unread messages in DB only. All other mutt
commands use standard (e.g. maildir) flags.
Default is "unread".
nm_db_limit = <num>
This variable specifies notmuch query limit.
Default is unlimited.
nm_query_type = <threads|messages>
This variable specifies notmuch query type, supported types: 'threads' and
'messages'.
Default is 'messages'.
vfolder_format = <string>
This variable allows you to customize the file browser display for virtual
folders to your personal taste. This string is similar to $index_format,
but has its own set of printf(3)-like sequences:
%f folder name (description)
%n number of all messages
%N number of new messages
%>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
Default is "%6n(%6N) %f ".
index_format and pager_format
%g notmuch tags (labels)
%Gx specific notmuch tag defined by tag-formats (see above)
for example:
tag-formats "inbox" "GI"
set index_format = "%4C %Z %?GI?%GI? ? %[%d/%b] %-16.15F %s %> %?g?(%g)?"
set pager_format = "-%Z- %C/%m: %-20.20n %s%* -- %?g?(%g)? - (%P)"
* .muttrc example:
set record="~/Mail/Maildir/sent-mail"
set nm_record = yes
set nm_record_tags ="-inbox me archive"
set nm_default_uri="notmuch:///home/kzak/Mail/Maildir"
set virtual_spoolfile = yes
set sort_browser = unsorted
# normal folders
set mbox_type=Maildir
set folder="~/Mail/Maildir"
mailboxes =rh =fedora =misc
set sidebar_width = 35
set sidebar_visible = yes
set sidebar_sort_method = unsorted
set sidebar_divider_char = │
color sidebar_new yellow default
color progress default magenta
bind index <left> sidebar-prev
bind index <right> sidebar-next
bind index <space> sidebar-open
bind index <Esc>S sidebar-toggle-virtual
set index_format="%4C %Z %?GI?%GI& ? %[%d/%b] %-16.15F %?M?(%3M)& ? %s %> %?g?%g?"
# virtual folders
virtual-mailboxes \
"INBOX" "notmuch://?query=tag:inbox and NOT tag:archive" \
"Util-linux" "notmuch://?query=tag:ul and NOT tag:archive" \
"Bugs" "notmuch://?query=tag:bug NOT tag:archive" \
"RH" "notmuch://?query=tag:rh and NOT tag:archive" \
"Fedora" "notmuch://?query=tag:fed and NOT tag:archive" \
"Linux" "notmuch://?query=tag:lk and NOT tag:archive" \
"NFS" "notmuch://?query=tag:nfs and NOT tag:archive" \
"Filesystems" "notmuch://?query=tag:fs and NOT tag:archive" \
"Security" "notmuch://?query=tag:sec" \
"Partitioning" "notmuch://?query=tag:part" \
"GNU" "notmuch://?query=tag:gnu" \
"udev" "notmuch://?query=tag:udev" \
"initrd" "notmuch://?query=tag:initrd" \
"Linux CZ" "notmuch://?query=tag:cz" \
"Notmuch" "notmuch://?query=tag:nm" \
"Procps" "notmuch://?query=tag:proc" \
\
" Util-linux [archive]" "notmuch://?query=tag:ul and tag:archive" \
" Bugs [archive]" "notmuch://?query=tag:bug and tag:archive" \
" RH [archive]" "notmuch://?query=tag:rh and tag:archive" \
" Fedora [archive]" "notmuch://?query=tag:fed and tag:archive" \
" Linux [archive]" "notmuch://?query=tag:lk and tag:archive" \
" Filesystems [archive]" "notmuch://?query=tag:fs and tag:archive" \
# move message to archive
macro index A "<modify-labels-then-hide>+archive -inbox\n<sync-mailbox>"
# remove message from inbox
macro index I "<modify-labels-then-hide>-inbox\n<sync-mailbox>"
# mark emails for git-am
# (e.g. "git am -i -3 $(notmuch search --output=files tag:PATCH)"
#
macro index P "<modify-labels>PATCH\n"
macro index <Esc>P "<modify-labels>-PATCH\n"
* .procmailrc example:
NOINBOX="-r inbox"
### Add 'kw' (keyword) tag to all interesting e-mails and make the emails
### visible in inbox.
:0
* ^Subject:.*(mount|umount|libmount|losetup|util-linux|blkid|hwclock|mkswap|fdisk|parted|partition|gpt|topology)
{
TAGS="-t kw"
NOINBOX=""
}
### Deliver emails to maildirs by notmuch-deliver
### from notmuch contrib/
###
### notmuch-deliver -t <tags> [-t ...] <maildir>
:0:notmuch.lock
* ^List-Id:.*linux.linux.cz
| notmuch-deliver $NOINBOX -t cz $TAGS linux.cz
:0:notmuch.lock
* ^X-Mailing-List:.*util-linux@vger.kernel.org
| notmuch-deliver -t ul $TAGS util-linux
:0:notmuch.lock
* ^List-Id:.*parted-devel.lists.alioth.debian.org
| notmuch-deliver $NOINBOX -t part $TAGS parted
### [...cut to make the example short...] ###
### All unmatched mails
:0:notmuch.lock
* ^From
| notmuch-deliver $TAGS misc
### fallback if notmuch does not work
:0:
* ^From
Mail/Maildir/misc/
* another example:
http://notmuchmail.org/mutttips/