Urgent.News

What's breaking now, across hundreds of outlets.

Tech

On Git Refs

Git Refs: A Deep Dive into Git's Key-Value Store and Branching System

I have recently improved my mental model of Git after learning that git is not just a content-addressable database, but also a mutable key-value store. Git stores commits as content-addressed objects identified by hash, but it also maintains a mutable map with string keys and content-addressed objects as values. This map is conventionally stored in the .git/refs directory, containing entries for branches, tags, and git notes.

The confusion arises from the key-value structure, where branch, tag, and git note entries are all just refs - symbolic names pointing to specific commits. To clarify, let's examine a fetch command: "git fetch [remote] [source]:[target]". The first argument is the remote repository's location, while the second argument is a source:target pair of string keys.

The source is a key on the remote repository, and the target is the name of a local key. Git saves this value locally under a different name, allowing you to avoid typing repository URLs all the time.

The symbolic name "origin" is conventionally used for the primary remote repository. When you list the .git/refs directory, you'll find refs/heads/master, which is the fully elaborated name of a branch on the remote repository. It could have been named refs/branch/master, but it isn't. Generally, you can spell only the suffix of a ref, such as refs/remotes/origin/master, which represents the local ref used to store the result of fetching data from the remote repository.

This structure might seem counterintuitive at first, especially when you consider that git is offline first and relies on explicit synchronization points. The remote branch state is stored as refs/remotes/origin/main, and when you synchronize your local repository with the remote, you receive refs/remotes/origin/main - your best current knowledge about the state of main on the origin.

Your local refs/heads/main typically points to the same commit as refs/remotes/origin/main, but advances when you make a commit. When pushing your local commit to origin, git automatically updates refs/remotes/origin/main, but you must update refs/heads/main and push it again if the main branch on the origin has advanced meanwhile.

Rewritten by urgent.news; may contain errors — check the original.

Read the original at matklad.github.io →

Report a problem with this story

More in Tech

More from Wednesday 7 October →