Disambiguate Debian notmuch package and notmuch for emacs package.
[notmuch-wiki] / notmuch-emacs.mdwn
1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Notmuch Emacs Interface
3
4 One of the more popular Notmuch message reading clients is **notmuch.el**, or
5 `notmuch-emacs`, an [Emacs](https://www.gnu.org/software/emacs/) major mode for
6 interacting with Notmuch. It is included in the Notmuch package (`notmuch-emacs`
7 in Debian). The [[screenshots|screenshots]] give a good overview of the mode.
8
9 This page is a basic guide for setting up and using Notmuch with Emacs. See also
10 the [[tips and tricks page|emacstips]] for more advanced details.
11
12 [[!toc levels=2]]
13
14 ## Prerequisites
15
16 The Notmuch Emacs interface uses the Notmuch [[command line interface|manpages]]
17 to interact with the Notmuch database and your mail store. Please make sure
18 you've [[set up Notmuch|getting-started]] first.
19
20 ## Installation
21
22 Due to the dependency on the command line interface, the Notmuch Emacs interface
23 version must be compatible with the Notmuch version. On Linux, the easiest way
24 to ensure this is to use the package(s) in your distribution's package
25 repository.
26
27 If you've installed Notmuch from a [git
28 checkout](https://git.notmuchmail.org/git/notmuch) or a [source
29 release](https://notmuchmail.org/releases/), Notmuch Emacs is included by
30 default.
31
32 It is **not** recommended to install Notmuch Emacs from the Emacs Lisp Package
33 Archive (ELPA), as the version there is likely not in sync with the command line
34 interface.
35
36 ## Setup
37
38 First, you need to tell Emacs about Notmuch. Add this to your `.emacs` rc file:
39
40         (autoload 'notmuch "notmuch" "notmuch mail" t)
41
42 or if you always want to load Notmuch when you start Emacs:
43
44         (require 'notmuch)
45
46 To start Notmuch Emacs, either run `emacs -f notmuch`, or execute the command
47 `M-x notmuch RET` from within a running Emacs. This will bring you to the
48 Notmuch Hello view.
49
50 ## Customization
51
52 Notmuch Emacs uses the Emacs customization interface extensively for
53 configuration. Execute `M-x customize-group RET notmuch RET` to get to the
54 Notmuch main customization group.
55
56 ### <span id="notmuch_init_file"> Notmuch Emacs configuration file </span>
57
58 After Notmuch is loaded `notmuch-init-file` (typically
59  `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists
60 it is loaded. Most Emacs lisp based configuration not suitable via
61 customization can be put there instead of `~/.emacs`.
62
63 ## Navigating & reading mails
64
65 When first starting Notmuch in Emacs, you will be presented with the
66 Notmuch "hello" page.  If it exits with an error after writing
67 "Welcome to notmuch. You have" you need to do the basic Notmuch setup
68 first (see above).
69 From here you can do searches, see lists of recent
70 searches, saved searches, message tags, help information, etc.
71
72 Executing a search will open a new buffer in `notmuch-search-mode`
73 displaying the search results.  Each line in the search results
74 represents a message thread.  Hitting the '?' key will show help for
75 this mode.
76
77 In general, the 'q' will kill the current Notmuch buffer and return
78 you to the previous buffer (sort of like a 'pop').
79
80 In search mode, navigating to a thread and hitting return will then
81 open a new buffer in `notmuch-show-mode`, which will show the actual
82 message contents of the thread.
83
84 ## Sending mail
85
86 In any Notmuch mode, you can start a new message by hitting the 'm'
87 key.  To reply to a message or thread, just hit the 'r' key.
88
89 When composing new messages, you will be entered in Emacs's
90 `message-mode`, which is a powerful mode for composing and sending
91 messages.  When in message mode, you can type `C-c ?` for help.
92
93 If you would like to use address autocompletion when composing
94 messages, see [address completion](/emacstips#index13h2).
95
96 When you are ready to send a message, type `C-c C-c`. By default
97 message mode will use your sendmail command to send mail, so make sure
98 that works. One annoying standard configuration of message mode is
99 that it will hide the sent mail in your Emacs frame stack, but it will
100 not close it. If you type several mails in an Emacs session they will
101 accumulate and make switching between buffers more annoying. You can
102 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
103 in your `.emacs` file
104 (or doing `M-x customize-variable<RET>message-kill-buffer-on-exit<RET>`)
105 which will really close the mail window after sending it.
106
107 ## Attaching files
108
109 Using the `M-x mml-attach-file` command, you can attach any file to be
110 sent with your mail. By default this command is bound to the menu item
111 *Attachments--Attach File* with the key binding `C-c C-a`. The
112 variable `mml-dnd-attach-options` (`M-x
113 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
114 allow the prompting for various attachment options (such as
115 inline/attachment) if you want to do that.
116
117 For those who prefer a more graphical interface, you can also simply
118 drag and drop files from a file manager into a mail composition window
119 to have them attached. In Ubuntu this works without any modifications
120 if files are dragged from the file manager.
121
122 And for those who prefer working from command line, the following
123 script opens new Emacs window with empty message and attaches files
124 mentioned as script arguments. (Note: The script expects that you have
125 `(server-start)` in your `.emacs` file.)
126
127         #!/bin/sh
128         attach_cmds=""
129         while [ $# -gt 0 ]; do
130             fullpath=$(readlink --canonicalize "$1")
131             attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
132             shift
133         done
134         emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
135
136 Also, if you're the kind of person who forgets to add attachments,
137 there's a cure for that disease. See [Never forget
138 attachments](/emacstips#index27h2) for all the details.