Provided by: notmuch-git_0.38-2ubuntu1_all 
NAME
notmuch-git - manage notmuch tags with git
SYNOPSIS
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
Manage notmuch tags with Git.
OPTIONS
Supported options for notmuch git include
-h, --help
show help message and exit
-N, --nmbug
Set defaults for --tag-prefix and --git-dir suitable for the notmuch bug tracker
-C <repo>, --git-dir <repo>
Operate on git repository repo. See REPOSITORY LOCATION for defaults.
-p <prefix>, --tag-prefix <prefix>
Operate only on tags with prefix prefix. See PREFIX VALUE for defaults.
-v, --version
show notmuch-git's version number and exit
-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'.
archive [tree-ish] [arg ...]
Dump a tar archive of a committed tag set using 'git archive'. See REPOSITORY CONTENTS for
details of the archive contents.
tree-ish
The tree or commit to produce an archive for. Defaults to 'HEAD'.
arg
If present, any optional arguments are passed through to git-archive(1). Arguments to
git-archive are reordered so that tree-ish comes last.
checkout [-f|--force]
Update the notmuch database from Git.
This is mainly useful to discard your changes in notmuch relative to Git.
[-f|--force]
Override checks that prevent modifying tags for large fractions of messages in the
database. See also git.safe_fraction.
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.
repository
The (possibly remote) repository to clone from. See the URLS section of git-clone(1)
for more information on specifying repositories.
commit [-f|--force] [message]
Commit prefix-matching tags from the notmuch database to Git.
message
Optional text for the commit message.
-f|--force
Override checks that prevent modifying tags for large fractions of messages in the
database. See also git.safe_fraction.
fetch [remote]
Fetch changes from the remote repository.
remote
Override the default configured in branch.<name>.remote to fetch from a particular
remote repository (e.g. origin).
help
Show brief help for an notmuch git command.
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.
--format-version=N
Create a repo in format version N. By default notmuch-git uses the highest supported
version, which is the best choice for most use-cases.
log [arg ...]
A wrapper for 'git log'.
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}
merge [reference]
Merge changes from 'reference' into HEAD and load the result into notmuch.
reference
Reference, usually other branch heads, to merge into our branch. Defaults to
@{upstream}.
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).
repository
The "remote" repository that is the source of the pull. This parameter can be either a
URL (see the section GIT URLS in git-pull(1)) or the name of a remote (see the section
REMOTES in git-pull(1)).
refspec
Refspec (usually a branch name) to fetch and merge. See the refspec entry in the
OPTIONS section of git-pull(1) for other possibilities.
push [repository] [refspec]
Push the local notmuch git Git state to a remote repository.
repository
The "remote" repository that is the destination of the push. This parameter can be
either a URL (see the section GIT URLS in git-push(1)) or the name of a remote (see the
section REMOTES in git-push(1)).
refspec
Refspec (usually a branch name) to push. See the refspec entry in the OPTIONS section
of git-push(1) for other possibilities.
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
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).
D
Tag is present in nmbug repo, but not restored to notmuch database (equivalently, tag
has been deleted in notmuch).
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.
a
Tag is present in upstream, but not in the local Git branch.
d
Tag is present in local Git branch, but not upstream.
REPOSITORY CONTENTS
The tags are stored in the git repo (and exported) as a set of empty 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 notmuch-git can read any format version, but can only create (via init) version
1 repositories.
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)
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 version 0, this reduces the number of subdirectories within each directory.
REPOSITORY LOCATION
notmuch-git uses the first of the following with a non-empty value to locate the git
repository.
• Option --git-dir.
• Environment variable NOTMUCH_GIT_DIR.
• Configuration item git.path
• If invoked as nmbug or with the --nmbug option, $HOME/.nmbug; otherwise
$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git.
PREFIX VALUE
notmuch-git uses the first of the following with a non-null value to define the tag
prefix.
• Option --tag-prefix.
• Environment variable NOTMUCH_GIT_PREFIX.
• Configuration item git.tag_prefix.
• If invoked as nmbug or with the --nmbug option, notmuch::, otherwise the empty string.
ENVIRONMENT
Variable NOTMUCH_PROFILE influences REPOSITORY LOCATION. If it is unset, 'default' is
assumed.
NOTMUCH_GIT_DIR
Default location of git repository. Overridden by --git-dir.
NOTMUCH_GIT_PREFIX
Default tag prefix (filter). Overridden by --tag-prefix.
SEE ALSO
notmuch, notmuch-dump, notmuch-restore, notmuch-tag
AUTHOR
Carl Worth and many others
COPYRIGHT
2009-2023, Carl Worth and many others