d7497a42b0
Introduce a new "extensions.refStorage" extension that allows us to specify the ref storage format used by a repository. For now, the only supported format is the "files" format, but this list will likely soon be extended to also support the upcoming "reftable" format. There have been discussions on the Git mailing list in the past around how exactly this extension should look like. One alternative [1] that was discussed was whether it would make sense to model the extension in such a way that backends are arbitrarily stackable. This would allow for a combined value of e.g. "loose,packed-refs" or "loose,reftable", which indicates that new refs would be written via "loose" files backend and compressed into "packed-refs" or "reftable" backends, respectively. It is arguable though whether this flexibility and the complexity that it brings with it is really required for now. It is not foreseeable that there will be a proliferation of backends in the near-term future, and the current set of existing formats and formats which are on the horizon can easily be configured with the much simpler proposal where we have a single value, only. Furthermore, if we ever see that we indeed want to gain the ability to arbitrarily stack the ref formats, then we can adapt the current extension rather easily. Given that Git clients will refuse any unknown value for the "extensions.refStorage" extension they would also know to ignore a stacked "loose,packed-refs" in the future. So let's stick with the easy proposal for the time being and wire up the extension. [1]: <pull.1408.git.1667846164.gitgitgadget@gmail.com> Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>
108 lines
4.4 KiB
Plaintext
108 lines
4.4 KiB
Plaintext
== Git Repository Format Versions
|
|
|
|
Every git repository is marked with a numeric version in the
|
|
`core.repositoryformatversion` key of its `config` file. This version
|
|
specifies the rules for operating on the on-disk repository data. An
|
|
implementation of git which does not understand a particular version
|
|
advertised by an on-disk repository MUST NOT operate on that repository;
|
|
doing so risks not only producing wrong results, but actually losing
|
|
data.
|
|
|
|
Because of this rule, version bumps should be kept to an absolute
|
|
minimum. Instead, we generally prefer these strategies:
|
|
|
|
- bumping format version numbers of individual data files (e.g.,
|
|
index, packfiles, etc). This restricts the incompatibilities only to
|
|
those files.
|
|
|
|
- introducing new data that gracefully degrades when used by older
|
|
clients (e.g., pack bitmap files are ignored by older clients, which
|
|
simply do not take advantage of the optimization they provide).
|
|
|
|
A whole-repository format version bump should only be part of a change
|
|
that cannot be independently versioned. For instance, if one were to
|
|
change the reachability rules for objects, or the rules for locking
|
|
refs, that would require a bump of the repository format version.
|
|
|
|
Note that this applies only to accessing the repository's disk contents
|
|
directly. An older client which understands only format `0` may still
|
|
connect via `git://` to a repository using format `1`, as long as the
|
|
server process understands format `1`.
|
|
|
|
The preferred strategy for rolling out a version bump (whether whole
|
|
repository or for a single file) is to teach git to read the new format,
|
|
and allow writing the new format with a config switch or command line
|
|
option (for experimentation or for those who do not care about backwards
|
|
compatibility with older gits). Then after a long period to allow the
|
|
reading capability to become common, we may switch to writing the new
|
|
format by default.
|
|
|
|
The currently defined format versions are:
|
|
|
|
=== Version `0`
|
|
|
|
This is the format defined by the initial version of git, including but
|
|
not limited to the format of the repository directory, the repository
|
|
configuration file, and the object and ref storage. Specifying the
|
|
complete behavior of git is beyond the scope of this document.
|
|
|
|
=== Version `1`
|
|
|
|
This format is identical to version `0`, with the following exceptions:
|
|
|
|
1. When reading the `core.repositoryformatversion` variable, a git
|
|
implementation which supports version 1 MUST also read any
|
|
configuration keys found in the `extensions` section of the
|
|
configuration file.
|
|
|
|
2. If a version-1 repository specifies any `extensions.*` keys that
|
|
the running git has not implemented, the operation MUST NOT
|
|
proceed. Similarly, if the value of any known key is not understood
|
|
by the implementation, the operation MUST NOT proceed.
|
|
|
|
Note that if no extensions are specified in the config file, then
|
|
`core.repositoryformatversion` SHOULD be set to `0` (setting it to `1`
|
|
provides no benefit, and makes the repository incompatible with older
|
|
implementations of git).
|
|
|
|
This document will serve as the master list for extensions. Any
|
|
implementation wishing to define a new extension should make a note of
|
|
it here, in order to claim the name.
|
|
|
|
The defined extensions are:
|
|
|
|
==== `noop`
|
|
|
|
This extension does not change git's behavior at all. It is useful only
|
|
for testing format-1 compatibility.
|
|
|
|
==== `preciousObjects`
|
|
|
|
When the config key `extensions.preciousObjects` is set to `true`,
|
|
objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
|
|
`git repack -d`).
|
|
|
|
==== `partialClone`
|
|
|
|
When the config key `extensions.partialClone` is set, it indicates
|
|
that the repo was created with a partial clone (or later performed
|
|
a partial fetch) and that the remote may have omitted sending
|
|
certain unwanted objects. Such a remote is called a "promisor remote"
|
|
and it promises that all such omitted objects can be fetched from it
|
|
in the future.
|
|
|
|
The value of this key is the name of the promisor remote.
|
|
|
|
==== `worktreeConfig`
|
|
|
|
If set, by default "git config" reads from both "config" and
|
|
"config.worktree" files from GIT_DIR in that order. In
|
|
multiple working directory mode, "config" file is shared while
|
|
"config.worktree" is per-working directory (i.e., it's in
|
|
GIT_COMMON_DIR/worktrees/<id>/config.worktree)
|
|
|
|
==== `refStorage`
|
|
|
|
Specifies the file format for the ref database. The only valid value
|
|
is `files` (loose references with a packed-refs file).
|