README.notmuch

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/