nmbug - manage notmuch bugs with git

NAME  SYNOPSIS  DESCRIPTION  OPTIONS  SUBCOMMANDS  REPOSITORY CONTENTS  Version 0  Version 1  REPOSITORY LOCATION  PREFIX VALUE  ENVIRONMENT  SEE ALSO  AUTHOR  COPYRIGHT 

NAME

nmbug − manage notmuch bugs 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). 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 <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 messages 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 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)) 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.

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-2023, Carl Worth and many others


Updated 2024-01-29 - jenkler.se | uex.se