| 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 | The defined extensions are given in the `extensions.*` section of |
| 69 | linkgit:git-config[1]. Any implementation wishing to define a new |
| 70 | extension should make a note of it there, in order to claim the name. |