git.cworth.org Git - notmuch/blob - doc/man1/notmuch-git.rst

   1 .. _notmuch-git(1):
   2
   3 ===========
   4 notmuch-git
   5 ===========
   6
   7 SYNOPSIS
   8 ========
   9
  10 **notmuch** **git** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
  11
  12 DESCRIPTION
  13 ===========
  14
  15 Manage notmuch tags with Git.
  16
  17 OPTIONS
  18 -------
  19
  20 Supported options for `notmuch git` include
  21
  22 .. program:: notmuch-git
  23
  24 .. option::  -h, --help
  25
  26    show help message and exit
  27
  28 .. option:: -C <repo>, --git-dir <repo>
  29
  30    Operate on git repository *repo*. See :ref:`repo_location` for
  31    defaults.
  32
  33 .. option::  -p <prefix>, --tag-prefix <prefix>
  34
  35    Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
  36    defaults.
  37
  38 .. option::   -v, --version
  39
  40    show notmuch-git's version number and exit
  41
  42 .. option::   -l <level>, --log-level <level>
  43
  44    Log verbosity, one of: `critical`, `error`, `warning`, `info`,
  45    `debug`. Defaults to `warning`.
  46
  47 SUBCOMMANDS
  48 -----------
  49
  50 For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.
  51
  52 .. program:: notmuch-git
  53
  54 .. option:: archive [tree-ish] [arg ...]
  55
  56 Dump a tar archive of a committed tag set using 'git archive'. See
  57 :any:`format` for details of the archive contents.
  58
  59    .. describe:: tree-ish
  60
  61    The tree or commit to produce an archive for. Defaults to 'HEAD'.
  62
  63    .. describe:: arg
  64
  65    If present, any optional arguments are passed through to
  66    :manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
  67    so that *tree-ish* comes last.
  68
  69 .. option:: checkout
  70
  71 Update the notmuch database from Git.
  72
  73 This is mainly useful to discard your changes in notmuch relative
  74 to Git.
  75
  76 .. option:: clone <repository>
  77
  78 Create a local `notmuch git` repository from a remote source.
  79
  80 This wraps 'git clone', adding some options to avoid creating a
  81 working tree while preserving remote-tracking branches and
  82 upstreams.
  83
  84     .. describe:: repository
  85
  86     The (possibly remote) repository to clone from. See the URLS
  87     section of :manpage:`git-clone(1)` for more information on
  88     specifying repositories.
  89
  90 .. option:: commit [message]
  91
  92 Commit prefix-matching tags from the notmuch database to Git.
  93
  94    .. describe:: message
  95
  96    Optional text for the commit message.
  97
  98 .. option:: fetch [remote]
  99
 100 Fetch changes from the remote repository.
 101
 102     .. describe:: remote
 103
 104     Override the default configured in `branch.<name>.remote` to fetch
 105     from a particular remote repository (e.g. `origin`).
 106
 107 .. option:: help
 108
 109 Show brief help for an `notmuch git` command.
 110
 111 .. option:: init
 112
 113 Create an empty `notmuch git` repository.
 114
 115 This wraps 'git init' with a few extra steps to support subsequent
 116 status and commit commands.
 117
 118 .. option:: log [arg ...]
 119
 120 A wrapper for 'git log'.
 121
 122    .. describe:: arg
 123
 124    Additional arguments are passed through to 'git log'.
 125
 126 After running `notmuch git fetch`, you can inspect the changes with
 127
 128 ::
 129
 130    $ notmuch git log HEAD..@{upstream}
 131
 132 .. option:: merge [reference]
 133
 134 Merge changes from 'reference' into HEAD and load the result into notmuch.
 135
 136    .. describe:: reference
 137
 138    Reference, usually other branch heads, to merge into our
 139    branch. Defaults to `@{upstream}`.
 140
 141 .. option:: pull [repository] [refspec ...]
 142
 143 Pull (merge) remote repository changes to notmuch.
 144
 145 **pull** is equivalent to **fetch** followed by **merge**.  We use the
 146 Git-configured repository for your current branch
 147 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
 148 likely `master` or `main`).
 149
 150    .. describe:: repository
 151
 152    The "remote" repository that is the source of the pull. This parameter
 153    can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
 154    name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
 155
 156    .. describe:: refspec
 157
 158    Refspec (usually a branch name) to fetch and merge. See the
 159    *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
 160    other possibilities.
 161
 162 .. option:: push [repository] [refspec]
 163
 164 Push the local `notmuch git` Git state to a remote repository.
 165
 166     .. describe::  repository
 167
 168     The "remote" repository that is the destination of the push. This
 169     parameter can be either a URL (see the section GIT URLS in
 170     :manpage:`git-push(1)`) or the name of a remote (see the section
 171     REMOTES in :manpage:`git-push(1)`).
 172
 173     .. describe:: refspec
 174
 175     Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
 176     :manpage:`git-push(1)` for other possibilities.
 177
 178 .. option:: status
 179
 180 Show pending updates in notmuch or git repo.
 181
 182 Prints lines of the form
 183
 184 |  ng Message-Id tag
 185
 186 where n is a single character representing notmuch database status
 187
 188    .. describe:: A
 189
 190    Tag is present in notmuch database, but not committed to nmbug
 191    (equivalently, tag has been deleted in nmbug repo, e.g. by a
 192    pull, but not restored to notmuch database).
 193
 194    .. describe:: D
 195
 196    Tag is present in nmbug repo, but not restored to notmuch
 197    database (equivalently, tag has been deleted in notmuch).
 198
 199    .. describe:: U
 200
 201    Message is unknown (missing from local notmuch database).
 202
 203 The second character *g* (if present) represents a difference between
 204 local and upstream branches. Typically `notmuch git fetch` needs to be
 205 run to update this.
 206
 207    .. describe:: a
 208
 209    Tag is present in upstream, but not in the local Git branch.
 210
 211    .. describe:: d
 212
 213    Tag is present in local Git branch, but not upstream.
 214
 215 .. _format:
 216
 217 REPOSITORY CONTENTS
 218 ===================
 219
 220 The tags are stored in the git repo (and exported) as a set of empty
 221 files. For a message with Message-Id *id*, for each tag *tag*, there
 222 is an empty file with path
 223
 224        tags/ `encode` (*id*) / `encode` (*tag*)
 225
 226 The encoding preserves alphanumerics, and the characters `+-_@=.,:`.
 227 All other octets are replaced with `%` followed by a two digit hex
 228 number.
 229
 230 .. _repo_location:
 231
 232 REPOSITORY LOCATION
 233 ===================
 234
 235 :any:`notmuch-git` uses the first of the following with a non-empty
 236 value to locate the git repository.
 237
 238 - Option :option:`--git-dir`.
 239
 240 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
 241
 242 .. _prefix_val:
 243
 244 PREFIX VALUE
 245 ============
 246
 247 :any:`notmuch-git` uses the first of the following with a non-null
 248 value to define the tag prefix.
 249
 250 - Option :option:`--tag-prefix`.
 251
 252 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
 253
 254 ENVIRONMENT
 255 ===========
 256
 257 .. envvar:: NOTMUCH_GIT_DIR
 258
 259    Default location of git repository. Overriden by :option:`--git-dir`.
 260
 261 .. envvar:: NOTMUCH_GIT_PREFIX
 262
 263    Default tag prefix (filter). Overriden by :option:`--tag-prefix`.
 264
 265 SEE ALSO
 266 ========
 267
 268 :any:`notmuch(1)`,
 269 :any:`notmuch-dump(1)`,
 270 :any:`notmuch-restore(1)`,
 271 :any:`notmuch-tag(1)`