--- name: "notmuch-git" section: "1" platform: "linux" package: "notmuch-runtime" version: "0.40-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/notmuch-git" --- # notmuch-git(1) manage notmuch tags with git ## 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)](/git-archive/1.md) \**. 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 \** 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)](/git-clone/1.md) \** 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.\.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)](/git-pull/1.md) \**) or the name of a remote (see the section REMOTES in **[git-pull(1)](/git-pull/1.md) \**). - **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)](/git-push/1.md) \**) or the name of a remote (see the section REMOTES in **[git-push(1)](/git-push/1.md) \**). - **refspec** Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of **[git-push(1)](/git-push/1.md) \** 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