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