From: David Bremner <david@tethera.net>
To: notmuch@notmuchmail.org
Subject: [PATCH v3 13/17] doc/notmuch-git: initial documentation
Date: Sat, 4 Jun 2022 14:23:09 -0300 [thread overview]
Message-ID: <20220604172313.1149879-14-david@tethera.net> (raw)
In-Reply-To: <20220604172313.1149879-1-david@tethera.net>
This is mainly derived from the various help outputs from the script,
with some massaging of markup and addition of links.
---
doc/conf.py | 4 +
doc/index.rst | 1 +
doc/man1/notmuch-git.rst | 271 +++++++++++++++++++++++++++++++++++++++
3 files changed, 276 insertions(+)
create mode 100644 doc/man1/notmuch-git.rst
diff --git a/doc/conf.py b/doc/conf.py
index e4bad9f1..f01c0058 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -123,6 +123,10 @@ man_pages = [
u'send mail with notmuch and emacs',
[notmuch_authors], 1),
+ ('man1/notmuch-git', 'notmuch-git',
+ u'manage notmuch tags with git',
+ [notmuch_authors], 1),
+
('man5/notmuch-hooks', 'notmuch-hooks',
u'hooks for notmuch',
[notmuch_authors], 5),
diff --git a/doc/index.rst b/doc/index.rst
index fbdcf779..c380ee1d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,6 +15,7 @@ Contents:
man1/notmuch-dump
notmuch-emacs
man1/notmuch-emacs-mua
+ man1/notmuch-git
man5/notmuch-hooks
man1/notmuch-insert
man1/notmuch-new
diff --git a/doc/man1/notmuch-git.rst b/doc/man1/notmuch-git.rst
new file mode 100644
index 00000000..86f246b6
--- /dev/null
+++ b/doc/man1/notmuch-git.rst
@@ -0,0 +1,271 @@
+.. _notmuch-git(1):
+
+===========
+notmuch-git
+===========
+
+SYNOPSIS
+========
+
+**notmuch** **git** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
+
+DESCRIPTION
+===========
+
+Manage notmuch tags with Git.
+
+OPTIONS
+-------
+
+Supported options for `notmuch git` include
+
+.. program:: notmuch-git
+
+.. option:: -h, --help
+
+ show help message and exit
+
+.. option:: -C <repo>, --git-dir <repo>
+
+ Operate on git repository *repo*. See :ref:`repo_location` for
+ defaults.
+
+.. option:: -p <prefix>, --tag-prefix <prefix>
+
+ Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
+ defaults.
+
+.. option:: -v, --version
+
+ show notmuch-git's version number and exit
+
+.. option:: -l <level>, --log-level <level>
+
+ Log verbosity, one of: `critical`, `error`, `warning`, `info`,
+ `debug`. Defaults to `warning`.
+
+SUBCOMMANDS
+-----------
+
+For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.
+
+.. program:: notmuch-git
+
+.. option:: archive [tree-ish] [arg ...]
+
+Dump a tar archive of a committed tag set using 'git archive'. See
+:any:`format` for details of the archive contents.
+
+ .. describe:: tree-ish
+
+ The tree or commit to produce an archive for. Defaults to 'HEAD'.
+
+ .. describe:: arg
+
+ If present, any optional arguments are passed through to
+ :manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
+ so that *tree-ish* comes last.
+
+.. option:: checkout
+
+Update the notmuch database from Git.
+
+This is mainly useful to discard your changes in notmuch relative
+to Git.
+
+.. option:: clone <repository>
+
+Create a local `notmuch git` repository from a remote source.
+
+This wraps 'git clone', adding some options to avoid creating a
+working tree while preserving remote-tracking branches and
+upstreams.
+
+ .. describe:: repository
+
+ The (possibly remote) repository to clone from. See the URLS
+ section of :manpage:`git-clone(1)` for more information on
+ specifying repositories.
+
+.. option:: commit [message]
+
+Commit prefix-matching tags from the notmuch database to Git.
+
+ .. describe:: message
+
+ Optional text for the commit message.
+
+.. option:: fetch [remote]
+
+Fetch changes from the remote repository.
+
+ .. describe:: remote
+
+ Override the default configured in `branch.<name>.remote` to fetch
+ from a particular remote repository (e.g. `origin`).
+
+.. option:: help
+
+Show brief help for an `notmuch git` command.
+
+.. option:: init
+
+Create an empty `notmuch git` repository.
+
+This wraps 'git init' with a few extra steps to support subsequent
+status and commit commands.
+
+.. option:: log [arg ...]
+
+A wrapper for 'git log'.
+
+ .. describe:: arg
+
+ Additional arguments are passed through to 'git log'.
+
+After running `notmuch git fetch`, you can inspect the changes with
+
+::
+
+ $ notmuch git log HEAD..@{upstream}
+
+.. option:: merge [reference]
+
+Merge changes from 'reference' into HEAD and load the result into notmuch.
+
+ .. describe:: reference
+
+ Reference, usually other branch heads, to merge into our
+ branch. Defaults to `@{upstream}`.
+
+.. option:: pull [repository] [refspec ...]
+
+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
+(`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
+likely `master` or `main`).
+
+ .. describe:: repository
+
+ The "remote" repository that is the source of the pull. This parameter
+ can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
+ name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
+
+ .. describe:: refspec
+
+ Refspec (usually a branch name) to fetch and merge. See the
+ *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
+ other possibilities.
+
+.. option:: push [repository] [refspec]
+
+Push the local `notmuch git` Git state to a remote repository.
+
+ .. describe:: repository
+
+ The "remote" repository that is the destination of the push. This
+ parameter can be either a URL (see the section GIT URLS in
+ :manpage:`git-push(1)`) or the name of a remote (see the section
+ REMOTES in :manpage:`git-push(1)`).
+
+ .. describe:: refspec
+
+ Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
+ :manpage:`git-push(1)` for other possibilities.
+
+.. option:: status
+
+Show pending updates in notmuch or git repo.
+
+Prints lines of the form
+
+| ng Message-Id tag
+
+where n is a single character representing notmuch database status
+
+ .. 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
+ pull, but not restored to notmuch database).
+
+ .. describe:: D
+
+ Tag is present in nmbug repo, but not restored to notmuch
+ database (equivalently, tag has been deleted in notmuch).
+
+ .. describe:: U
+
+ Message is unknown (missing from local notmuch database).
+
+The second character *g* (if present) represents a difference between
+local and upstream branches. Typically `notmuch git fetch` needs to be
+run to update this.
+
+ .. describe:: a
+
+ Tag is present in upstream, but not in the local Git branch.
+
+ .. describe:: d
+
+ Tag is present in local Git branch, but not upstream.
+
+.. _format:
+
+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
+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.
+
+.. _repo_location:
+
+REPOSITORY LOCATION
+===================
+
+:any:`notmuch-git` uses the first of the following with a non-empty
+value to locate the git repository.
+
+- Option :option:`--git-dir`.
+
+- Environment variable :envvar:`NOTMUCH_GIT_DIR`.
+
+.. _prefix_val:
+
+PREFIX VALUE
+============
+
+:any:`notmuch-git` uses the first of the following with a non-null
+value to define the tag prefix.
+
+- Option :option:`--tag-prefix`.
+
+- Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
+
+ENVIRONMENT
+===========
+
+.. envvar:: NOTMUCH_GIT_DIR
+
+ Default location of git repository. Overriden by :option:`--git-dir`.
+
+.. envvar:: NOTMUCH_GIT_PREFIX
+
+ Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
+
+SEE ALSO
+========
+
+:any:`notmuch(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-tag(1)`
--
2.35.2
next prev parent reply other threads:[~2022-06-04 17:24 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-04 17:22 David Bremner
2022-06-04 17:22 ` [PATCH v3 01/17] nmbug: promote to user tool "notmuch-git" David Bremner
2022-06-04 17:22 ` [PATCH v3 02/17] CLI/git: drop support for python < 3.2 David Bremner
2022-06-04 17:22 ` [PATCH v3 03/17] notmuch-git: add --git-dir, --tag-prefix arguments David Bremner
2022-06-04 17:23 ` [PATCH v3 04/17] CLI/git: make existance of config branch optional on clone David Bremner
2022-06-04 17:23 ` [PATCH v3 05/17] CLI/git: Add an 'init' command David Bremner
2022-06-04 17:23 ` [PATCH v3 06/17] test: initial tests for notmuch-git David Bremner
2022-06-04 17:23 ` [PATCH v3 07/17] CLI/git: rename environment variables David Bremner
2022-06-04 17:23 ` [PATCH v3 08/17] CLI/git: suppress warnings about initial branch name David Bremner
2022-06-04 17:23 ` [PATCH v3 09/17] test/git: add known broken test for tag with quotes David Bremner
2022-06-04 17:23 ` [PATCH v3 10/17] CLI/git: replace enumeration of tags with sexp query David Bremner
2022-06-04 17:23 ` [PATCH v3 11/17] CLI/git: add @timed decorator, time a few functions David Bremner
2022-06-04 17:23 ` [PATCH v3 12/17] CLI/git: cache git indices David Bremner
2022-06-04 17:23 ` David Bremner [this message]
2022-06-04 17:23 ` [PATCH v3 14/17] CLI/git: change defaults for repo and prefix David Bremner
2022-06-04 17:23 ` [PATCH v3 15/17] CLI/git: support configuration for repo location / prefix David Bremner
2022-06-04 17:23 ` [PATCH v3 16/17] CLI/git: add safety checks for checkout and commit David Bremner
2022-06-04 17:23 ` [PATCH v3 17/17] debian: install notmuch-git David Bremner
2022-06-18 11:21 ` notmuch-git v3 David Bremner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220604172313.1149879-14-david@tethera.net \
--to=david@tethera.net \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).