1. Manuals
  2. Tumbleweed
  3. notmuch
  4. notmuch-git(1)

Scroll to navigation

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

show help message and exit

Set defaults for --tag-prefix and --git-dir suitable for the notmuch bug tracker

Operate on git repository repo. See REPOSITORY LOCATION for defaults.

Operate only on tags with prefix prefix. See PREFIX VALUE for defaults.

show notmuch-git's version number and exit

Log verbosity, one of: critical, error, warning, info, debug. Defaults to warning.

SUBCOMMANDS

For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.


Dump a tar archive of a committed tag set using 'git archive'. See REPOSITORY CONTENTS for details of the archive contents.


The tree or commit to produce an archive for. Defaults to 'HEAD'.


If present, any optional arguments are passed through to git-archive(1). Arguments to git-archive are reordered so that tree-ish comes last.




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.




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.


The (possibly remote) repository to clone from. See the URLS section of git-clone(1) for more information on specifying repositories.




Commit prefix-matching tags from the notmuch database to Git.


Optional text for the commit message.


Override checks that prevent modifying tags for large fractions of messages in the database. See also git.safe_fraction.




Fetch changes from the remote repository.


Override the default configured in branch.<name>.remote to fetch from a particular remote repository (e.g. origin).




Show brief help for an notmuch git command.


Create an empty notmuch git repository.

This wraps 'git init' with a few extra steps to support subsequent status and commit commands.


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.




A wrapper for 'git log'.


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 changes from 'reference' into HEAD and load the result into notmuch.


Reference, usually other branch heads, to merge into our branch. Defaults to @{upstream}.




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


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 (usually a branch name) to fetch and merge. See the refspec entry in the OPTIONS section of git-pull(1) for other possibilities.




Push the local notmuch git Git state to a remote 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 (usually a branch name) to push. See the refspec entry in the OPTIONS section of git-push(1) for other possibilities.




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


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


Tag is present in nmbug repo, but not restored to notmuch database (equivalently, tag has been deleted in notmuch).


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.


Tag is present in upstream, but not in the local Git branch.


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.

Default location of git repository. Overridden by --git-dir.

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

December 6, 2024 0.38.3