technical/repository-version.txt

   1 == Git Repository Format Versions
   2
   3 Every git repository is marked with a numeric version in the
   4 `core.repositoryformatversion` key of its `config` file. This version
   5 specifies the rules for operating on the on-disk repository data. An
   6 implementation of git which does not understand a particular version
   7 advertised by an on-disk repository MUST NOT operate on that repository;
   8 doing so risks not only producing wrong results, but actually losing
   9 data.
  10
  11 Because of this rule, version bumps should be kept to an absolute
  12 minimum. Instead, we generally prefer these strategies:
  13
  14   - bumping format version numbers of individual data files (e.g.,
  15     index, packfiles, etc). This restricts the incompatibilities only to
  16     those files.
  17
  18   - introducing new data that gracefully degrades when used by older
  19     clients (e.g., pack bitmap files are ignored by older clients, which
  20     simply do not take advantage of the optimization they provide).
  21
  22 A whole-repository format version bump should only be part of a change
  23 that cannot be independently versioned. For instance, if one were to
  24 change the reachability rules for objects, or the rules for locking
  25 refs, that would require a bump of the repository format version.
  26
  27 Note that this applies only to accessing the repository's disk contents
  28 directly. An older client which understands only format `0` may still
  29 connect via `git://` to a repository using format `1`, as long as the
  30 server process understands format `1`.
  31
  32 The preferred strategy for rolling out a version bump (whether whole
  33 repository or for a single file) is to teach git to read the new format,
  34 and allow writing the new format with a config switch or command line
  35 option (for experimentation or for those who do not care about backwards
  36 compatibility with older gits). Then after a long period to allow the
  37 reading capability to become common, we may switch to writing the new
  38 format by default.
  39
  40 The currently defined format versions are:
  41
  42 === Version `0`
  43
  44 This is the format defined by the initial version of git, including but
  45 not limited to the format of the repository directory, the repository
  46 configuration file, and the object and ref storage. Specifying the
  47 complete behavior of git is beyond the scope of this document.
  48
  49 === Version `1`
  50
  51 This format is identical to version `0`, with the following exceptions:
  52
  53   1. When reading the `core.repositoryformatversion` variable, a git
  54      implementation which supports version 1 MUST also read any
  55      configuration keys found in the `extensions` section of the
  56      configuration file.
  57
  58   2. If a version-1 repository specifies any `extensions.*` keys that
  59      the running git has not implemented, the operation MUST NOT
  60      proceed. Similarly, if the value of any known key is not understood
  61      by the implementation, the operation MUST NOT proceed.
  62
  63 Note that if no extensions are specified in the config file, then
  64 `core.repositoryformatversion` SHOULD be set to `0` (setting it to `1`
  65 provides no benefit, and makes the repository incompatible with older
  66 implementations of git).
  67
  68 This document will serve as the master list for extensions. Any
  69 implementation wishing to define a new extension should make a note of
  70 it here, in order to claim the name.
  71
  72 The defined extensions are:
  73
  74 ==== `noop`
  75
  76 This extension does not change git's behavior at all. It is useful only
  77 for testing format-1 compatibility.
  78
  79 ==== `preciousObjects`
  80
  81 When the config key `extensions.preciousObjects` is set to `true`,
  82 objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
  83 `git repack -d`).
  84
  85 ==== `partialClone`
  86
  87 When the config key `extensions.partialClone` is set, it indicates
  88 that the repo was created with a partial clone (or later performed
  89 a partial fetch) and that the remote may have omitted sending
  90 certain unwanted objects.  Such a remote is called a "promisor remote"
  91 and it promises that all such omitted objects can be fetched from it
  92 in the future.
  93
  94 The value of this key is the name of the promisor remote.
  95
  96 ==== `worktreeConfig`
  97
  98 If set, by default "git config" reads from both "config" and
  99 "config.worktree" file from GIT_DIR in that order. In
 100 multiple working directory mode, "config" file is shared while
 101 "config.worktree" is per-working directory (i.e., it's in
 102 GIT_COMMON_DIR/worktrees/<id>/config.worktree)