[PATCH 8/8] doc: document database search algorithm.

Subject: [PATCH 8/8] doc: document database search algorithm.

Date: Mon, 2 Aug 2021 12:09:22 -0300

To: notmuch@notmuchmail.org

Cc: David Bremner

From: David Bremner

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/<profile>`` where ``<profile>``
+   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..de4c91ac 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)`
-- 
2.30.2
_______________________________________________
notmuch mailing list -- notmuch@notmuchmail.org
To unsubscribe send an email to notmuch-leave@notmuchmail.org

Thread: