NAME

     git-repository — Git repository format

DESCRIPTION

     A Git repository stores a series of versioned snapshots of a file hierarchy.  Conceptually,
     the repository's data model is a directed acyclic graph which contains four types of objects
     as nodes:

     Blobs   The content of tracked files is stored in objects of type blob.

     Trees   A tree object points to any number of such blobs, and also to other trees in order
             to represent a hierarchy of files and directories.

     Commits
             A commit object points to the root element of one tree, and thus records the state
             of this entire tree as a snapshot.  Commit objects are chained together to form
             lines of version control history.  Most commits have just one successor commit, but
             commits may be succeeded by an arbitrary number of subsequent commits so that
             diverging lines of version control history, known as branches, can be represented.
             A commit which precedes another commit is referred to as that other commit's parent
             commit.  A commit with multiple parents unites disparate lines of history and is
             known as a merge commit.

     Tags    A tag object associates a user-defined label with another object, which is typically
             a commit object.  Tag objects also contain a tag message, as well as author and
             timestamp information.

     Each object is identified by a SHA1 hash calculated over both the object's header and the
     data stored in the object.

OBJECT STORAGE

     Loose objects are stored as individual files beneath the directory objects, spread across
     256 sub-directories named after the 256 possible hexadecimal values of the first byte of an
     object identifier.  The name of the loose object file corresponds to the remaining
     hexadecimal byte values of the object's identifier.

     A loose object file begins with a header which specifies the type of object as an ASCII
     string, followed by an ASCII space character, followed by the object data's size encoded as
     an ASCII number string.  The header is terminated by a NUL character, and the remainder of
     the file contains object data.  Loose objects files are compressed with deflate(3).

     Multiple objects can be bundled in a pack file for better disk space efficiency and
     increased run-time performance.  The pack file format introduces two additional types of
     objects:

     Offset Delta Objects
             This object is represented as a delta against another object in the same pack file.
             This other object is referred to by its offset in the pack file.

     Reference Delta Objects
             This object is represented as a delta against another object in the same pack file.
             The other object is referred to by its SHA1 object identifier.

     Pack files are self-contained and may not refer to loose objects or objects stored in other
     pack files.  Deltified objects may refer to other deltified objects as their delta base,
     forming chains of deltas.  The ultimate base of a delta chain must be an object of the same
     type as the original object which is stored in deltified form.

     Each pack file is accompanied by a corresponding pack index file, which lists the IDs and
     offsets of all objects contained in the pack file.

REFERENCES

     A reference associates a name with an object ID.  A prominent use of references is providing
     names to branches in the repository by pointing at commit objects which represent the
     current tip commit of a branch.  Because references may point to arbitrary object IDs, their
     use is not limited to branches.

     The name is a UTF-8 string with the following disallowed characters: ‘ ’ (space), ~ (tilde),
     ^ (caret), : (colon), ? (question mark), * (asterisk), [ (opening square bracket), \
     (backslash).  Additionally, the name may not contain the two-character sequences //, .. ,
     and @{.

     Reference names may optionally have multiple components separated by the / (slash)
     character, forming a hierarchy of reference namespaces.  Got reserves the refs/got/
     reference namespace for internal use.

     A symbolic reference associates a name with the name of another reference.  The most
     prominent example is the HEAD reference which points at the name of the repository's default
     branch reference.

     References are stored either as a plain file within the repository, typically under the
     refs/ directory, or in the packed-refs file which contains one reference definition per
     line.

     Any object which is not directly or indirectly reachable via a reference is subject to
     deletion by Git's garbage collector or gotadmin cleanup.

FILES

     HEAD         A reference to the current head commit of the Git work tree.  In bare
                  repositories, this files serves as a default reference.
     ORIG_HEAD    Reference to original head commit.  Set by some Git operations.
     FETCH_HEAD   Reference to a branch tip commit most recently fetched from another repository.
     branches/    Legacy directory used by the deprecated Gogito Git interface.
     config       Git configuration file.  See git-config(1).
     description  A human-readable description of the repository.
     got.conf     Configuration file for got(1).  See got.conf(5).
     hooks/       This directory contains hook scripts to run when certain events occur.
     index        The file index used by git(1).  This file is not used by got(1), which uses the
                  got-worktree(5) file index instead.
     info         Various configuration items.
     logs/        Directory where reflogs are stored.
     objects/     Loose and packed objects are stored in this directory.
     packed-refs  A file which stores references.  Corresponding on-disk references take
                  precedence over those stored here.
     refs/        The default directory to store references in.

     A typical Git repository exposes a work tree which allows the user to make changes to
     versioned files and create new commits.  When a Git work tree is present, the actual
     repository data is stored in a .git subfolder of the repository's root directory.  A Git
     repository without a work tree is known as a “bare” repository.  got(1) does not make use of
     Git's work tree and treats every repository as if it was bare.

SEE ALSO

     got(1), gotadmin(1), deflate(3), SHA1(3), got-worktree(5), got.conf(5)

HISTORY

     The Git repository format was initially designed by Linus Torvalds in 2005 and has since
     been extended by various people involved in the development of the Git version control
     system.

CAVEATS

     The particular set of disallowed characters in reference names is a consequence of design
     choices made for the command-line interface of git(1).  The same characters are disallowed
     by Got for compatibility purposes.  Got additionally prevents users from creating reference
     names with a leading - (dash) character, because this is rarely intended and not considered
     useful.