X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-git.rst;h=33a46f84058750ef19b910772089bbe07f7956ed;hb=HEAD;hp=86f246b67d2a4e0b92b488322f2563624f20c97d;hpb=e50a413906b9fadf93b7801c4758b48792bb348f;p=notmuch

diff --git a/doc/man1/notmuch-git.rst b/doc/man1/notmuch-git.rst
index 86f246b6..33a46f84 100644
--- a/doc/man1/notmuch-git.rst
+++ b/doc/man1/notmuch-git.rst
@@ -7,7 +7,9 @@ notmuch-git
 SYNOPSIS
 ========
 
-**notmuch** **git** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
+**notmuch** **git** [-h] [-N] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
+
+**nmbug** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
 
 DESCRIPTION
 ===========
@@ -25,12 +27,17 @@ Supported options for `notmuch git` include
 
    show help message and exit
 
+.. option:: -N, --nmbug
+
+   Set defaults for :option:`--tag-prefix` and :option:`--git-dir` suitable for the
+   :any:`notmuch` bug tracker
+
 .. option:: -C <repo>, --git-dir <repo>
 
    Operate on git repository *repo*. See :ref:`repo_location` for
    defaults.
 
-.. option::  -p <prefix>, --tag-prefix <prefix>
+.. option:: -p <prefix>, --tag-prefix <prefix>
 
    Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
    defaults.
@@ -66,13 +73,18 @@ Dump a tar archive of a committed tag set using 'git archive'. See
    :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.
@@ -87,7 +99,7 @@ upstreams.
     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.
 
@@ -95,6 +107,11 @@ 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.
@@ -108,13 +125,19 @@ 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'.
@@ -218,14 +241,46 @@ REPOSITORY CONTENTS
 ===================
 
 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:
 
@@ -239,6 +294,12 @@ value to locate the git repository.
 
 - 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`.
+
 .. _prefix_val:
 
 PREFIX VALUE
@@ -251,16 +312,24 @@ value to define the tag prefix.
 
 - 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.
+
 ENVIRONMENT
 ===========
 
+Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
+If it is unset, 'default' is assumed.
+
 .. envvar:: NOTMUCH_GIT_DIR
 
-   Default location of git repository. Overriden by :option:`--git-dir`.
+   Default location of git repository. Overridden by :option:`--git-dir`.
 
 .. envvar:: NOTMUCH_GIT_PREFIX
 
-   Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
+   Default tag prefix (filter). Overridden by :option:`--tag-prefix`.
 
 SEE ALSO
 ========