doc: document database search algorithm.

[notmuch] / doc / man1 / notmuch-config.rst

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 129d4b81026191fe69651064333ff780e5709008..07a9eaf0bec3745f1cb6b4635f6caa7649f9d58f 100644 (file)
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -19,32 +19,37 @@ DESCRIPTION
 The **config** command can be used to get or set settings in the notmuch
 configuration file and corresponding database.
 
-**get**
-    The value of the specified configuration item is printed to
-    stdout. If the item has multiple values (it is a list), each value
-    is separated by a newline character.
+.. program:: config
 
-**set**
-    The specified configuration item is set to the given value. To
-    specify a multiple-value item (a list), provide each value as a
-    separate command-line argument.
+.. option:: get
 
-    If no values are provided, the specified configuration item will
-    be removed from the configuration file.
+   The value of the specified configuration item is printed to
+   stdout. If the item has multiple values (it is a list), each value
+   is separated by a newline character.
 
-    With the `--database` option, updates configuration metadata
-    stored in the database, rather than the default (text)
-    configuration file.
+.. option:: set
 
-**list**
-    Every configuration item is printed to stdout, each on a separate
-    line of the form::
+   The specified configuration item is set to the given value. To
+   specify a multiple-value item (a list), provide each value as a
+   separate command-line argument.
 
-        section.item=value
+   If no values are provided, the specified configuration item will
+   be removed from the configuration file.
 
-    No additional whitespace surrounds the dot or equals sign
-    characters. In a multiple-value item (a list), the values are
-    separated by semicolon characters.
+   With the `--database` option, updates configuration metadata
+   stored in the database, rather than the default (text)
+   configuration file.
+
+.. option:: list
+
+   Every configuration item is printed to stdout, each on a separate
+   line of the form::
+
+     section.item=value
+
+   No additional whitespace surrounds the dot or equals sign
+   characters. In a multiple-value item (a list), the values are
+   separated by semicolon characters.
 
 The available configuration items are described below. Non-absolute
 paths are presumed relative to `$HOME` for items in section
@@ -55,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
@@ -76,10 +81,21 @@ paths are presumed relative to `$HOME` for items in section
     `backups`.
 
 **database.hook_dir**
-
     Directory containing hooks run by notmuch commands. See
     :any:`notmuch-hooks(5)`.
 
+    History: this configuration value was introduced in notmuch 0.32.
+
+    Default: See HOOKS, below.
+
+**database.autocommit**
+
+    How often to commit transactions to disk. `0` means wait until
+    command completes, otherwise an integer `n` specifies to commit to
+    disk after every `n` completed transactions.
+
+    History: this configuration value was introduced in notmuch 0.33.
+
 **user.name**
     Your full name.
 
@@ -243,7 +259,7 @@ CONFIGURATION
 
 Notmuch configuration file search order:
 
-1. File specified by ``--config=FILE`` global option; see
+1. File specified by :option:`notmuch --config` global option; see
    :any:`notmuch(1)`.
 
 2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
@@ -256,7 +272,26 @@ Notmuch configuration file search order:
    by :envvar:`NOTMUCH_PROFILE` environment variable if set,
    ``$HOME/.notmuch-config`` otherwise.
 
-Hooks
+.. _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
 -----
 
 Notmuch hook directory search order: