Skip to content
Tutorials Center
My learning

Topics

Lesson 44 of 78 ยท Git Internals

References, HEAD and the .git Directory

Learn how branches, tags and HEAD are just files in .git. Read refs by hand, use update-ref and symbolic-ref, understand packed-refs and tour the .git directory.

In the previous lesson you saw that Git objects are immutable and named by hash. A hash such as 9eb4236... is not something people want to remember, so Git adds a second layer: references (refs). A ref is a human-friendly name that holds one object ID. main, v1.0, origin/main and HEAD are all refs. Objects never change; refs are the things that move.

The surprise is how simple refs are. A branch is a text file with 41 bytes in it. Creating one is writing a line into a file, and deleting one is removing the file. In this lesson you will read and write refs with your bare hands, learn what HEAD really is, see how Git packs thousands of refs into one file, and take a guided tour of everything inside the .git directory.

A tour of the .git directory

Everything Git knows about your project lives in .git at the top of the working tree (delete it and the project is no longer a repository, but your files stay). Here is a freshly created repository with a single commit.

Bash What is inside .git

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The important parts are:

Path What it holds
HEAD Which branch (or commit) you currently have checked out
config Settings for this repository (remotes, branches, your local options)
description Used by old web viewers; ignore it
hooks/ Sample scripts that run at certain moments, see Git Hooks
info/exclude A private .gitignore that is not committed
objects/ The object database: loose objects and packfiles
refs/ Branches, tags and remote-tracking branches, one file per ref
index The staging area, see The Index and Packfiles
logs/ The reflogs (see The Reflog)
COMMIT_EDITMSG The last commit message you wrote

Other files appear while special operations run: MERGE_HEAD during a merge, ORIG_HEAD after risky moves, FETCH_HEAD after a fetch, packed-refs after garbage collection, rebase-merge/ during a rebase, shallow in shallow clones. They are all ordinary files you can read.

Branches and tags are files

A branch lives at .git/refs/heads/<name> and a tag at .git/refs/tags/<name>. The file contains a full object ID and a newline. That is the entire representation.

Bash Read a branch ref by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The branch file is 41 bytes: 40 hex digits plus a newline. The lightweight tag v1 holds the very same ID as main, since a lightweight tag is just a second name for a commit. The annotated tag file holds the ID of a separate tag object (as in the objects lesson).

Because refs are files, branch names with slashes become directories: feature/login is .git/refs/heads/feature/login. This also explains a classic limitation: you cannot have branches called feature and feature/login at the same time, since feature would have to be both a file and a directory. (Newer reftable storage removes this limit, see below.)

HEAD: the current position

HEAD is a ref too, but with a twist. Normally it does not contain an ID. It contains the name of another ref, written as ref: refs/heads/main. This is a symbolic reference. When you commit, Git follows HEAD to the branch, writes the new commit's ID into that branch file, and HEAD itself stays unchanged. Switching branches only rewrites the one line in HEAD.

In a detached HEAD state, HEAD contains a raw commit ID instead: you are standing on a commit that no branch follows. See Branches for the user-level view.

Bash HEAD is a symbolic ref, and what detached means

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git symbolic-ref HEAD prints the branch HEAD points to, and fails with fatal: ref HEAD is not a symbolic ref when it is detached. Scripts use that failure to detect a detached state. git rev-parse --abbrev-ref HEAD prints the branch name, or the word HEAD when detached.

Moving refs safely: update-ref and symbolic-ref

You can edit ref files by hand (the previous TryIt just read them), but Git offers plumbing commands that also handle locking, reflogs and packed refs:

  • git update-ref <ref> <id> creates or moves a ref. Add -m "message" to put text in the reflog, and a third argument <old-id> to make the update fail when the ref is not what you expect (compare-and-swap).
  • git update-ref -d <ref> deletes a ref.
  • git symbolic-ref <name> <target> makes a symbolic ref, for example git symbolic-ref HEAD refs/heads/other to point HEAD at a branch that does not exist yet.
  • git show-ref lists all refs with their IDs, git for-each-ref does the same with formatting and sorting.
Bash Create, move and delete refs with plumbing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The compare-and-swap form is what makes git push --force-with-lease possible: "move this ref, but only if it is still where I last saw it". Hosting servers use the same idea to reject conflicting pushes.

Namespaces under refs/

All refs are organised by prefix. The most important ones:

TEXT
refs/heads/<name>              local branches
refs/tags/<name>               tags
refs/remotes/<remote>/<name>   remote-tracking branches (origin/main)
refs/stash                     the newest stash (older ones are in its reflog)
refs/notes/<name>              git notes
refs/replace/<id>              object replacements (advanced)

Short names such as main or origin/main are expanded using a lookup order: Git tries <name>, refs/<name>, refs/tags/<name>, refs/heads/<name>, refs/remotes/<name> and refs/remotes/<name>/HEAD, and uses the first that exists. If a tag and a branch share a name Git warns you about the ambiguity; use the full refs/heads/x to choose.

Bash Remote-tracking refs and special refs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

origin/HEAD is a symbolic ref too: it names the remote's default branch, so origin alone means origin/main. The -u flag stored the tracking configuration in .git/config; the tracking branch files refs/remotes/origin/main and refs/remotes/origin/feature are updated by fetch and push, never by your commits. See Remotes and Transfer Protocols.

packed-refs: thousands of refs, one file

A repository with 20,000 tags would have 20,000 tiny files, which is slow on many file systems. git pack-refs --all (also run by git gc) moves refs into a single file, .git/packed-refs, one line per ref. The loose file wins when both exist; when you update a packed ref, Git writes a new loose file that overrides the packed line; deleting rewrites packed-refs.

Bash Pack refs into one file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first line of packed-refs is a comment about the file's capabilities; each other line is <id> <refname>. After the commit, refs/heads/main is loose again because it had to change.

Git 2.45 and later can store refs in a new reftable format (git init --ref-format=reftable). It keeps all refs in a binary table instead of files, which is faster and removes the file-versus-directory and case-insensitivity problems. The commands in this lesson work the same, but you can no longer cat a ref file. The classic "files" backend remains the default.

Special refs and pseudo-refs

Besides branches and tags, .git holds a few well-known names that Git itself maintains:

  • HEAD: the current branch or commit.
  • ORIG_HEAD: the old HEAD before a dangerous operation (reset, merge, rebase, pull). git reset --hard ORIG_HEAD is the quick undo.
  • FETCH_HEAD: what the last git fetch retrieved; git pull merges it.
  • MERGE_HEAD: the commit you are merging in, present only while a merge is unfinished. git merge --abort uses it.
  • CHERRY_PICK_HEAD, REVERT_HEAD, REBASE_HEAD: similarly, the commit being applied while a conflicted operation is paused.

You can use all of them as revisions, for example git diff MERGE_HEAD. If you are in the middle of an operation and wonder what state you are in, ls .git tells you.

Bash MERGE_HEAD while a merge waits for you

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Why this matters in practice

Understanding refs explains many everyday facts:

  • Branches are cheap, because creating one writes 41 bytes.
  • Deleting a branch loses no commits, only the name; see the Reflog for recovery.
  • A branch "contains" what its tip reaches, nothing more; commits do not know which branches include them.
  • HEAD moves in two ways: with the branch it follows (commit), or alone (switching).
  • Corruption stories like fatal: bad object refs/heads/x or an empty ref file after a crash are easy to repair once you know a ref is just a file with an ID.
  • Scripts can read the current branch with git symbolic-ref --short -q HEAD, loop over refs with for-each-ref, and update refs atomically with update-ref.

Do not edit files in .git by hand in real projects when a Git command exists for the job. Hand-written refs bypass locking and reflogs, and a typo in HEAD can make Git think the directory is not a repository. Use update-ref and symbolic-ref instead, and make a copy of the folder before experimenting.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the file .git/refs/heads/main contain?

    A branch file stores a single object ID. Git walks parents from that commit to find the rest of the history.
  2. 2. In a normal state (on a branch), what does .git/HEAD contain?

    HEAD points to a branch by name. When you commit, the branch file is updated and HEAD stays as it is. Only a detached HEAD holds a raw commit ID.
  3. 3. Which command moves or creates a ref safely, with locking and an optional reflog message?

    update-ref is the plumbing command for creating, moving (with an optional expected old value) and deleting refs.
  4. 4. What is packed-refs for?

    git pack-refs (and gc) moves refs into a single file. A loose file for the same ref overrides the packed line.
  5. 5. You are in the middle of a conflicted merge. Which file in .git records the commit you are merging in?

    MERGE_HEAD exists only while a merge is unfinished and names the other parent of the future merge commit.

Summary

  • Refs are named pointers to objects; branches (refs/heads), tags (refs/tags) and remote-tracking branches (refs/remotes) are plain files holding an object ID.
  • HEAD is normally a symbolic ref (ref: refs/heads/main); when it holds a raw ID you are in detached HEAD state.
  • git update-ref, git symbolic-ref, git show-ref and git for-each-ref read and write refs safely.
  • packed-refs stores many refs in one file; loose files override it, and the new reftable backend replaces files entirely.
  • ORIG_HEAD, FETCH_HEAD, MERGE_HEAD and friends are helper refs that mark the state of an operation.
  • The .git directory holds config, objects, refs, the index, reflogs and hooks; all are readable files.

Next: The Index, Packfiles and Garbage Collection