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 , --git-dir Operate on git repository repo. See REPOSITORY LOCATION for defaults. -p , --tag-prefix Operate only on tags with prefix prefix. See PREFIX VALUE for defaults. -v, --version show notmuch-git's version number and exit -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'. 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 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..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..repository, likely origin, and branch..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. o Option --git-dir. o Environment variable NOTMUCH_GIT_DIR. o Configuration item git.path o 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. o Option --tag-prefix. o Environment variable NOTMUCH_GIT_PREFIX. o Configuration item git.tag_prefix. o 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-2024, Carl Worth and many others 0.38.3 April 5, 2024 NOTMUCH-GIT(1)