emacs: Allow customizing :excluded in notmuch-saved-searches

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

diff --git a/doc/man1/notmuch-git.rst b/doc/man1/notmuch-git.rst
index 86f246b67d2a4e0b92b488322f2563624f20c97d..33a46f84058750ef19b910772089bbe07f7956ed 100644 (file)
--- a/doc/man1/notmuch-git.rst
+++ b/doc/man1/notmuch-git.rst
@@ -7,7 +7,9 @@ notmuch-git
 SYNOPSIS
 ========
 
 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
 ===========
 
 DESCRIPTION
 ===========


@@ -25,12 +27,17 @@ Supported options for `notmuch git` include
 
    show help message and exit
 
 
    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:: -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.
 
    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.
 
    :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.
 
 
 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.
 .. 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.
 
     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.
 


@@ -95,6 +107,11 @@ Commit prefix-matching tags from the notmuch database to Git.
 
    Optional text for the commit 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.


@@ -108,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'.


@@ -218,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:
 


@@ -239,6 +294,12 @@ value to locate the git repository.
 
 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
 
 
 - 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
 .. _prefix_val:
 
 PREFIX VALUE


@@ -251,16 +312,24 @@ value to define the tag prefix.
 
 - Environment variable :envvar:`NOTMUCH_GIT_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
 ===========
 
 ENVIRONMENT
 ===========
 

+Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
+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
 ========