Provided by: notmuch-git_0.38-2ubuntu1_all bug

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