NOTMUCH-GIT(1) notmuch NOTMUCH-GIT(1) 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 de- faults. -p <prefix>, --tag-prefix <prefix> Operate only on tags with prefix prefix. See PREFIX VALUE for de- faults. -v, --version show notmuch-git's version number and exit -l <level>, --log-level <level> Log verbosity, one of: critical, error, warning, info, debug. De- faults 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 mes- sages 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 mes- sages 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 high- est 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. De- faults 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 ori- gin, 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 en- try 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 para- meter 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 git (equiva- lently, tag has been deleted in git repo, e.g. by a pull, but not re- stored to notmuch database). D Tag is present in git repo, but not restored to notmuch database (equiv- alently, 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 up- date 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 mes- sage-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 lo- cate 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-2026, Carl Worth and many others 0.40 Aug 27, 2026 NOTMUCH-GIT(1)
NAME | SYNOPSIS | DESCRIPTION | REPOSITORY CONTENTS | REPOSITORY LOCATION | PREFIX VALUE | ENVIRONMENT | SEE ALSO | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=notmuch-git&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>