kmx git

.\"
.\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt GIT-REPOSITORY 5
.Os
.Sh NAME
.Nm git-repository
.Nd Git repository format
.Sh 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 three types of objects as nodes:
.Bl -tag -width Ds
.It Blobs
The content of tracked files is stored in objects of type
.Em blob .
.It Trees
A
.Em tree
object points to any number of such blobs, and also to other trees in
order to represent a hierarchy of files and directories.
.It Commits
A
.Em 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
.Em branches ,
can be represented.
A commit which precedes another commit is referred to as that other commit's
.Em parent commit .
A commit with multiple parents unites disparate lines of history and is
known as a
.Em merge commit .
.It Tags
A
.Em tag
object associates an user-defined label with another object, which is
typically a commit object.
Tag objects also contains a tag message, as well as author and
timestamp information.
.El
.Pp
Each object is identified by a SHA1 hash calculated over both the object's
header and the data stored in the object.
.Sh OBJECT STORAGE
Loose objects are stored as individual files beneath the directory
.Pa 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.
.Pp
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
.Sy NUL
character, and the remainder of the file contains object data.
Loose objects files are compressed with
.Xr deflate 3 .
.Pp
Multiple objects can be bundled in a
.Em pack file
for better disk space efficiency and increased run-time performance.
The pack file format knows two additional types of objects in addition
to blobs, trees, and commits:
.Bl -tag -width Ds
.It 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.
.It 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.
.El
.Pp
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.
.Pp
Each pack file is accompanied by a corresponding
.Em pack index
file, which lists the IDs and offsets of all objects contained in the
pack file.
.Sh 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.
.Pp
The name is a UTF-8 string with the following disallowed characters:
.Sq \ \&
(space),
\(a~ (tilde),
\(a^ (caret),
: (colon),
? (question mark),
* (asterisk),
[ (opening square bracket),
\\ (backslash).
Additionally, the name may not contain the two-character sequences
//, .. , and @{.
.Pp
Reference names may optionally have multiple components separated by
the / (slash) character, forming a hierarchy of reference namespaces.
Got reserves the
.Pa got/
reference namespace for internal use.
.Pp
A symbolic reference associates a name with the name of another reference.
The most prominent example is the
.Pa HEAD
reference which points at the name of the repository's default branch
reference.
.Pp
References are stored either as a plain file within the repository,
typically under the
.Pa refs/
directory, or in the
.Pa packed-refs
file which contains one reference definition per line.
.Pp
Any object which is not directly or indirectly reachable via a reference
is subject to deletion by Git's garbage collector.
.Sh FILES
.Bl -tag -width packed-refs -compact
.It Pa HEAD
A reference to the current head commit of the Git work tree.
In bare repositories, this files serves as a default reference.
.It Pa ORIG_HEAD
Reference to original head commit.
Set by some Git operations.
.It Pa FETCH_HEAD
Reference to a branch tip commit most recently fetched from another repository.
.It Pa branches/
Legacy directory used by the deprecated Gogito Git interface.
.It Pa config
Git configuration file.
See
.Xr git-config 1 .
.It Pa description
A human-readable description of the repository.
.It Pa hooks/
This directory contains hook scripts to run when certain events occur.
.It Pa index
The file index used by
.Xr git 1 .
This file is not used by
.Xr got 1 ,
which uses the
.Xr got-worktree 5
file index instead.
.It Pa info
Various configuration items.
.It Pa logs/
Directory where reflogs are stored.
.It Pa objects/
Loose and packed objects are stored in this directory.
.It Pa packed-refs
A file which stores references.
Corresponding on-disk references take precedence over those stored here.
.It Pa refs/
The default directory to store references in.
.El
.Pp
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
.Pa .git
subfolder of the repository's root directory.
A Git repository without a work tree is known as a
.Dq bare
repository.
.Xr got 1
does not make use of Git's work tree and treats every repository as if it
was bare.
.Sh SEE ALSO
.Xr got 1 ,
.Xr deflate 3 ,
.Xr SHA1 3 ,
.Xr got-worktree 5
.Sh 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.
.Sh CAVEATS
The particular set of disallowed characters in reference names is a
consequence of design choices made for the command-line interface of
.Xr 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.
thodg/got/got/git-repository.5

Commit

got/git-repository.5
