From bc0eb71fccd9c1be6dbdcda826da2fe2f74b0f53 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Sun, 25 Jan 2026 07:56:42 +0900 Subject: [PATCH] doc: initial documentation for git-remote-notmuch While it is not intended to be invoked directly, the user still needs to know how to use it via git commands. --- doc/command-line.rst | 1 + doc/conf.py | 3 + doc/man1/git-remote-notmuch.rst | 177 ++++++++++++++++++++++++++++++++ doc/man1/notmuch-config.rst | 23 +++++ 4 files changed, 204 insertions(+) create mode 100644 doc/man1/git-remote-notmuch.rst diff --git a/doc/command-line.rst b/doc/command-line.rst index 543a5f9e..5d084b10 100644 --- a/doc/command-line.rst +++ b/doc/command-line.rst @@ -23,6 +23,7 @@ Main commands man1/notmuch-search man1/notmuch-show man1/notmuch-tag + man1/git-remote-notmuch man5/notmuch-hooks Aliases diff --git a/doc/conf.py b/doc/conf.py index 6472d6f8..5e91f29b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -99,6 +99,9 @@ notmuch_authors = u'Carl Worth and many others' man_make_section_directory = False man_pages = [ + ('man1/git-remote-notmuch', 'git-remote-notmuch', + u'git remote helper for notmuch', + [notmuch_authors], 1), ('man1/notmuch', 'notmuch', u'thread-based email index, search, and tagging', [notmuch_authors], 1), diff --git a/doc/man1/git-remote-notmuch.rst b/doc/man1/git-remote-notmuch.rst new file mode 100644 index 00000000..ab368bab --- /dev/null +++ b/doc/man1/git-remote-notmuch.rst @@ -0,0 +1,177 @@ +.. _git-remote-notmuch(1): + +================== +git-remote-notmuch +================== + +Description +=========== + +git-remote-notmuch is a git remote helper to push and pull from +notmuch databases on the local machine. This remote helper handles +URIs prefixed with `notmuch:`. The remote helper is not usually +invoked directly by users, but indirectly by configuring a remote with +an appropriate URI (see :ref:`uri_format`, below) or by fetching or +pushing directly to such a URI. + +Configuration +============= + +This remote helper is configured via :any:`notmuch-config(1)` options. + +Git needs an email address and name to construct a commit. This remote +helper uses the values proved by :nmconfig:`user.primary_email` and +:nmconfig:`user.name` respectively. + +The handling of missing messages (messages referenced in the git +repository but not found in the database) is controlled by +:nmconfig:`git.fail_on_missing`. + +The file system layout of the repository is influenced by +:nmconfig:`git.metadata_prefix`. + +This remote helper ignores any commits that do not match +:nmconfig:`git.ref` + +.. _uri_format: + +URI format +========== + +This remote helper supports the following forms of URI. + +``notmuch://`` + The default notmuch database, located as documented + in ``notmuch-config(1)`` + +``notmuch://?config=notmuch-config`` + Use configuration file ``notmuch-config`` + +``notmuch://?profile=default`` + Use profile ``default`` + +``notmuch://?config=notmuch-config&profile=default`` + Combine previous two. + +``notmuch://home/blub/mail`` + Use the database / mail_root at ``/home/blub/mail`` + +``notmuch://home/blub/mail/?config=/home/blub/notmuch-config`` + Use the database / mail_root at ``/home/blub/mail``, + with the config file specified. + +``notmuch://home/blub/mail/?config=/home/blub/notmuch-config&profile=default`` + Set path, config file and profile. + +``notmuch://?path=/home/blub/mail&config=notmuch-config&profile=default`` + As previous, but using query format for all parameters. + +The prefix ``notmuch::`` can be substituted for ``notmuch://`` in all of the above and is essentially equivalent. See ``gitremote-helpers(1)`` for details. + +Examples +======== + +For these examples, assume shell variable ``TAG_FILE`` is set +as (cf. :any:`repository_format`):: + + TAG_FILE="_notmuch_metadata/87/b1/4EFC743A.3060609@april.org/tags" + +Add remote to an existing repo:: + + cd repo + git remote add database notmuch:: + git fetch database + git merge database/master + +Restore database state using push:: + + git clone notmuch:: repo + notmuch tag +foo id:bar + git -C repo push origin master + +Remove all tags on a single message via push:: + + git clone notmuch:: repo && cd repo + cp /dev/null $TAG_FILE + git add $TAG_FILE + git commit -m 'testing push' + git push origin master + +Recording database state to Git:: + + git clone notmuch:: repo && cd repo + cat $TAG_FILE + > inbox + > unread + notmuch tag +zznew -- id:4EFC743A.3060609@april.org + git pull + cat $TAG_FILE + > inbox + > unread + > zznew + +.. _repository_format: + +Repository format +================= + +Work Tree +--------- + +Metadata (currently only tags) is stored under the path defined by the +option :nmconfig:`git.metadata_prefix` (by default `_notmuch_metadata`). +It is supported (and useful) to keep other files in the same +repository, outside this prefix. Such files will be ignored by +:any:`git-remote-notmuch(1)`. + +Inside the prefix directory, there is a directory corresponding to +each message-id in the notmuch database. The path of this directory is +obtained by taking the first two bytes of the SHA1 hash of the +message-id, followed by the hex escaped (in the manner documented in +:any:`notmuch-dump(1)`) message name. For example, the message-id ``discourse/post/15986@community.mnt.re`` corresponds to directory:: + + _notmuch_metadata/ae/27/discourse%2fpost%2f15986@community.mnt.re + +Inside each such directory is a (possibly empty) file containing the tags for that message, one per line. + +Repository Internals +-------------------- + +There is currently one file inside ``.git`` used by this remote +helper. The file ``.git/notmuch/lastmod`` stores the UUID and lastmod +counter of the most recent fetch of the database. This should match +the output of ``notmuch count --lastmod`` if the git repository and +the database are synchronized (but is not updated by git operations +not involving this remote helper). + +Environment variables +===================== + +.. envvar:: GIT_DIR + + Normally set by ``git``. + +.. envvar:: GIT_REMOTE_NM_LOG + + If set, log debugging information to the named file. + +.. envvar:: GIT_REMOTE_NM_DEBUG + + A string of single character flags to enable extra debugging. These are subject to change and should not be relied upon by e.g. scripts. + + ``d`` + Extra output about deletions + ``m`` + Extra output about missing messages + ``s`` + Sort output, for reproducibility + +See also +======== + +:manpage:`git(1)`, +:manpage:`gitremote-helpers(1)`, +:any:`notmuch-config(1)` +:any:`notmuch-dump(1)` +:any:`notmuch-restore(1)` + diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 5106655f..6a63e457 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -107,6 +107,21 @@ paths are presumed relative to `$HOME` for items in section Default: see :ref:`database` +.. nmconfig:: git.fail_on_missing + + Determine whether messages not found in database but known in git + are an error (``true``) or a warning (``false``) for + :any:`git-remote-notmuch(1)` + + Default: ``true`` + +.. nmconfig:: git.metadata_prefix + + Prefix under which :any:`git-remote-notmuch` stores + metadata from the database. + + Default: ``_notmuch_metadata``. + .. nmconfig:: git.path Default location for git repository for :any:`notmuch-git`. @@ -118,6 +133,13 @@ paths are presumed relative to `$HOME` for items in section too large. This item controls what fraction of total messages is considered "not too large". +.. nmconfig:: git.ref + + Commits that do not match this ref are ignored by + :any:`git-remote-notmuch` + + Default: ``refs/heads/master`` + .. nmconfig:: git.tag_prefix Default tag prefix (filter) for :any:`notmuch-git`. @@ -396,3 +418,4 @@ SEE ALSO :any:`notmuch-search-terms(7)`, :any:`notmuch-show(1)`, :any:`notmuch-tag(1)` +:any:`git-remote-notmuch(1)` -- 2.45.2