From be6edee49660308131cbc7a6eb51e38c642cc098 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Wed, 4 Aug 2021 07:42:36 -0300 Subject: [PATCH] doc: document database search algorithm. Essentially a translation of the function _choose_database_path for human consumption. As a bonus, document environment variable NOTMUCH_DATABASE --- doc/man1/notmuch-config.rst | 21 ++++++++++++++++++++- doc/man1/notmuch.rst | 5 +++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 82fbb44c..07a9eaf0 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -60,7 +60,7 @@ paths are presumed relative to `$HOME` for items in section sub-directory named ``.notmuch`` if **database.mail\_root** is unset). - Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``. + Default: see :ref:`database` **database.mail_root** The top-level directory where your mail currently exists and to @@ -272,6 +272,25 @@ Notmuch configuration file search order: by :envvar:`NOTMUCH_PROFILE` environment variable if set, ``$HOME/.notmuch-config`` otherwise. +.. _database: + +DATABASE LOCATION +----------------- + +Notmuch database search order: + +1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable. + +2. Directory specified by config key ``database.path``. + +3. ``$XDG_DATA_HOME/notmuch/`` where ```` + is defined by :envvar:`NOTMUCH_PROFILE` environment variable if + set, ``$XDG_DATA_HOME/notmuch/default`` otherwise. + +4. Directory specified by :envvar:`MAILDIR` environment variable. + +5. ``$HOME/mail`` + HOOKS ----- diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 6bd1dc03..c6ee3036 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -164,6 +164,11 @@ of notmuch. Specifies the location of the notmuch configuration file. See :any:`notmuch-config(1)` for details. +.. envvar:: NOTMUCH_DATABASE + + Specifies the location of the notmuch database. See + :any:`notmuch-config(1)` for details. + .. envvar:: NOTMUCH_PROFILE Selects among notmuch configurations. See :any:`notmuch-config(1)`