got/git-repository.5

   1 .\"
   2 .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate$
  17 .Dt GIT-REPOSITORY 5
  18 .Os
  19 .Sh NAME
  20 .Nm git-repository
  21 .Nd Git repository format
  22 .Sh DESCRIPTION
  23 A Git repository stores a series of versioned snapshots of a file hierarchy.
  24 Conceptually, the repository's data model is a directed acyclic graph which
  25 contains four types of objects as nodes:
  26 .Bl -tag -width commits
  27 .It Blobs
  28 The content of tracked files is stored in objects of type
  29 .Em blob .
  30 .It Trees
  31 A
  32 .Em tree
  33 object points to any number of such blobs, and also to other trees in
  34 order to represent a hierarchy of files and directories.
  35 .It Commits
  36 A
  37 .Em commit
  38 object points to the root element of one tree, and thus records the
  39 state of this entire tree as a snapshot.
  40 Commit objects are chained together to form lines of version control history.
  41 Most commits have just one successor commit, but commits may be succeeded by
  42 an arbitrary number of subsequent commits so that diverging lines of version
  43 control history, known as
  44 .Em branches ,
  45 can be represented.
  46 A commit which precedes another commit is referred to as that other commit's
  47 .Em parent commit .
  48 A commit with multiple parents unites disparate lines of history and is
  49 known as a
  50 .Em merge commit .
  51 .It Tags
  52 A
  53 .Em tag
  54 object associates a user-defined label with another object, which is
  55 typically a commit object.
  56 Tag objects also contain a tag message, as well as author and
  57 timestamp information.
  58 .El
  59 .Pp
  60 Each object is identified by an hash calculated over both the object's
  61 header and the data stored in the object.
  62 The hashing algorithm used is specified in the repository
  63 .Pa config
  64 file for newer repositories while older ones use SHA1 implicitly.
  65 .Sh OBJECT STORAGE
  66 Loose objects are stored as individual files beneath the directory
  67 .Pa objects ,
  68 spread across 256 sub-directories named after the 256 possible hexadecimal
  69 values of the first byte of an object identifier.
  70 The name of the loose object file corresponds to the remaining hexadecimal
  71 byte values of the object's identifier.
  72 .Pp
  73 A loose object file begins with a header which specifies the type of object
  74 as an ASCII string, followed by an ASCII space character, followed by the
  75 object data's size encoded as an ASCII number string.
  76 The header is terminated by a
  77 .Sy NUL
  78 character, and the remainder of the file contains object data.
  79 Loose objects files are compressed with
  80 .Xr deflate 3 .
  81 .Pp
  82 Multiple objects can be bundled in a
  83 .Em pack file
  84 for better disk space efficiency and increased run-time performance.
  85 The pack file format introduces two additional types of objects:
  86 .Bl -tag -width Ds
  87 .It Offset Delta Objects
  88 This object is represented as a delta against another object in the
  89 same pack file.
  90 This other object is referred to by its offset in the pack file.
  91 .It Reference Delta Objects
  92 This object is represented as a delta against another object in the
  93 same pack file.
  94 The other object is referred to by its object identifier.
  95 .El
  96 .Pp
  97 Pack files are self-contained and may not refer to loose objects or
  98 objects stored in other pack files.
  99 Deltified objects may refer to other deltified objects as their delta base,
 100 forming chains of deltas.
 101 The ultimate base of a delta chain must be an object of the same type as
 102 the original object which is stored in deltified form.
 103 .Pp
 104 Each pack file is accompanied by a corresponding
 105 .Em pack index
 106 file, which lists the IDs and offsets of all objects contained in the
 107 pack file.
 108 .Sh REFERENCES
 109 A reference associates a name with an object ID.
 110 A prominent use of references is providing names to branches in the
 111 repository by pointing at commit objects which represent the current
 112 tip commit of a branch.
 113 Because references may point to arbitrary object IDs, their use
 114 is not limited to branches.
 115 .Pp
 116 The name is a UTF-8 string with the following disallowed characters:
 117 .Sq \ \&
 118 (space),
 119 \(a~ (tilde),
 120 \(a^ (caret),
 121 : (colon),
 122 ? (question mark),
 123 * (asterisk),
 124 [ (opening square bracket),
 125 \\ (backslash).
 126 Additionally, the name may not contain the two-character sequences
 127 //, .. , and @{.
 128 .Pp
 129 Reference names may optionally have multiple components separated by
 130 the / (slash) character, forming a hierarchy of reference namespaces.
 131 Got reserves the
 132 .Pa refs/got/
 133 reference namespace for internal use.
 134 .Pp
 135 A symbolic reference associates a name with the name of another reference.
 136 The most prominent example is the
 137 .Pa HEAD
 138 reference which points at the name of the repository's default branch
 139 reference.
 140 .Pp
 141 References are stored either as a plain file within the repository,
 142 typically under the
 143 .Pa refs/
 144 directory, or in the
 145 .Pa packed-refs
 146 file which contains one reference definition per line.
 147 .Pp
 148 Any object which is not directly or indirectly reachable via a reference
 149 is subject to deletion by Git's garbage collector or
 150 .Cm gotadmin cleanup .
 151 .Sh FILES
 152 .Bl -tag -width packed-refs -compact
 153 .It Pa HEAD
 154 A reference to the current head commit of the Git work tree.
 155 In bare repositories, this file serves as a default reference.
 156 .It Pa ORIG_HEAD
 157 Reference to original head commit.
 158 Set by some Git operations.
 159 .It Pa FETCH_HEAD
 160 Reference to a branch tip commit most recently fetched from another repository.
 161 .It Pa branches/
 162 Legacy directory used by the deprecated Gogito Git interface.
 163 .It Pa config
 164 Git configuration file.
 165 See
 166 .Xr git-config 1 .
 167 .It Pa description
 168 A human-readable description of the repository.
 169 .It Pa got.conf
 170 Configuration file for
 171 .Xr got 1 .
 172 See
 173 .Xr got.conf 5 .
 174 .It Pa hooks/
 175 This directory contains hook scripts to run when certain events occur.
 176 .It Pa index
 177 The file index used by
 178 .Xr git 1 .
 179 This file is not used by
 180 .Xr got 1 ,
 181 which uses the
 182 .Xr got-worktree 5
 183 file index instead.
 184 .It Pa info
 185 Various configuration items.
 186 .It Pa logs/
 187 Directory where reflogs are stored.
 188 .It Pa objects/
 189 Loose and packed objects are stored in this directory.
 190 .It Pa packed-refs
 191 A file which stores references.
 192 Corresponding on-disk references take precedence over those stored here.
 193 .It Pa refs/
 194 The default directory to store references in.
 195 .El
 196 .Pp
 197 A typical Git repository exposes a work tree which allows the user to make
 198 changes to versioned files and create new commits.
 199 When a Git work tree is present, the actual repository data is stored in a
 200 .Pa .git
 201 subfolder of the repository's root directory.
 202 A Git repository without a work tree is known as a
 203 .Dq bare
 204 repository.
 205 .Xr got 1
 206 does not make use of Git's work tree and treats every repository as if it
 207 was bare.
 208 .Sh SEE ALSO
 209 .Xr got 1 ,
 210 .Xr gotadmin 1 ,
 211 .Xr deflate 3 ,
 212 .Xr SHA1 3 ,
 213 .Xr got-worktree 5 ,
 214 .Xr got.conf 5
 215 .Sh HISTORY
 216 The Git repository format was initially designed by Linus Torvalds in 2005
 217 and has since been extended by various people involved in the development
 218 of the Git version control system.
 219 .Sh CAVEATS
 220 The particular set of disallowed characters in reference names is a
 221 consequence of design choices made for the command-line interface of
 222 .Xr git 1 .
 223 The same characters are disallowed by Got for compatibility purposes.
 224 Got additionally prevents users from creating reference names with
 225 a leading - (dash) character, because this is rarely intended and
 226 not considered useful.