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/[email protected]/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:[email protected]
+ 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/[email protected]`` corresponds to directory::
+
+ _notmuch_metadata/ae/27/discourse%2fpost%[email protected]
+
+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.51.0
_______________________________________________
notmuch mailing list -- [email protected]
To unsubscribe send an email to [email protected]
