]>
Commit | Line | Data |
---|---|---|
356aea6f | 1 | == Git Repository Format Versions |
00a09d57 JK |
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 | ||
356aea6f | 42 | === Version `0` |
00a09d57 JK |
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 | ||
356aea6f | 49 | === Version `1` |
00a09d57 JK |
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 | ||
356aea6f | 74 | ==== `noop` |
00a09d57 JK |
75 | |
76 | This extension does not change git's behavior at all. It is useful only | |
77 | for testing format-1 compatibility. | |
067fbd41 | 78 | |
356aea6f | 79 | ==== `preciousObjects` |
067fbd41 JK |
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`). | |
75b97fec | 84 | |
29c550f0 | 85 | ==== `partialClone` |
75b97fec | 86 | |
29c550f0 | 87 | When the config key `extensions.partialClone` is set, it indicates |
75b97fec JT |
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. | |
356aea6f NTND |
95 | |
96 | ==== `worktreeConfig` | |
97 | ||
98 | If set, by default "git config" reads from both "config" and | |
6cc668c0 | 99 | "config.worktree" files from GIT_DIR in that order. In |
356aea6f NTND |
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) | |
d7497a42 PS |
103 | |
104 | ==== `refStorage` | |
105 | ||
57db2a09 PS |
106 | Specifies the file format for the ref database. The valid values are |
107 | `files` (loose references with a packed-refs file) and `reftable` (see | |
108 | Documentation/technical/reftable.txt). |