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 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) <https://manpages.debian.org/git-archive.1.html>. 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 <#nmconfig-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) <https://manpages.debian.org/git-clone.1.html> 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 <#nmconfig-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) <https://manpages.debian.org/git-pull.1.html>) or the name of a remote (see the section REMOTES in git-pull(1) <https://manpages.debian.org/git-pull.1.html>).

refspec

    Refspec (usually a branch name) to fetch and merge. See the refspec entry in the OPTIONS section of git-pull(1 <https://manpages.debian.org/git-pull.1.html>) 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) <https://manpages.debian.org/git-push.1.html>) or the name of a remote (see the section REMOTES in git-push(1) <https://manpages.debian.org/git-push.1.html>).

refspec

    Refspec (usually a branch name) to push. See the refspec entry in the OPTIONS section of git-push(1) <https://manpages.debian.org/git-push.1.html> 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 (equivalently, tag has been deleted in git repo, e.g. by a pull, but not restored to notmuch database).

D

    Tag is present in git 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 <#nmconfig-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 <#nmconfig-git.tag_prefix>.

•   If invoked as nmbug or with the --nmbug option, notmuch::, otherwise the empty string.

ENVIRONMENT

Variable NOTMUCH_PROFILE <#envvar-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-1>, notmuch-dump <#notmuch-dump-1>, notmuch-restore <#notmuch-restore-1>, notmuch-tag <#notmuch-tag-1>

Author
Carl Worth and many others

Copyright
2009-2026, Carl Worth and many others