2 5e5560e1 2018-08-01 stsp .\" Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
4 5e5560e1 2018-08-01 stsp .\" Permission to use, copy, modify, and distribute this software for any
5 5e5560e1 2018-08-01 stsp .\" purpose with or without fee is hereby granted, provided that the above
6 5e5560e1 2018-08-01 stsp .\" copyright notice and this permission notice appear in all copies.
8 5e5560e1 2018-08-01 stsp .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 5e5560e1 2018-08-01 stsp .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 5e5560e1 2018-08-01 stsp .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 5e5560e1 2018-08-01 stsp .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 5e5560e1 2018-08-01 stsp .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 5e5560e1 2018-08-01 stsp .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 5e5560e1 2018-08-01 stsp .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 5e5560e1 2018-08-01 stsp .Dd $Mdocdate$
17 5e5560e1 2018-08-01 stsp .Dt GIT-REPOSITORY 5
20 5e5560e1 2018-08-01 stsp .Nm git-repository
21 4639d500 2018-08-01 stsp .Nd Git repository format
22 5e5560e1 2018-08-01 stsp .Sh DESCRIPTION
23 4639d500 2018-08-01 stsp A Git repository stores a series of versioned snapshots of a file hierarchy.
24 03301f46 2019-03-26 stsp Conceptually, the repository's data model is a directed acyclic graph which
25 03301f46 2019-03-26 stsp contains three types of objects as nodes:
26 03301f46 2019-03-26 stsp .Bl -tag -width Ds
28 5e5560e1 2018-08-01 stsp The content of tracked files is stored in objects of type
33 5e5560e1 2018-08-01 stsp object points to any number of such blobs, and also to other trees in
34 4639d500 2018-08-01 stsp order to represent a hierarchy of files and directories.
38 5e5560e1 2018-08-01 stsp object points to the root element of one tree, and thus records the
39 5e5560e1 2018-08-01 stsp state of this entire tree as a snapshot.
40 03301f46 2019-03-26 stsp Commit objects are chained together to form lines of version control history.
41 03301f46 2019-03-26 stsp Most commits have just one successor commit, but commits may be succeeded by
42 03301f46 2019-03-26 stsp an arbitrary number of subsequent commits so that diverging lines of version
43 03301f46 2019-03-26 stsp control history, known as
44 5e5560e1 2018-08-01 stsp .Em branches ,
45 5e5560e1 2018-08-01 stsp can be represented.
46 03301f46 2019-03-26 stsp A commit which precedes another commit is referred to as that other commit's
47 5e5560e1 2018-08-01 stsp .Em parent commit .
48 03301f46 2019-03-26 stsp A commit with multiple parents unites disparate lines of history and is
50 5e5560e1 2018-08-01 stsp .Em merge commit .
53 03301f46 2019-03-26 stsp Each object is identified by a SHA1 hash calculated over both the object's
54 4639d500 2018-08-01 stsp header and the data stored in the object.
55 4639d500 2018-08-01 stsp .Sh OBJECT STORAGE
56 4639d500 2018-08-01 stsp Loose objects are stored as individual files beneath the directory
57 4639d500 2018-08-01 stsp .Pa objects ,
58 4639d500 2018-08-01 stsp spread across 256 sub-directories named after the 256 possible hexadecimal
59 4639d500 2018-08-01 stsp values of the first byte of an object identifier.
60 e0486a23 2018-08-01 stsp The name of the loose object file corresponds to the remaining hexadecimal
61 e0486a23 2018-08-01 stsp byte values of the object's identifier.
63 4639d500 2018-08-01 stsp A loose object file begins with a header which specifies the type of object
64 4639d500 2018-08-01 stsp as an ASCII string, followed by an ASCII space character, followed by the
65 4639d500 2018-08-01 stsp object data's size encoded as an ASCII number string.
66 4639d500 2018-08-01 stsp The header is terminated by a
68 4639d500 2018-08-01 stsp character, and the remainder of the file contains object data.
69 4639d500 2018-08-01 stsp Loose objects files are compressed with
70 5e5560e1 2018-08-01 stsp .Xr deflate 3 .
72 4639d500 2018-08-01 stsp Multiple objects can be bundled in a
73 5e5560e1 2018-08-01 stsp .Em pack file
74 4639d500 2018-08-01 stsp for better disk space efficiency and increased run-time performance.
75 03301f46 2019-03-26 stsp The pack file format knows two additional types of objects in addition
76 03301f46 2019-03-26 stsp to blobs, trees, and commits:
77 03301f46 2019-03-26 stsp .Bl -tag -width Ds
78 03301f46 2019-03-26 stsp .It Offset Delta Objects
79 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
80 3d50f291 2019-03-26 stsp same pack file.
81 3d50f291 2019-03-26 stsp This other object is referred to by its offset in the pack file.
82 03301f46 2019-03-26 stsp .It Reference Delta Objects
83 3d50f291 2019-03-26 stsp This object is represented as a delta against another object in the
84 3d50f291 2019-03-26 stsp same pack file.
85 3d50f291 2019-03-26 stsp The other object is referred to by its SHA1 object identifier.
88 03301f46 2019-03-26 stsp Pack files are self-contained and may not refer to loose objects or
89 03301f46 2019-03-26 stsp objects stored in other pack files.
90 03301f46 2019-03-26 stsp Deltified objects may refer to other deltified objects as their delta base,
91 03301f46 2019-03-26 stsp forming chains of deltas.
92 03301f46 2019-03-26 stsp The ultimate base of a delta chain must be an object of the same type as
93 03301f46 2019-03-26 stsp the original object which is stored in deltified form.
95 03301f46 2019-03-26 stsp Each pack file is accompanied by a corresponding
96 03301f46 2019-03-26 stsp .Em pack index
97 03301f46 2019-03-26 stsp file, which lists the IDs and offsets of all objects contained in the
100 03301f46 2019-03-26 stsp .Bl -tag -width packed-refs -compact
101 5e5560e1 2018-08-01 stsp .It Pa HEAD
102 a3a2b44e 2019-03-26 stsp A reference to the current head commit of the Git work tree.
103 03301f46 2019-03-26 stsp In bare repositories, this files serves as a default reference.
104 5e5560e1 2018-08-01 stsp .It Pa ORIG_HEAD
105 a3a2b44e 2019-03-26 stsp Reference to original head commit.
106 a3a2b44e 2019-03-26 stsp Set by some Git operations.
107 5e5560e1 2018-08-01 stsp .It Pa FETCH_HEAD
108 18779d58 2019-05-10 jcs Reference to a branch tip commit most recently fetched from another repository.
109 5e5560e1 2018-08-01 stsp .It Pa branches/
110 f877d8eb 2019-03-26 stsp Legacy directory used by the deprectated Gogito Git interface.
111 5e5560e1 2018-08-01 stsp .It Pa config
112 03301f46 2019-03-26 stsp Git configuration file. See
113 03301f46 2019-03-26 stsp .Xr git-config 1 .
114 5e5560e1 2018-08-01 stsp .It Pa description
115 03301f46 2019-03-26 stsp A human-readable description of the repository.
116 5e5560e1 2018-08-01 stsp .It Pa hooks/
117 03301f46 2019-03-26 stsp This directory contains hook scripts to run when certain events occur.
118 5e5560e1 2018-08-01 stsp .It Pa index
119 03301f46 2019-03-26 stsp The file index used by
120 03301f46 2019-03-26 stsp .Xr git 1 .
121 03301f46 2019-03-26 stsp This file is not used by
122 03301f46 2019-03-26 stsp .Xr got 1 ,
123 03301f46 2019-03-26 stsp which uses the
124 03301f46 2019-03-26 stsp .Xr got-worktree 5
125 03301f46 2019-03-26 stsp file index instead.
126 5e5560e1 2018-08-01 stsp .It Pa info
127 03301f46 2019-03-26 stsp Various configuration items.
128 5e5560e1 2018-08-01 stsp .It Pa logs/
129 03301f46 2019-03-26 stsp Directory where reflogs are stored.
130 5e5560e1 2018-08-01 stsp .It Pa objects/
131 03301f46 2019-03-26 stsp Loose and packed objects are stored in this directory.
132 5e5560e1 2018-08-01 stsp .It Pa packed-refs
133 03301f46 2019-03-26 stsp A file which stores references.
134 a3a2b44e 2019-03-26 stsp Corresponding on-disk references take precedence over those stored here.
135 5e5560e1 2018-08-01 stsp .It Pa refs/
136 03301f46 2019-03-26 stsp The default directory to store references in.
139 4dfb2f0f 2019-03-26 stsp A typical Git repository exposes a work tree which allows the user to make
140 4dfb2f0f 2019-03-26 stsp changes to versioned files and create new commits.
141 4dfb2f0f 2019-03-26 stsp When a Git work tree is present, the actual repository data is stored in a
143 4dfb2f0f 2019-03-26 stsp subfolder of the repository's root directory.
144 4dfb2f0f 2019-03-26 stsp A Git repository without a work tree is known as a
146 4dfb2f0f 2019-03-26 stsp repository.
148 4dfb2f0f 2019-03-26 stsp does not make use of Git's work tree and treats every repository as if it
150 5e5560e1 2018-08-01 stsp .Sh SEE ALSO
151 5e5560e1 2018-08-01 stsp .Xr got 1 ,
152 5e5560e1 2018-08-01 stsp .Xr deflate 3 ,
153 4639d500 2018-08-01 stsp .Xr SHA1 3 ,
154 5e5560e1 2018-08-01 stsp .Xr got-worktree 5
155 5e5560e1 2018-08-01 stsp .Sh HISTORY
156 4639d500 2018-08-01 stsp The Git repository format was initially designed by Linus Torvalds in 2005
157 4639d500 2018-08-01 stsp and has since been extended by various people involved in the development
158 4639d500 2018-08-01 stsp of the Git version control system.
