nmbug - manage notmuch bugs with git

       Carl Worth and many others

       2009-2024, Carl Worth and many others

0.38.3                                            Mar 11, 2025                                          NMBUG(1)

       Manage notmuch tags with Git.

   OPTIONS
       Supported options for notmuchgit 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 REPOSITORYLOCATION for defaults.

       -p<prefix>,--tag-prefix<prefix>
              Operate only on tags with prefix prefix. See PREFIXVALUE 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 REPOSITORYCONTENTS 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).Argumentstogit-archivearereorderedsothattree-ishcomeslast.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 notmuchgit 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)formoreinformationonspecifyingrepositories.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 notmuchgit command.

       init[--format-version=N]

       Create an empty notmuchgit 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 notmuchgitfetch, 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))orthenameofaremote(seethesectionREMOTESingit-pull(1)).refspec

          Refspec  (usually a branch name) to fetch and merge. See the refspec entry in the OPTIONS section of ‐git-pull(1)forotherpossibilities.push[repository][refspec]

       Push the local notmuchgit 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))orthenameofaremote(seethesectionREMOTESingit-push(1)).refspec

          Refspec  (usually  a branch name) to push. See the refspec entry in the OPTIONS section of git-push(1)forotherpossibilities.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 notmuchgitfetch 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.

       Variable NOTMUCH_PROFILE influences REPOSITORYLOCATION.  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.

       nmbug - manage notmuch bugs with git

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.

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

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

   Version1
       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 version0, this reduces the number of subdirectories within each directory.

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.

notmuch, notmuch-dump, notmuch-restore, notmuch-tag

notmuchgit [-h] [-N] [-C repo] [-p prefix] [-v] [-l loglevel] subcommandnmbug [-h] [-C repo] [-p prefix] [-v] [-l loglevel] subcommand