git.cworth.org Git - notmuch-wiki/blob - 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](http://www.gnu.org/software/emacs/) major mode for
   6 interacting with Notmuch. It is included in the Notmuch package (`notmuch-emacs`
   7 in Debian).
   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 ## Setup
  15
  16 Have a look at the [[Howto|howto]] for prerequisites. Be sure you have done the
  17 general setup using the notmuch cli command!
  18
  19 To use the Notmuch emacs mode, first add the following line to your `.emacs` rc
  20 file:
  21
  22         (autoload 'notmuch "notmuch" "notmuch mail" t)
  23
  24 or if you always want to load notmuch when you start emacs:
  25
  26         (require 'notmuch)
  27
  28 Then, either run `emacs -f notmuch`, or execute the command `M-x notmuch` from
  29 within a running emacs.
  30
  31 ### <span id="notmuch_init_file"> Notmuch Emacs configuration file: </span>
  32
  33 (Since Notmuch 0.18)
  34
  35 After notmuch is loaded `notmuch-init-file` (typically
  36  `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists
  37 it is loaded. Most emacs lisp based configuration not suitable via
  38 customization can be put there instead of `~/.emacs`.
  39
  40 ## Navigating & reading mails
  41
  42 When first starting notmuch in emacs, you will be presented with the
  43 notmuch "hello" page.  If it exits with an error after writing
  44 "Welcome to notmutch. You have" you need to do the basic notmuch setup
  45 first (see above).
  46 From here you can do searches, see lists of recent
  47 searches, saved searches, message tags, help information, etc.
  48
  49 Executing a search will open a new buffer in `notmuch-search-mode`
  50 displaying the search results.  Each line in the search results
  51 represents a message thread.  Hitting the '?' key will show help for
  52 this mode.
  53
  54 In general, the 'q' will kill the current notmuch buffer and return
  55 you to the previous buffer (sort of like a 'pop').
  56
  57 In search mode, navigating to a thread and hitting return will then
  58 open a new buffer in `notmuch-show-mode`, which will show the actual
  59 message contents of the thread.
  60
  61 ## Sending mail
  62
  63 In any notmuch mode, you can start a new message by hitting the 'm'
  64 key.  To reply to a message or thread, just hit the 'r' key.
  65
  66 When composing new messages, you will be entered in emacs's
  67 `message-mode`, which is a powerful mode for composing and sending
  68 messages.  When in message mode, you can type `C-c ?` for help.
  69
  70 If you would like to use address autocompletion when composing
  71 messages, see [address completion](#address_completion).
  72
  73 When you are ready to send a message, type `C-c C-c`. By default
  74 message mode will use your sendmail command to send mail, so make sure
  75 that works. One annoying standard configuration of message mode is
  76 that it will hide the sent mail in your emacs frame stack, but it will
  77 not close it. If you type several mails in an emacs session they will
  78 accumulate and make switching between buffers more annoying. You can
  79 avoid that behavior by adding `(setq message-kill-buffer-on-exit t)`
  80 in your `.emacs` file
  81 (or doing `M-x customize-variable<RET>message-kill-buffer-on-exit<RET>`)
  82 which will really close the mail window after sending it.
  83
  84 ## Attaching files
  85
  86 Using the `M-x mml-attach-file` command, you can attach any file to be
  87 sent with your mail. By default this command is bound to the menu item
  88 *Attachments--Attach File* with the key binding `C-c C-a`. The
  89 variable `mml-dnd-attach-options` (`M-x
  90 customize-variable<RET>mml-dnd-attach-options<RET>`) can be set to
  91 allow the prompting for various attachment options (such as
  92 inline/attachment) if you want to do that.
  93
  94 For those who prefer a more graphical interface, you can also simply
  95 drag and drop files from a file manager into a mail composition window
  96 to have them attached. In Ubuntu this works without any modifications
  97 if files are dragged from the file manager.
  98
  99 And for those who prefer working from command line, the following
 100 script opens new emacs window with empty message and attaches files
 101 mentioned as script arguments. (Note: The script expects that you have
 102 `(server-start)` in your `.emacs` file.)
 103
 104         #!/bin/sh
 105         attach_cmds=""
 106         while [ $# -gt 0 ]; do
 107             fullpath=$(readlink --canonicalize "$1")
 108             attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")"
 109             shift
 110         done
 111         emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"