#+title: Change log of notmuch-indicator
#+author: Protesilaos Stavrou
#+email: info@protesilaos.com
#+options: ':nil toc:nil num:nil author:nil email:nil

This document contains the release notes for each tagged commit on the
project's main git repository: <https://github.com/protesilaos/notmuch-indicator>.

The newest release is at the top.  For further details, please consult
the manual: <https://protesilaos.com/emacs/notmuch-indicator>.

* 1.3.0 on 2026-01-18
:PROPERTIES:
:CUSTOM_ID: h:e0d9caf2-b419-4bce-8521-f4ba5dff8b08
:END:

This version adds quality-of-life refinements to a stable package.

** The ~notmuch-indicator-mode~ sets up the ~notmuch-after-tag-hook~
:PROPERTIES:
:CUSTOM_ID: h:2651878e-1104-4652-93a8-288b3d8d9dca
:END:

The indicator will be updated whenever a message's tags change. This
way users do not need to rely on the timer-based method that we have
always had.

** The ~notmuch-indicator-refresh-count~ can be set to ~nil~
:PROPERTIES:
:CUSTOM_ID: h:032712b7-6394-44e5-965d-da122b33a5fb
:END:

Doing so has the effect of disabling the timer-based refresh of the
indicator. It will now be updated only when some event happens, such
as with the aforementioned change to tags or after the invocation of
any of the commands listed in the user option ~notmuch-indicator-force-refresh-commands~.

** More configuration file paths
:PROPERTIES:
:CUSTOM_ID: h:b4ad9000-0a59-4e7e-9a96-0288b72a7b6d
:END:

When checking for the ~notmuch~ configuration file, we now also
consider these two filesystem paths:

- =$HOME/.config/notmuch/$NOTMUCH_PROFILE/config=
- =$HOME/.config/notmuch/default/config=

Thanks to Yejun Su for the contribution in pull request 6:
<https://github.com/protesilaos/notmuch-indicator/pull/6>.

The change is small, meaning that Yejun Su does not need to assign
copyright to the Free Software Foundation.

* 1.2.0 on 2024-05-11
:PROPERTIES:
:CUSTOM_ID: h:59674a50-c1b7-4ca3-92ce-2b986bc3f0bf
:END:

This version brings quality-of-life refinements to an already stable
package.

** More styles for the indicator
:PROPERTIES:
:CUSTOM_ID: h:35470310-c369-4d58-8ef0-297c379ce07b
:END:

The user option ~notmuch-indicator-args~ always accepted an optional
face that was applied to the label that accompanies the given counter.
The same can now be done for the counter itself. To be concrete:

#+begin_src
LABEL       COUNTER

[unread]    10
#+end_src

Or what you will most likely prefer:

#+begin_src emacs-lisp
[U] 10
#+end_src

The technicalities of how to set those up are covered in the
documentation string of ~notmuch-indicator-args~. Here is a variant of
what I use (I actually have custom faces):

#+begin_src emacs-lisp
  (setq notmuch-indicator-args
        '(( :terms "tag:unread and tag:inbox"
            :label "[A] "
            :label-face font-lock-string-face
            :counter-face font-lock-string-face)
          ( :terms "tag:unread and tag:inbox and not tag:package and not tag:coach"
            :label "[U] "
            :label-face font-lock-type-face
            :counter-face font-lock-type-face)
          ( :terms "tag:unread and tag:package"
            :label "[P] "
            :label-face font-lock-function-name-face
            :counter-face font-lock-function-name-face)
          ( :terms "tag:unread and tag:coach"
            :label "[C] "
            :label-face font-lock-preprocessor-face
            :counter-face font-lock-preprocessor-face)))
#+end_src

For backward-compatibility, =:face= has the same meaning as =:label-face=.

** Control exactly where the indicator is placed
:PROPERTIES:
:CUSTOM_ID: h:75c87a22-7078-4db2-8731-5f2e13e034d1
:END:

This is for advanced users, though I am happy to help you set it up if
you are interested.

By default, the indicator (the block with all the email counters) is
appended to the mode line. It thus shows up on the mode line of the
current window but also on that of all inactive windows.

To control exactly where the indicator is placed set the user option
~notmuch-indicator-add-to-mode-line-misc-info~ to nil. This will no
longer display the indicator on the mode line. Then do any of the
following:

1. If you are using the built-in ~tab-bar-mode~, add the
   ~notmuch-indicator-tab-bar-format~ to the list of ~tab-bar-format~.
   Like this:

   #+begin_src emacs-lisp
   (setq tab-bar-format
         '( tab-bar-format-history
            tab-bar-format-tabs
            tab-bar-separator
            tab-bar-format-add-tab
            tab-bar-format-align-right
            notmuch-indicator-tab-bar-format ; here it is
            tab-bar-separator
            tab-bar-format-global))
   #+end_src

