Notmuch: Full-Text Search Guide Like Multi-Occur

Oct 27, 2025 by Andrew McMorgan 49 views

Hey guys! Ever felt the need to dive deep into your email archive using Notmuch, but wished you had a "multi-occur-like" feature to make sifting through the results a breeze? You know, that handy Emacs feature that lists all occurrences of your search term, letting you jump from one to another effortlessly? Well, you're in the right place. Let’s explore how we can achieve a similar workflow in Notmuch to supercharge your email searching game. Buckle up!

Understanding the Challenge

Okay, so let's break down why this is something we even need to figure out. Notmuch is fantastic for quickly finding emails based on tags, sender, subject, and other metadata. But when it comes to the content of the emails, sometimes a simple search just doesn't cut it. You might find a bunch of emails, but then you're stuck opening each one and manually searching for your keyword. Ain't nobody got time for that!

The goal here is to mimic the multi-occur behavior. Imagine typing in your search term, and then bam, a list pops up showing every email where that term appears, along with a snippet of the context around it. Click on one, and you're instantly taken to that email. That's the dream. This approach is especially useful when you're dealing with large volumes of email and need to pinpoint specific information quickly.

Furthermore, think about the scenarios where this becomes invaluable. Legal professionals searching for specific phrases in case-related emails, researchers sifting through data for key insights, or even just us trying to find that one email with the important detail we vaguely remember. A multi-occur-like search transforms Notmuch from a great email index into a powerful content discovery tool. So, yeah, this is a pretty big deal.

Diving into Solutions: Emacs to the Rescue

Since Notmuch is designed to play nicely with other tools, especially Emacs, that's where we'll focus our efforts. Emacs provides the flexibility to create custom workflows and integrate with Notmuch's search capabilities. We'll use Emacs Lisp (elisp) to bridge the gap and build our multi-occur-like functionality.

Method 1: Leveraging `notmuch-search` and `occur`

The first approach involves combining notmuch-search with Emacs' built-in occur command. Here’s the basic idea:

Use notmuch-search to find emails matching your query.
Open the resulting emails in an Emacs buffer.
Use occur (or M-s o) to list all occurrences of your keyword within that buffer.

This is a straightforward method, but it has a limitation: it only searches the emails currently open in the buffer. To overcome this, we can write a function that automatically opens all the emails returned by notmuch-search in a single buffer.

Here’s a snippet of elisp code to get you started:

(defun notmuch-multi-occur (query)
  (interactive "sEnter Notmuch Query: ")
  (let ((emails (notmuch-search query)))
    (if (null emails)
        (message "No emails found.")
      (let ((buffer (generate-new-buffer "*Notmuch Multi-Occur*")))
        (with-current-buffer buffer
          (erase-buffer)
          (dolist (email emails)
            (insert-file-contents email)
            (insert "\n\n------------------------------------\n\n"))
        (occur query)))))

Explanation:

notmuch-multi-occur is the function we're defining. It takes a query as input.
notmuch-search executes the Notmuch search and returns a list of file paths to the matching emails.
We create a new Emacs buffer named *Notmuch Multi-Occur* to hold the content of all the emails.
We loop through the list of emails, insert the content of each one into the buffer, and add a separator for clarity.
Finally, we call occur to list all occurrences of the search term in the combined buffer.

To use this, evaluate the code in Emacs (e.g., by placing the cursor after the last parenthesis and pressing M-x eval-last-sexp), and then run M-x notmuch-multi-occur. Enter your Notmuch query, and you'll get a buffer listing all the occurrences.

Method 2: Enhancing with `notmuch-show` and Custom Parsing

Another approach is to use notmuch-show to extract the relevant content from the emails and then parse it to display the context around each match. This gives you more control over the output format.

Here’s a more advanced elisp function:

(defun notmuch-multi-occur-enhanced (query &optional context-lines)
  (interactive
   (list (read-string "Enter Notmuch Query: ")
         (read-number "Context Lines (default 3): " 3)))
  (let ((emails (notmuch-search query))
        (context-lines (or context-lines 3)))
    (if (null emails)
        (message "No emails found.")
      (let ((buffer (generate-new-buffer "*Notmuch Multi-Occur Enhanced*")))
        (with-current-buffer buffer
          (erase-buffer)
          (dolist (email emails)
            (let* ((output (shell-command-to-string (format "notmuch show %s" email)))
                   (matches (seq-filter (lambda (line) (string-match-p query line)) (split-string output "\n" t))))
              (dolist (match matches)
                (let* ((line-number (1+ (seq-position (split-string output "\n" t) match)))
                       (start-line (max 1 (- line-number context-lines)))
                       (end-line (min (length (split-string output "\n" t)) (+ line-number context-lines))))
                  (insert (format "Email: %s, Line: %d\n" email line-number))
                  (dotimes (i (- start-line 1) )
                    (insert "  "))
                  (loop for i from start-line to end-line do
                        (insert (nth i  (split-string output "\n" t)))
                    (insert "\n"))
                  (insert "\n------------------------------------\n\n"))))))
        (display-buffer buffer t)))))

Explanation:

notmuch-multi-occur-enhanced allows you to specify the number of context lines to display around each match.
It uses shell-command-to-string to run notmuch show and capture the email content as a string.
It splits the output into lines and filters for lines containing the search term.
For each match, it extracts the surrounding context lines and displays them in the buffer, along with the email file path and line number.

This enhanced version gives you a more readable output with context around each match, making it easier to understand the results.

Customizing Your Workflow

The beauty of Emacs is its customizability. You can tailor these solutions to fit your specific needs. Here are a few ideas:

Keybindings: Assign a keybinding to your notmuch-multi-occur function for quick access. For example:
```
(global-set-key (kbd "C-c n o") 'notmuch-multi-occur)
```
This binds C-c n o to the notmuch-multi-occur function.
Integration with Notmuch-mode: If you're using notmuch-mode, you can integrate these functions directly into the mode's keymap.
Custom Output Formatting: Modify the output format to include more information, such as the email subject or sender.
Asynchronous Searching: For large email archives, consider using asynchronous searching to prevent Emacs from freezing while the search is in progress.

Conclusion

So there you have it! Bringing a multi-occur-like search experience to Notmuch is totally achievable with a bit of Emacs magic. Whether you choose the simple occur approach or the enhanced context-aware version, you'll be well on your way to becoming a Notmuch power user. Now go forth and conquer your email mountain! Happy searching, folks!