python/doc: fix link to notmuch-config manpage

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

diff --git a/doc/man1/notmuch-git.rst b/doc/man1/notmuch-git.rst
index ad859b8094734a5fcf4368534d02d74548bdabc2..ae393ca1a044b96e25c75c554821b1fc34b9d874 100644 (file)
--- a/doc/man1/notmuch-git.rst
+++ b/doc/man1/notmuch-git.rst
@@ -73,12 +73,17 @@ 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.
 
    :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.
+Update the notmuch database from git.

 
 This is mainly useful to discard your changes in notmuch relative
 
 This is mainly useful to discard your changes in notmuch relative

-to Git.
+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>
 
 
 .. option:: clone <repository>
 


@@ -94,14 +99,19 @@ upstreams.
     section of :manpage:`git-clone(1)` for more information on
     specifying repositories.
 
     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.
+Commit prefix-matching tags from the notmuch database to git.

 
    .. describe:: message
 
    Optional text for the commit message.
 
 
    .. describe:: message
 
    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.
 .. option:: fetch [remote]
 
 Fetch changes from the remote repository.


@@ -115,13 +125,19 @@ Fetch changes from the remote repository.
 
 Show brief help for an `notmuch git` command.
 
 
 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.
 
 
 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'.
 .. option:: log [arg ...]
 
 A wrapper for 'git log'.


@@ -150,7 +166,7 @@ Merge changes from 'reference' into HEAD and load the result into notmuch.
 Pull (merge) remote repository changes to notmuch.
 
 **pull** is equivalent to **fetch** followed by **merge**.  We use the
 Pull (merge) remote repository changes to notmuch.
 
 **pull** is equivalent to **fetch** followed by **merge**.  We use the

-Git-configured repository for your current branch
+git-configured repository for your current branch

 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
 likely `master` or `main`).
 
 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
 likely `master` or `main`).
 


@@ -168,7 +184,7 @@ likely `master` or `main`).
 
 .. option:: push [repository] [refspec]
 
 
 .. option:: push [repository] [refspec]
 

-Push the local `notmuch git` Git state to a remote repository.
+Push the local `notmuch git` git state to a remote repository.

 
     .. describe::  repository
 
 
     .. describe::  repository
 


@@ -194,13 +210,13 @@ where n is a single character representing notmuch database status
 
    .. describe:: A
 
 
    .. describe:: A
 

-   Tag is present in notmuch database, but not committed to nmbug
-   (equivalently, tag has been deleted in nmbug repo, e.g. by a
+   Tag is present in notmuch database, but not committed to git
+   (equivalently, tag has been deleted in git repo, e.g. by a

    pull, but not restored to notmuch database).
 
    .. describe:: D
 
    pull, but not restored to notmuch database).
 
    .. describe:: D
 

-   Tag is present in nmbug repo, but not restored to notmuch
+   Tag is present in git repo, but not restored to notmuch

    database (equivalently, tag has been deleted in notmuch).
 
    .. describe:: U
    database (equivalently, tag has been deleted in notmuch).
 
    .. describe:: U


@@ -213,11 +229,11 @@ run to update this.
 
    .. describe:: a
 
 
    .. describe:: a
 

-   Tag is present in upstream, but not in the local Git branch.
+   Tag is present in upstream, but not in the local git branch.

 
    .. describe:: d
 
 
    .. describe:: d
 

-   Tag is present in local Git branch, but not upstream.
+   Tag is present in local git branch, but not upstream.

 
 .. _format:
 
 
 .. _format:
 


@@ -225,14 +241,46 @@ REPOSITORY CONTENTS
 ===================
 
 The tags are stored in the git repo (and exported) as a set of empty
 ===================
 
 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*)
 
 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:
 
 
 .. _repo_location:
 


@@ -277,11 +325,11 @@ If it is unset, 'default' is assumed.
 
 .. envvar:: NOTMUCH_GIT_DIR
 
 
 .. 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
 
 
 .. envvar:: NOTMUCH_GIT_PREFIX
 

-   Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
+   Default tag prefix (filter). Overridden by :option:`--tag-prefix`.

 
 SEE ALSO
 ========
 
 SEE ALSO
 ========