NMBUG(1)

📦
version 0.40 · 12 versions
, in fedora 44, nixos 26.05, ubuntu resolute

🦋 NAME 🦋

nmbug — manage notmuch bugs with git

okay so this whole page is NMBUG(1), part of the notmuch manual, and it's literally your bestie for wrangling 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

two ways in, same energy 🫶

🌸 DESCRIPTION 🌸

Manage notmuch tags with Git.

that's it, that's the whole vibe. tags in, git out, no cap ✨

🎀 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'.

ngl bestie, that's the cheat code. use it liberally 🔥

📦 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.

🧚 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.

💖 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).

⬆️ push [repository] [refspec]

Push the local notmuch git git state to a remote repository.

yes it says "git git", we're keeping it, it's iconic 💅

👀 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

2009-2026, Carl Worth and many others

and that's the whole page, bestie!! 🫶✨ this was notmuch version 0.40, dated Jan 31, 2026 — go forth and tag responsibly, you absolute icon 💅🌈👑

📦 where this page comes from