The Git Expert's Handbook

Rina hit a wall when her CI job failed with a message that looked like a permissions problem, but the root cause turned out to be simpler: she had one repository where `.git` came from a previous checkout and another repo where it came from a fresh clone. Two repos, same remote URL, wildly different internal state. When you understand what lives inside `.git`, you stop guessing and start inspecting. That’s the difference between “try again” and “fix the exact thing that’s wrong.”

At the center of this chapter sits .gitdir (the directory Git uses to store repository data, usually named `.git`). Inside it, Git keeps objects (content and history), references (names like `main`), and working state (what you staged and what you stashed). You don’t need to delete anything to learn this - you need to read it, verify it, and connect each file to the behavior you already know from Git commands.

How to Read the Repository Anatomy Map in `.git`

Think of a Git repository as a warehouse with three big zones: storage, bookkeeping, and working paperwork. Git’s internal structure matches that idea closely.

• Object database: Git stores data as objects addressed by a hash (a fingerprint). You can treat it like a content-addressed file store: the hash tells you what the content is, not where it came from.
• References: Git stores branch and tag names as pointers to specific commits. If you move a branch, you update a reference; you don’t rewrite the commit objects themselves.
• Working state: Git tracks your local staging and temporary work so you can commit, switch, and recover without losing changes.

In Git internals, you’ll see these key terms repeatedly:

• Blob: a stored snapshot of file content (the bytes of a file as they existed at a commit).
• Tree: a stored directory listing (it records filenames and points to blobs and other trees).
• Commit: a stored record of history (it points to a tree, references parent commits, and includes metadata like author info and the commit message).
• Index (Index file): the staging area on disk; it holds the “what you plan to commit next” view.
• HEAD: a special reference that tells Git which commit your current branch name resolves to (or which detached commit you checked out).
• packfiles: a storage format Git uses to pack many objects together efficiently, plus .idx indexes to locate objects quickly.

Now map those ideas onto the real `.git` layout you’ll inspect on disk. Run this from the repo root:

ls -la .git
# Shows the top-level .gitdir contents: objects, refs, HEAD, config, index, etc.

If you work with worktrees or submodules, you might also see `.git` as a file that points elsewhere. If `.git` is a file, read it:

cat .git
# If it says "gitdir: /path/to/actual/.git", follow that path.

Ask yourself one quick question before you proceed: when you run `git status` and it says you have staged changes, which file does Git update - your working directory files, or something under `.git`? The answer drives every inspection step in this chapter.

Breaking It Down: The Complete `.git` Folder Structure You Actually Need

Here’s the concrete layout you’ll commonly find in a non-bare repo. Exact contents vary by Git version and features, but the following components explain the core behaviors you see daily.

Top-level files: config, HEAD, index, and friends

• `config`: repository-specific settings (remote URLs, branch tracking info, hooks). Git reads this constantly; changes here alter how commands behave.
• `HEAD`: the current “where am I pointing?” marker. It usually contains something like `ref: refs/heads/main` or a raw commit hash in detached mode.
• `index`: the staging area. Git uses it to compute what will go into the next commit.
• `ORIG_HEAD`: Git uses this to remember the previous HEAD in some operations (handy when you need a fallback).
• `logs/`: reflog history - what moved, when. You’ll use it for recovery later.

Inspect them:

cat .git/HEAD
# See whether you're on a branch (ref: ...) or detached (hash directly).

git rev-parse --git-path index
# Prints the on-disk path to the index file Git uses.

ls -la .git/logs
# Reflogs live here; they record reference movement over time.

If you ever wondered why `git status` stays fast, it’s because Git can read the index and compare it to your working tree without scanning all history.

`objects/`: where blobs, trees, commits, and other internals live

Inside `.git/objects/`, Git stores the object database.

• `objects/??/????...` loose objects: individual objects stored as compressed files, typically when they haven’t been packed yet.
• `objects/pack/`: packed object storage. You’ll see files like:
• `pack-.pack`
• `pack-.idx`
• sometimes `pack-.promisor` in partial clone setups

List the pack directory:

ls -ლა .git/objects/pack
# Look for .pack and .idx files....