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