X-Git-Url: https://git.cworth.org/git?p=notmuch-wiki;a=blobdiff_plain;f=notmuch-emacs.mdwn;h=bc42d1af8ffc8b167de3f379e32b3627b3b890df;hp=78fbe42e504a52d6190d0934426d61bce08f5f0a;hb=HEAD;hpb=d8ec2b443ec10acda34c096650317947e2de65c1 diff --git a/notmuch-emacs.mdwn b/notmuch-emacs.mdwn index 78fbe42..f5c8f01 100644 --- a/notmuch-emacs.mdwn +++ b/notmuch-emacs.mdwn @@ -2,46 +2,72 @@ # Notmuch Emacs Interface One of the more popular Notmuch message reading clients is **notmuch.el**, or -`notmuch-emacs`, an [emacs](http://www.gnu.org/software/emacs/) major mode for -interacting with Notmuch. It is included in the Notmuch package (`notmuch-emacs` -in Debian). +`notmuch-mode`, an [Emacs](https://www.gnu.org/software/emacs/) major mode for +interacting with Notmuch. It is included in the Notmuch package (as +`elpa-notmuch` within the `notmuch` package in current Debian or as +`notmuch-emacs` in Debian 10 or prior). The [[screenshots|screenshots]] give a +good overview of the mode. This page is a basic guide for setting up and using Notmuch with Emacs. See also the [[tips and tricks page|emacstips]] for more advanced details. [[!toc levels=2]] -## Setup +## Prerequisites + +The Notmuch Emacs interface uses the Notmuch [command line +interface](https://notmuchmail.org/doc/latest/man1/notmuch.html) to +interact with the Notmuch database and your mail store. Please make +sure you've [[set up Notmuch|getting-started]] first. + +## Installation -Have a look at the [[Howto|howto]] for prerequisites. Be sure you have done the -general setup using the notmuch cli command! +Due to the dependency on the command line interface, the Notmuch Emacs interface +version must be compatible with the Notmuch version. On Linux, the easiest way +to ensure this is to use the package(s) in your distribution's package +repository. -To use the Notmuch emacs mode, first add the following line to your `.emacs` rc -file: +If you've installed Notmuch from a [git +checkout](https://git.notmuchmail.org/git/notmuch) or a [source +release](https://notmuchmail.org/releases/), Notmuch Emacs is included by +default. + +It is **not** recommended to install Notmuch Emacs from the Emacs Lisp Package +Archive (ELPA), as the version there is likely not in sync with the command line +interface. + +## Setup + +First, you need to tell Emacs about Notmuch. Add this to your `.emacs` rc file: (autoload 'notmuch "notmuch" "notmuch mail" t) -or if you always want to load notmuch when you start emacs: +or if you always want to load Notmuch when you start Emacs: (require 'notmuch) -Then, either run `emacs -f notmuch`, or execute the command `M-x notmuch` from -within a running emacs. +To start Notmuch Emacs, either run `emacs -f notmuch`, or execute the command +`M-x notmuch RET` from within a running Emacs. This will bring you to the +Notmuch Hello view. -### Notmuch Emacs configuration file: +## Customization -(Since Notmuch 0.18) +Notmuch Emacs uses the Emacs customization interface extensively for +configuration. Execute `M-x customize-group RET notmuch RET` to get to the +Notmuch main customization group. -After notmuch is loaded `notmuch-init-file` (typically +### Notmuch Emacs configuration file + +After Notmuch is loaded `notmuch-init-file` (typically `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists -it is loaded. Most emacs lisp based configuration not suitable via +it is loaded. Most Emacs lisp based configuration not suitable via customization can be put there instead of `~/.emacs`. ## Navigating & reading mails -When first starting notmuch in emacs, you will be presented with the -notmuch "hello" page. If it exits with an error after writing -"Welcome to notmutch. You have" you need to do the basic notmuch setup +When first starting Notmuch in Emacs, you will be presented with the +Notmuch "hello" page. If it exits with an error after writing +"Welcome to notmuch. You have" you need to do the basic Notmuch setup first (see above). From here you can do searches, see lists of recent searches, saved searches, message tags, help information, etc. @@ -51,7 +77,7 @@ displaying the search results. Each line in the search results represents a message thread. Hitting the '?' key will show help for this mode. -In general, the 'q' will kill the current notmuch buffer and return +In general, the 'q' will kill the current Notmuch buffer and return you to the previous buffer (sort of like a 'pop'). In search mode, navigating to a thread and hitting return will then @@ -60,21 +86,21 @@ message contents of the thread. ## Sending mail -In any notmuch mode, you can start a new message by hitting the 'm' +In any Notmuch mode, you can start a new message by hitting the 'm' key. To reply to a message or thread, just hit the 'r' key. -When composing new messages, you will be entered in emacs's +When composing new messages, you will be entered in Emacs's `message-mode`, which is a powerful mode for composing and sending messages. When in message mode, you can type `C-c ?` for help. If you would like to use address autocompletion when composing -messages, see [address completion](#address_completion). +messages, see [address completion](/emacstips#index13h2). When you are ready to send a message, type `C-c C-c`. By default message mode will use your sendmail command to send mail, so make sure that works. One annoying standard configuration of message mode is -that it will hide the sent mail in your emacs frame stack, but it will -not close it. If you type several mails in an emacs session they will +that it will hide the sent mail in your Emacs frame stack, but it will +not close it. If you type several mails in an Emacs session they will accumulate and make switching between buffers more annoying. You can avoid that behavior by adding `(setq message-kill-buffer-on-exit t)` in your `.emacs` file @@ -97,7 +123,7 @@ to have them attached. In Ubuntu this works without any modifications if files are dragged from the file manager. And for those who prefer working from command line, the following -script opens new emacs window with empty message and attaches files +script opens new Emacs window with empty message and attaches files mentioned as script arguments. (Note: The script expects that you have `(server-start)` in your `.emacs` file.) @@ -109,3 +135,7 @@ mentioned as script arguments. (Note: The script expects that you have shift done emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)" + +Also, if you're the kind of person who forgets to add attachments, +there's a cure for that disease. See [Never forget +attachments](/emacstips#index27h2) for all the details.