.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "NOTMUCH-GIT" "1" "Feb 05, 2024" "0.38.2" "notmuch"
.SH NAME
notmuch-git \- manage notmuch tags with git
.SH SYNOPSIS
.sp
\fBnotmuch\fP \fBgit\fP [\-h] [\-N] [\-C \fIrepo\fP] [\-p \fIprefix\fP] [\-v] [\-l \fIlog level\fP] \fIsubcommand\fP
.sp
\fBnmbug\fP [\-h] [\-C \fIrepo\fP] [\-p \fIprefix\fP] [\-v] [\-l \fIlog level\fP] \fIsubcommand\fP
.SH DESCRIPTION
.sp
Manage notmuch tags with Git.
.SS OPTIONS
.sp
Supported options for \fInotmuch git\fP include
.INDENT 0.0
.TP
.B \-h, \-\-help
show help message and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-N, \-\-nmbug
Set defaults for \fI\%\-\-tag\-prefix\fP and \fI\%\-\-git\-dir\fP suitable for the
\fI\%notmuch\fP bug tracker
.UNINDENT
.INDENT 0.0
.TP
.B \-C <repo>, \-\-git\-dir <repo>
Operate on git repository \fIrepo\fP\&. See \fI\%REPOSITORY LOCATION\fP for
defaults.
.UNINDENT
.INDENT 0.0
.TP
.B \-p <prefix>, \-\-tag\-prefix <prefix>
Operate only on tags with prefix \fIprefix\fP\&. See \fI\%PREFIX VALUE\fP for
defaults.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-version
show notmuch\-git\(aqs version number and exit
.UNINDENT
.INDENT 0.0
.TP
.B \-l <level>, \-\-log\-level <level>
Log verbosity, one of: \fIcritical\fP, \fIerror\fP, \fIwarning\fP, \fIinfo\fP,
\fIdebug\fP\&. Defaults to \fIwarning\fP\&.
.UNINDENT
.SS SUBCOMMANDS
.sp
For help on a particular subcommand, run: \(aqnotmuch\-git ... <command> \-\-help\(aq.
.INDENT 0.0
.TP
.B archive [tree\-ish] [arg ...]
.UNINDENT
.sp
Dump a tar archive of a committed tag set using \(aqgit archive\(aq. See
\fI\%REPOSITORY CONTENTS\fP for details of the archive contents.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B tree\-ish
.UNINDENT
.sp
The tree or commit to produce an archive for. Defaults to \(aqHEAD\(aq.
.INDENT 0.0
.TP
.B arg
.UNINDENT
.sp
If present, any optional arguments are passed through to
\fBgit\-archive(1)\fP\&. Arguments to \fIgit\-archive\fP are reordered
so that \fItree\-ish\fP comes last.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B checkout [\-f|\-\-force]
.UNINDENT
.sp
Update the notmuch database from Git.
.sp
This is mainly useful to discard your changes in notmuch relative
to Git.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B [\-f|\-\-force]
.UNINDENT
.sp
Override checks that prevent modifying tags for large fractions of
messages in the database. See also \fI\%git.safe_fraction\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B clone <repository>
.UNINDENT
.sp
Create a local \fInotmuch git\fP repository from a remote source.
.sp
This wraps \(aqgit clone\(aq, adding some options to avoid creating a
working tree while preserving remote\-tracking branches and
upstreams.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B repository
.UNINDENT
.sp
The (possibly remote) repository to clone from. See the URLS
section of \fBgit\-clone(1)\fP for more information on
specifying repositories.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B commit [\-f|\-\-force] [message]
.UNINDENT
.sp
Commit prefix\-matching tags from the notmuch database to Git.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B message
.UNINDENT
.sp
Optional text for the commit message.
.INDENT 0.0
.TP
.B \-f|\-\-force
.UNINDENT
.sp
Override checks that prevent modifying tags for large fractions of
messages in the database. See also \fI\%git.safe_fraction\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B fetch [remote]
.UNINDENT
.sp
Fetch changes from the remote repository.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B remote
.UNINDENT
.sp
Override the default configured in \fIbranch.<name>.remote\fP to fetch
from a particular remote repository (e.g. \fIorigin\fP).
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B help
.UNINDENT
.sp
Show brief help for an \fInotmuch git\fP command.
.INDENT 0.0
.TP
.B init [\-\-format\-version=N]
.UNINDENT
.sp
Create an empty \fInotmuch git\fP repository.
.sp
This wraps \(aqgit init\(aq with a few extra steps to support subsequent
status and commit commands.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-\-format\-version=N
.UNINDENT
.sp
Create a repo in format version N. By default \fI\%notmuch\-git\fP
uses the highest supported version, which is the best choice for
most use\-cases.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B log [arg ...]
.UNINDENT
.sp
A wrapper for \(aqgit log\(aq.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B arg
.UNINDENT
.sp
Additional arguments are passed through to \(aqgit log\(aq.
.UNINDENT
.UNINDENT
.sp
After running \fInotmuch git fetch\fP, you can inspect the changes with
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ notmuch git log HEAD..@{upstream}
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B merge [reference]
.UNINDENT
.sp
Merge changes from \(aqreference\(aq into HEAD and load the result into notmuch.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B reference
.UNINDENT
.sp
Reference, usually other branch heads, to merge into our
branch. Defaults to \fI@{upstream}\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B pull [repository] [refspec ...]
.UNINDENT
.sp
Pull (merge) remote repository changes to notmuch.
.sp
\fBpull\fP is equivalent to \fBfetch\fP followed by \fBmerge\fP\&.  We use the
Git\-configured repository for your current branch
(\fIbranch.<name>.repository\fP, likely \fIorigin\fP, and \fIbranch.<name>.merge\fP,
likely \fImaster\fP or \fImain\fP).
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B repository
.UNINDENT
.sp
The \(dqremote\(dq repository that is the source of the pull. This parameter
can be either a URL (see the section GIT URLS in \fBgit\-pull(1)\fP) or the
name of a remote (see the section REMOTES in \fBgit\-pull(1)\fP).
.INDENT 0.0
.TP
.B refspec
.UNINDENT
.sp
Refspec (usually a branch name) to fetch and merge. See the
\fIrefspec\fP entry in the OPTIONS section of \fBgit\-pull(1\fP) for
other possibilities.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B push [repository] [refspec]
.UNINDENT
.sp
Push the local \fInotmuch git\fP Git state to a remote repository.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B repository
.UNINDENT
.sp
The \(dqremote\(dq repository that is the destination of the push. This
parameter can be either a URL (see the section GIT URLS in
\fBgit\-push(1)\fP) or the name of a remote (see the section
REMOTES in \fBgit\-push(1)\fP).
.INDENT 0.0
.TP
.B refspec
.UNINDENT
.sp
Refspec (usually a branch name) to push. See the \fIrefspec\fP entry in the OPTIONS section of
\fBgit\-push(1)\fP for other possibilities.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B status
.UNINDENT
.sp
Show pending updates in notmuch or git repo.
.sp
Prints lines of the form
.nf
ng Message\-Id tag
.fi
.sp
.sp
where n is a single character representing notmuch database status
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B A
.UNINDENT
.sp
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).
.INDENT 0.0
.TP
.B D
.UNINDENT
.sp
Tag is present in nmbug repo, but not restored to notmuch
database (equivalently, tag has been deleted in notmuch).
.INDENT 0.0
.TP
.B U
.UNINDENT
.sp
Message is unknown (missing from local notmuch database).
.UNINDENT
.UNINDENT
.sp
The second character \fIg\fP (if present) represents a difference between
local and upstream branches. Typically \fInotmuch git fetch\fP needs to be
run to update this.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B a
.UNINDENT
.sp
Tag is present in upstream, but not in the local Git branch.
.INDENT 0.0
.TP
.B d
.UNINDENT
.sp
Tag is present in local Git branch, but not upstream.
.UNINDENT
.UNINDENT
.SH REPOSITORY CONTENTS
.sp
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.
.sp
In what follows \fIencode()\fP represents a POSIX filesystem safe
encoding. The encoding preserves alphanumerics, and the characters
\fI+\-_@=.,:\fP\&.  All other octets are replaced with \fI%\fP followed by a two
digit hex number.
.sp
Currently \fI\%notmuch\-git\fP can read any format version, but can only
create (via \fI\%init\fP) \fI\%version 1\fP repositories.
.SS Version 0
.sp
This is the legacy format created by the \fInmbug\fP tool prior to release
0.37.  For a message with Message\-Id \fIid\fP, for each tag \fItag\fP, there
is an empty file with path
.INDENT 0.0
.INDENT 3.5
tags/ \fIencode\fP (\fIid\fP) / \fIencode\fP (\fItag\fP)
.UNINDENT
.UNINDENT
.SS Version 1
.sp
In format version 1 and later, the format version is contained in a
top level file called FORMAT.
.sp
For a message with Message\-Id \fIid\fP, for each tag \fItag\fP, there
is an empty file with path
.INDENT 0.0
.INDENT 3.5
tags/ \fIhash1\fP (\fIid\fP) / \fIhash2\fP (\fIid\fP) \fIencode\fP (\fIid\fP) / \fIencode\fP (\fItag\fP)
.UNINDENT
.UNINDENT
.sp
The hash functions each represent one byte of the \fIblake2b\fP hex
digest.
.sp
Compared to \fI\%version 0\fP, this reduces the
number of subdirectories within each directory.
.SH REPOSITORY LOCATION
.sp
\fI\%notmuch\-git\fP uses the first of the following with a non\-empty
value to locate the git repository.
.INDENT 0.0
.IP \(bu 2
Option \fI\%\-\-git\-dir\fP\&.
.IP \(bu 2
Environment variable \fI\%NOTMUCH_GIT_DIR\fP\&.
.IP \(bu 2
Configuration item \fI\%git.path\fP
.IP \(bu 2
If invoked as \fInmbug\fP or with the \fI\%\-\-nmbug\fP option,
\fB$HOME/.nmbug\fP; otherwise
\fB$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git\fP\&.
.UNINDENT
.SH PREFIX VALUE
.sp
\fI\%notmuch\-git\fP uses the first of the following with a non\-null
value to define the tag prefix.
.INDENT 0.0
.IP \(bu 2
Option \fI\%\-\-tag\-prefix\fP\&.
.IP \(bu 2
Environment variable \fI\%NOTMUCH_GIT_PREFIX\fP\&.
.IP \(bu 2
Configuration item \fI\%git.tag_prefix\fP\&.
.IP \(bu 2
If invoked as \fInmbug\fP or with the \fI\%\-\-nmbug\fP option,
\fBnotmuch::\fP, otherwise the empty string.
.UNINDENT
.SH ENVIRONMENT
.sp
Variable \fI\%NOTMUCH_PROFILE\fP influences \fI\%REPOSITORY LOCATION\fP\&.
If it is unset, \(aqdefault\(aq is assumed.
.INDENT 0.0
.TP
.B NOTMUCH_GIT_DIR
Default location of git repository. Overridden by \fI\%\-\-git\-dir\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B NOTMUCH_GIT_PREFIX
Default tag prefix (filter). Overridden by \fI\%\-\-tag\-prefix\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fI\%notmuch\fP,
\fI\%notmuch\-dump\fP,
\fI\%notmuch\-restore\fP,
\fI\%notmuch\-tag\fP
.SH AUTHOR
Carl Worth and many others
.SH COPYRIGHT
2009-2024, Carl Worth and many others
.\" Generated by docutils manpage writer.
.