:manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
so that *tree-ish* comes last.
-.. option:: checkout
+.. option:: checkout [-f|--force]
Update the notmuch database from Git.
This is mainly useful to discard your changes in notmuch relative
to Git.
+ .. describe:: [-f|--force]
+
+ Override checks that prevent modifying tags for large fractions of
+ messages in the database. See also :nmconfig:`git.safe_fraction`.
+
.. option:: clone <repository>
Create a local `notmuch git` repository from a remote source.
section of :manpage:`git-clone(1)` for more information on
specifying repositories.
-.. option:: commit [message]
+.. option:: commit [-f|--force] [message]
Commit prefix-matching tags from the notmuch database to Git.
Optional text for the commit message.
+ .. describe:: -f|--force
+
+ Override checks that prevent modifying tags for large fractions of
+ messages in the database. See also :nmconfig:`git.safe_fraction`.
+
.. option:: fetch [remote]
Fetch changes from the remote repository.
Show brief help for an `notmuch git` command.
-.. option:: init
+.. option:: init [--format-version=N]
Create an empty `notmuch git` repository.
This wraps 'git init' with a few extra steps to support subsequent
status and commit commands.
+ .. describe:: --format-version=N
+
+ Create a repo in format version N. By default :any:`notmuch-git`
+ uses the highest supported version, which is the best choice for
+ most use-cases.
+
.. option:: log [arg ...]
A wrapper for 'git log'.
===================
The tags are stored in the git repo (and exported) as a set of empty
-files. For a message with Message-Id *id*, for each tag *tag*, there
+files. These empty files are contained within a directory named after
+the message-id.
+
+In what follows `encode()` represents a POSIX filesystem safe
+encoding. The encoding preserves alphanumerics, and the characters
+`+-_@=.,:`. All other octets are replaced with `%` followed by a two
+digit hex number.
+
+Currently :any:`notmuch-git` can read any format version, but can only
+create (via :any:`init`) :ref:`version 1 <format_version_1>` repositories.
+
+.. _format_version_0:
+
+Version 0
+---------
+
+This is the legacy format created by the `nmbug` tool prior to release
+0.37. For a message with Message-Id *id*, for each tag *tag*, there
is an empty file with path
tags/ `encode` (*id*) / `encode` (*tag*)
-The encoding preserves alphanumerics, and the characters `+-_@=.,:`.
-All other octets are replaced with `%` followed by a two digit hex
-number.
+.. _format_version_1:
+
+Version 1
+---------
+
+In format version 1 and later, the format version is contained in a
+top level file called FORMAT.
+
+For a message with Message-Id *id*, for each tag *tag*, there
+is an empty file with path
+
+ tags/ `hash1` (*id*) / `hash2` (*id*) `encode` (*id*) / `encode` (*tag*)
+
+The hash functions each represent one byte of the `blake2b` hex
+digest.
+
+Compared to :ref:`version 0 <format_version_0>`, this reduces the
+number of subdirectories within each directory.
.. _repo_location:
- Environment variable :envvar:`NOTMUCH_GIT_DIR`.
+- Configuration item :nmconfig:`git.path`
+
- If invoked as `nmbug` or with the :option:`--nmbug` option,
:code:`$HOME/.nmbug`; otherwise
:code:`$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git`.
- Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
+- Configuration item :nmconfig:`git.tag_prefix`.
+
- If invoked as `nmbug` or with the :option:`--nmbug` option,
:code:`notmuch::`, otherwise the empty string.