2. Add the ~ ~notmuch-indicator-mode-line-construct~ to the
   ~mode-line-format~. This allows you to put it wherever you want,
   such as before the buffer name.

3. Create your own mode line construct with the extra logic you need
   and then add it anywhere you want in the ~mode-line-format~ list.
   This is what I do to display the indicator only on the active mode
   line:

   #+begin_src emacs-lisp
   ;; Here is my variant of the indicator.
   (defvar-local prot-modeline-notmuch-indicator
       '(notmuch-indicator-mode
         (" "
          (:eval (when (mode-line-window-selected-p)
                   notmuch-indicator--counters))))
     "The equivalent of `notmuch-indicator-mode-line-construct'.
   Display the indicator only on the focused window's mode line.")

   ;; And here I format my modeline to place everything exactly where I want.
   (setq-default mode-line-format
                 '("%e"
                   ;; ... things before
                   prot-modeline-notmuch-indicator
                   ;; ... things after
                   prot-modeline-misc-info))
   #+end_src

** Escape queries to avoid shell errors
:PROPERTIES:
:CUSTOM_ID: h:93996b38-c28f-4802-9a65-5aa0e3985c4d
:END:

We now escape all special shell characters before running the
~notmuch~ shell command to get the number of emails. This way, more
complex queries are read without any issue. Thanks to Sébastien
Delafond for the contribution, which was done in pull request 4:
<https://github.com/protesilaos/notmuch-indicator/pull/4>.

The change is small, meaning that Sébastien does not need to assign
copyright to the Free Software Foundation.

** Bind call to the ~notmuch~ binary to the user's home directory
:PROPERTIES:
:CUSTOM_ID: h:8ed85974-3122-420e-97f2-de94d2e890f3
:END:

The reason for this is explained by @shimeike (MikeS):
<https://github.com/protesilaos/notmuch-indicator/issues/2#issuecomment-1819853525>.
In short, we want to make sure we use the correct binary while
visiting files via TRAMP.

Also thanks to Mohamed Suliman for corroborating the findings
discussed therein.

* 1.1.0 on 2023-10-14
:PROPERTIES:
:CUSTOM_ID: h:331ff2c0-a76b-4018-98d7-be6822626f75
:END:

** The indicator now works over TRAMP
:PROPERTIES:
:CUSTOM_ID: h:872a225a-df52-4f37-897c-cac77310d086
:END:

In previous versions, the counters of the ~notmuch-indicator-mode~
would be omitted from the mode line if the refresh would happen while
the user was browsing a remote file system with TRAMP. They would be
restored once the user would switch to a local buffer. This was done
as a precaution, as I had not yet developed a mechanism to retrieve
the data relative to the local user.

Counters are now always on display and are pointing to the local
user's configuration. The package furnishes two new users options,
which make this possible: the ~notmuch-indicator-notmuch-config-file~
and ~notmuch-indicator-notmuch-binary~.

Their respective value is set at the time the ~notmuch-indicator~
feature is loaded (such as with ~require~ or ~use-package~).

Advanced users may wish to display different indicators depending on
the TRAMP environment. In principle, this is done by setting the
aforementioned options to the appropriate values. If anyone has such a
use-case, please contact me as I am eager to make the package more
flexible.

** The mouse hover of counters has a better style
:PROPERTIES:
:CUSTOM_ID: h:d44b8111-2101-4fe5-b5cf-a1b824188419
:END:

One of the nice features of the ~notmuch-indicator-mode~ counters on
the mode line is that they are clickable: a mouse click produces a
~notmuch.el~ buffer with the same search terms as those that populate
the counter.

Before, the face used to indicate the mouse hover state was the
generic ~highlight~ which can differ from the ~mode-line-highlight~
(depending on the theme).  We now use the latter to make sure that the
styling is consistent.

** Documentation
:PROPERTIES:
:CUSTOM_ID: h:5acd3900-4533-48d3-bf90-21c83e97fcbe
:END:

- The documentation of ~notmuch-indicator~ is now available on my
  website as well as an Info manual together with the GNU ELPA
  package.  On my website: <https://protesilaos.com/emacs/notmuch-indicator>.

- I did not keep a =CHANGELOG.org= for this package, though I am doing
  it from now on. This file's corresponding web page is this one:
  <https://protesilaos.com/emacs/notmuch-indicator-changelog>.

 At any rate, I always publish release notes on my coding-related
  blog. The previous publications from oldest to newest:

  - <https://protesilaos.com/codelog/2022-09-21-notmuch-indicator-0-1-0/>
  - <https://protesilaos.com/codelog/2022-10-06-notmuch-indicator-0-2-0/>
  - <https://protesilaos.com/codelog/2023-06-30-notmuch-indicator-1-0-0/>
