git.notmuchmail.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] [-N] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
  11
  12 **nmbug** [-h] [-C *repo*] [-p *prefix*] [-v] [-l *log level*] *subcommand*
  13
  14 DESCRIPTION
  15 ===========
  16
  17 Manage notmuch tags with Git.
  18
  19 OPTIONS
  20 -------
  21
  22 Supported options for `notmuch git` include
  23
  24 .. program:: notmuch-git
  25
  26 .. option::  -h, --help
  27
  28    show help message and exit
  29
  30 .. option:: -N, --nmbug
  31
  32    Set defaults for :option:`--tag-prefix` and :option:`--git-dir` suitable for the
  33    :any:`notmuch` bug tracker
  34
  35 .. option:: -C <repo>, --git-dir <repo>
  36
  37    Operate on git repository *repo*. See :ref:`repo_location` for
  38    defaults.
  39
  40 .. option:: -p <prefix>, --tag-prefix <prefix>
  41
  42    Operate only on tags with prefix *prefix*. See :ref:`prefix_val` for
  43    defaults.
  44
  45 .. option::   -v, --version
  46
  47    show notmuch-git's version number and exit
  48
  49 .. option::   -l <level>, --log-level <level>
  50
  51    Log verbosity, one of: `critical`, `error`, `warning`, `info`,
  52    `debug`. Defaults to `warning`.
  53
  54 SUBCOMMANDS
  55 -----------
  56
  57 For help on a particular subcommand, run: 'notmuch-git ... <command> --help'.
  58
  59 .. program:: notmuch-git
  60
  61 .. option:: archive [tree-ish] [arg ...]
  62
  63 Dump a tar archive of a committed tag set using 'git archive'. See
  64 :any:`format` for details of the archive contents.
  65
  66    .. describe:: tree-ish
  67
  68    The tree or commit to produce an archive for. Defaults to 'HEAD'.
  69
  70    .. describe:: arg
  71
  72    If present, any optional arguments are passed through to
  73    :manpage:`git-archive(1)`. Arguments to `git-archive` are reordered
  74    so that *tree-ish* comes last.
  75
  76 .. option:: checkout [-f|--force]
  77
  78 Update the notmuch database from Git.
  79
  80 This is mainly useful to discard your changes in notmuch relative
  81 to Git.
  82
  83    .. describe:: [-f|--force]
  84
  85    Override checks that prevent modifying tags for large fractions of
  86    messages in the database. See also :nmconfig:`git.safe_fraction`.
  87
  88 .. option:: clone <repository>
  89
  90 Create a local `notmuch git` repository from a remote source.
  91
  92 This wraps 'git clone', adding some options to avoid creating a
  93 working tree while preserving remote-tracking branches and
  94 upstreams.
  95
  96     .. describe:: repository
  97
  98     The (possibly remote) repository to clone from. See the URLS
  99     section of :manpage:`git-clone(1)` for more information on
 100     specifying repositories.
 101
 102 .. option:: commit [-f|--force] [message]
 103
 104 Commit prefix-matching tags from the notmuch database to Git.
 105
 106    .. describe:: message
 107
 108    Optional text for the commit message.
 109
 110    .. describe:: -f|--force
 111
 112    Override checks that prevent modifying tags for large fractions of
 113    messages in the database. See also :nmconfig:`git.safe_fraction`.
 114
 115 .. option:: fetch [remote]
 116
 117 Fetch changes from the remote repository.
 118
 119     .. describe:: remote
 120
 121     Override the default configured in `branch.<name>.remote` to fetch
 122     from a particular remote repository (e.g. `origin`).
 123
 124 .. option:: help
 125
 126 Show brief help for an `notmuch git` command.
 127
 128 .. option:: init [--format-version=N]
 129
 130 Create an empty `notmuch git` repository.
 131
 132 This wraps 'git init' with a few extra steps to support subsequent
 133 status and commit commands.
 134
 135    .. describe:: --format-version=N
 136
 137    Create a repo in format version N. By default :any:`notmuch-git`
 138    uses the highest supported version, which is the best choice for
 139    most use-cases.
 140
 141 .. option:: log [arg ...]
 142
 143 A wrapper for 'git log'.
 144
 145    .. describe:: arg
 146
 147    Additional arguments are passed through to 'git log'.
 148
 149 After running `notmuch git fetch`, you can inspect the changes with
 150
 151 ::
 152
 153    $ notmuch git log HEAD..@{upstream}
 154
 155 .. option:: merge [reference]
 156
 157 Merge changes from 'reference' into HEAD and load the result into notmuch.
 158
 159    .. describe:: reference
 160
 161    Reference, usually other branch heads, to merge into our
 162    branch. Defaults to `@{upstream}`.
 163
 164 .. option:: pull [repository] [refspec ...]
 165
 166 Pull (merge) remote repository changes to notmuch.
 167
 168 **pull** is equivalent to **fetch** followed by **merge**.  We use the
 169 Git-configured repository for your current branch
 170 (`branch.<name>.repository`, likely `origin`, and `branch.<name>.merge`,
 171 likely `master` or `main`).
 172
 173    .. describe:: repository
 174
 175    The "remote" repository that is the source of the pull. This parameter
 176    can be either a URL (see the section GIT URLS in :manpage:`git-pull(1)`) or the
 177    name of a remote (see the section REMOTES in :manpage:`git-pull(1)`).
 178
 179    .. describe:: refspec
 180
 181    Refspec (usually a branch name) to fetch and merge. See the
 182    *refspec* entry in the OPTIONS section of :manpage:`git-pull(1`) for
 183    other possibilities.
 184
 185 .. option:: push [repository] [refspec]
 186
 187 Push the local `notmuch git` Git state to a remote repository.
 188
 189     .. describe::  repository
 190
 191     The "remote" repository that is the destination of the push. This
 192     parameter can be either a URL (see the section GIT URLS in
 193     :manpage:`git-push(1)`) or the name of a remote (see the section
 194     REMOTES in :manpage:`git-push(1)`).
 195
 196     .. describe:: refspec
 197
 198     Refspec (usually a branch name) to push. See the *refspec* entry in the OPTIONS section of
 199     :manpage:`git-push(1)` for other possibilities.
 200
 201 .. option:: status
 202
 203 Show pending updates in notmuch or git repo.
 204
 205 Prints lines of the form
 206
 207 |  ng Message-Id tag
 208
 209 where n is a single character representing notmuch database status
 210
 211    .. describe:: A
 212
 213    Tag is present in notmuch database, but not committed to nmbug
 214    (equivalently, tag has been deleted in nmbug repo, e.g. by a
 215    pull, but not restored to notmuch database).
 216
 217    .. describe:: D
 218
 219    Tag is present in nmbug repo, but not restored to notmuch
 220    database (equivalently, tag has been deleted in notmuch).
 221
 222    .. describe:: U
 223
 224    Message is unknown (missing from local notmuch database).
 225
 226 The second character *g* (if present) represents a difference between
 227 local and upstream branches. Typically `notmuch git fetch` needs to be
 228 run to update this.
 229
 230    .. describe:: a
 231
 232    Tag is present in upstream, but not in the local Git branch.
 233
 234    .. describe:: d
 235
 236    Tag is present in local Git branch, but not upstream.
 237
 238 .. _format:
 239
 240 REPOSITORY CONTENTS
 241 ===================
 242
 243 The tags are stored in the git repo (and exported) as a set of empty
 244 files. These empty files are contained within a directory named after
 245 the message-id.
 246
 247 In what follows `encode()` represents a POSIX filesystem safe
 248 encoding. The encoding preserves alphanumerics, and the characters
 249 `+-_@=.,:`.  All other octets are replaced with `%` followed by a two
 250 digit hex number.
 251
 252 Currently :any:`notmuch-git` can read any format version, but can only
 253 create (via :any:`init`) :ref:`version 1 <format_version_1>` repositories.
 254
 255 .. _format_version_0:
 256
 257 Version 0
 258 ---------
 259
 260 This is the legacy format created by the `nmbug` tool prior to release
 261 0.37.  For a message with Message-Id *id*, for each tag *tag*, there
 262 is an empty file with path
 263
 264        tags/ `encode` (*id*) / `encode` (*tag*)
 265
 266 .. _format_version_1:
 267
 268 Version 1
 269 ---------
 270
 271 In format version 1 and later, the format version is contained in a
 272 top level file called FORMAT.
 273
 274 For a message with Message-Id *id*, for each tag *tag*, there
 275 is an empty file with path
 276
 277        tags/ `hash1` (*id*) / `hash2` (*id*) `encode` (*id*) / `encode` (*tag*)
 278
 279 The hash functions each represent one byte of the `blake2b` hex
 280 digest.
 281
 282 Compared to :ref:`version 0 <format_version_0>`, this reduces the
 283 number of subdirectories within each directory.
 284
 285 .. _repo_location:
 286
 287 REPOSITORY LOCATION
 288 ===================
 289
 290 :any:`notmuch-git` uses the first of the following with a non-empty
 291 value to locate the git repository.
 292
 293 - Option :option:`--git-dir`.
 294
 295 - Environment variable :envvar:`NOTMUCH_GIT_DIR`.
 296
 297 - Configuration item :nmconfig:`git.path`
 298
 299 - If invoked as `nmbug` or with the :option:`--nmbug` option,
 300   :code:`$HOME/.nmbug`; otherwise
 301   :code:`$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE/git`.
 302
 303 .. _prefix_val:
 304
 305 PREFIX VALUE
 306 ============
 307
 308 :any:`notmuch-git` uses the first of the following with a non-null
 309 value to define the tag prefix.
 310
 311 - Option :option:`--tag-prefix`.
 312
 313 - Environment variable :envvar:`NOTMUCH_GIT_PREFIX`.
 314
 315 - Configuration item :nmconfig:`git.tag_prefix`.
 316
 317 - If invoked as `nmbug` or with the :option:`--nmbug` option,
 318   :code:`notmuch::`, otherwise the empty string.
 319
 320 ENVIRONMENT
 321 ===========
 322
 323 Variable :envvar:`NOTMUCH_PROFILE` influences :ref:`repo_location`.
 324 If it is unset, 'default' is assumed.
 325
 326 .. envvar:: NOTMUCH_GIT_DIR
 327
 328    Default location of git repository. Overridden by :option:`--git-dir`.
 329
 330 .. envvar:: NOTMUCH_GIT_PREFIX
 331
 332    Default tag prefix (filter). Overridden by :option:`--tag-prefix`.
 333
 334 SEE ALSO
 335 ========
 336
 337 :any:`notmuch(1)`,
 338 :any:`notmuch-dump(1)`,
 339 :any:`notmuch-restore(1)`,
 340 :any:`notmuch-tag(1)`