From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id oLA0IFuVm2IybwAAbAwnHQ (envelope-from ) for ; Sat, 04 Jun 2022 19:24:43 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id eIggIFuVm2JBJQAAauVa8A (envelope-from ) for ; Sat, 04 Jun 2022 19:24:43 +0200 Received: from mail.notmuchmail.org (yantan.tethera.net [135.181.149.255]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 3A7361CEA2 for ; Sat, 4 Jun 2022 19:24:43 +0200 (CEST) Received: from yantan.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 474095F7FA; Sat, 4 Jun 2022 17:23:51 +0000 (UTC) Received: from fethera.tethera.net (fethera.tethera.net [IPv6:2607:5300:60:c5::1]) by mail.notmuchmail.org (Postfix) with ESMTP id 564145F800 for ; Sat, 4 Jun 2022 17:23:47 +0000 (UTC) Received: by fethera.tethera.net (Postfix, from userid 1001) id 8E6D05FC1F; Sat, 4 Jun 2022 13:23:46 -0400 (EDT) Received: (nullmailer pid 1150091 invoked by uid 1000); Sat, 04 Jun 2022 17:23:25 -0000 From: David Bremner To: notmuch@notmuchmail.org Subject: [PATCH v3 13/17] doc/notmuch-git: initial documentation Date: Sat, 4 Jun 2022 14:23:09 -0300 Message-Id: <20220604172313.1149879-14-david@tethera.net> X-Mailer: git-send-email 2.35.2 In-Reply-To: <20220604172313.1149879-1-david@tethera.net> References: <20220604172313.1149879-1-david@tethera.net> MIME-Version: 1.0 Message-ID-Hash: 2CBJBZTUME7CVTFNI7BPDA2ZSWRCLX5H X-Message-ID-Hash: 2CBJBZTUME7CVTFNI7BPDA2ZSWRCLX5H X-MailFrom: bremner@tethera.net X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.3 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: DE ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1654363483; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-owner:list-unsubscribe:list-subscribe:list-post; bh=T/AkZlb0hrXf8kGqIdEjThnTorLOqRGP2sEMhlDeJv0=; b=ONZQmUXV3v8RB6YQwolp7/Udgi5RVkfh7qblY3qH+Q7/z3I+1wH0qAjRaHzkDZcMt0cu9S b37itaeksxIiVO6RuO/P8vCZb0uVvsoOh0QvyE6r/I3dbHE8P7/YIxmR1bTHR+3AMgc6J+ DSuLSDVJxLYSn0KhGJzvK/UCDp9bfmYUsG30k89Za2g/GHtWMS9rScGmwXWOqbFFFJwjcY Uee1SjTHr7TNog/cRdN6aVum8qTsKhu6AtGoIKJQZS3WIiSIq5JAdGxZ7oh6eHlh1ZZ39+ N88ltymAkqkhQym+WcqXp8OrwZDslsRvhstcZZ+d6CK2qfBJ8f2OkAHG8zxwgQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1654363483; a=rsa-sha256; cv=none; b=oV/62nQ7shIhLvFGR9jl4IlyBf7bZ6KkVRzCUMdX4Rj9SwfQYC2Dl4W9Bgdt15olmBF4n7 1DjaCpCyKjBmqjFa86G5EliMGp54Rg2D+AsGOpAkjc0IDd+vTErpM8pYt1jwfjtDKMZVHZ sYGc/LCiA6Kb6nDJ/EUYJQhyh2ZSo6pe0ZztgzDsjYJxeK2rSzR5GYg+/QXpF0HxM2auYY 9tlmsSjr0n36pyTvfEG4x9xrrteNs8Brsf+XaT6CBGUT7Mf9t3Qa9KugziWGb9ZxlxZcgm 4gKb+MmsOPcFI9+AvfM/u/qQBIs/QgLZz9i4623L+M9mdGuVu4fkxFenhO7D1A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 135.181.149.255 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -1.55 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 135.181.149.255 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: 3A7361CEA2 X-Spam-Score: -1.55 X-Migadu-Scanner: scn0.migadu.com X-TUID: mJTwwDJULN9J 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 , --git-dir + + Operate on git repository *repo*. See :ref:`repo_location` for + defaults. + +.. option:: -p , --tag-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 , --log-level + + Log verbosity, one of: `critical`, `error`, `warning`, `info`, + `debug`. Defaults to `warning`. + +SUBCOMMANDS +----------- + +For help on a particular subcommand, run: 'notmuch-git ... --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 + +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..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..repository`, likely `origin`, and `branch..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