gitrepository-layout(5)

NAME#

gitrepository-layout - Git Repository Layout

SYNOPSIS#

$GIT_DIR/*

DESCRIPTION#

A Git repository comes in two different flavours:

Note: Also you can have a plain text file .git at the root of your working tree, containing gitdir: <path> to point at the real directory that has the repository. This mechanism is called a gitfile and is usually managed via the git submodule and git worktree commands. It is often used for a working tree of a submodule checkout, to allow you in the containing superproject to git checkout a branch that does not have the submodule. The checkout has to remove the entire submodule working tree, without losing the submodule repository.

These things may exist in a Git repository.

objects

This directory is ignored if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/objects" will be used instead.

objects/[0-9a-f][0-9a-f]

objects/pack

objects/info

objects/info/packs

objects/info/alternates

objects/info/http-alternates

refs

refs/heads/name

refs/tags/name

refs/remotes/name

refs/replace/<obj-sha1>

packed-refs

HEAD

HEAD can also record a specific commit directly, instead of being a symref to point at the current branch. Such a state is often called detached HEAD. See git-checkout(1) for details.

config

config.worktree

branches

hooks

common

index

sharedindex.<SHA-1>

info

info/refs

info/grafts

Note that the grafts mechanism is outdated and can lead to problems transferring objects between repositories; see git-replace(1) for a more flexible and robust system to do the same thing.

info/exclude

info/attributes

info/sparse-checkout

remotes

logs

logs/refs/heads/name

logs/refs/tags/name

shallow

commondir

modules

worktrees

worktrees/<id>/gitdir

worktrees/<id>/locked

worktrees/<id>/config.worktree

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:

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:

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 valid values are files (loose references with a packed-refs file) and reftable (see Documentation/technical/reftable.txt).

SEE ALSO#

git-init(1), git-clone(1), git-fetch(1), git-pack-refs(1), git-gc(1), git-checkout(1), gitglossary(7), The Git User’s Manual[1]

GIT#

Part of the git(1) suite

NOTES#

1.

The Git User’s Manual