CLI/git: add safety checks for checkout and commit

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

diff --git a/doc/man1/notmuch-git.rst b/doc/man1/notmuch-git.rst
index 86f246b67d2a4e0b92b488322f2563624f20c97d..fa7a748ea0c22c610dafb31c7eb22952731926d4 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.


@@ -239,6 +256,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,9 +274,17 @@ 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
 
    Default location of git repository. Overriden by :option:`--git-dir`.
 .. envvar:: NOTMUCH_GIT_DIR
 
    Default location of git repository. Overriden by :option:`--git-dir`.