GIT-REPOSITORY(5)

✨ GIT-REPOSITORY ✨ (section 5 of the manual, bestie)

okay so this is the git-repository page from the File Formats Manual, and it's literally the blueprint of what a Git repository IS. no cap, it's giving "backstage tour of the thing you use every single day" energy 💅

---

🎀 DESCRIPTION 🎀

A Git repository stores a whole series of versioned snapshots of a file hierarchy. Conceptually (iykyk, big word), the repo's data model is a directed acyclic graph — and that graph has four types of objects as its nodes. let's meet the girlies 👑

• Blobs — the actual content of your tracked files lives here, in objects of type blob. that's it, that's the vibe. the raw file content, no names, no drama.
• Trees — a tree object points to any number of those blobs, and also to other trees, so it can represent a hierarchy of files and directories. it's giving "folder structure but make it graph theory" 🌳
• 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 a commit may be succeeded by an arbitrary number of subsequent commits — so diverging lines of history, aka branches, can be represented. a commit which precedes another commit is that other commit's parent commit. a commit with multiple parents unites disparate lines of history and is called a merge commit. iconic behavior honestly.
• Tags — a tag object associates a user-defined label with another object, typically a commit object. tag objects also contain a tag message, plus author and timestamp info. cute little nametag fr fr 🏷️

every single object is identified by a hash calculated over both the object's header and the data stored in the object. the hashing algorithm used is specified in the repository config file for newer repositories, while older ones use SHA1 implicitly. periodt.

---

💾 OBJECT STORAGE 💾

Loose objects are stored as individual files beneath the objects directory, 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. (yes bestie, 256 folders, it's a whole aesthetic 🌈)

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 object 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 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. no shortcuts, no chaos, we keep it consistent 🫶

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. but because references may point to arbitrary object IDs, their use is not limited to branches. versatile queen 💅

The name is a non-empty UTF-8 string with the following disallowed characters:

• (space)
• ~ (tilde)
• ^ (caret)
• : (colon)
• ? (question mark)
• * (asterisk)
• [ (opening square bracket)
• \ (backslash)

The name may not be the string "@", may not begin with a / (slash), and may not begin or end with a . (period). additionally, the name may not contain the two-character sequences //, .., and @{.

🚨 that's a lot of nope, bestie. read the list twice before you name your branch, fr fr.

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.

💀 WARNING: any object which is not directly or indirectly reachable via a reference is subject to deletion by Git's garbage collector or gotadmin cleanup. so like… if it's not attached to anything, it's getting deleted. no thoughts, just garbage collection.

---

📁 FILES 📁

okay this is the tour of what actually lives in there:

• HEAD — a reference to the current head commit of the Git work tree. in bare repositories, this file 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. (so got is the low-maintenance bestie who skips the work tree entirely 💅)

---

👀 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. a whole glow-up arc, honestly 🌸

---

⚠️ 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.

💀 so a leading dash? got says absolutely not. it's giving "we don't do that here."

---

and that's the whole page, bestie 💖 this was section 5 of the File Formats Manual, from the Debian mdoc build (date placeholder $Mdocdate$, if you were wondering), and it's literally the origin story of every repo you've ever cloned. go forth and understand your objects 🦋✨