PyGit

Build your own version control system from scratch!

PyGit is a simplified version of Git, written entirely in Python. It teaches you how version control really works under the hood -- hashing, blobs, trees, commits, branches, and diffs -- by building each piece yourself.

What is version control?

Imagine you are writing a story. Every time you finish a chapter, you save a copy so you can go back to it later. Version control does the same thing for code -- it remembers every change you make, who made it, and why.

Quick start

from pygit.repository import Repository

# Create a new repository
repo = Repository.init("my-project")

# Create a file and stage it
with open("my-project/hello.txt", "w") as f:
    f.write("Hello, world!")

repo.add("hello.txt")

# Commit the change
commit_hash = repo.commit("Add greeting")
print(f"Created commit: {commit_hash}")

# Make another change
with open("my-project/hello.txt", "w") as f:
    f.write("Hello, everyone!")

repo.add("hello.txt")
repo.commit("Update greeting")

# See the history
for entry in repo.log():
    print(f"{entry.commit_hash[:8]} {entry.message}")

Features

• Hashing -- Every piece of content gets a unique fingerprint using SHA-1, with Git's blob <size> label in front -- so file (blob) hashes match git hash-object exactly. (Trees and commits use a simpler JSON layout than real Git, so their hashes differ.)
• Nested trees -- Every folder gets its own tree, just like real Git.
• Object store -- Files are stored by their hash, so identical content is never duplicated.
• Trees -- Snapshots of your directory structure, like a table of contents.
• Commits -- Diary entries that record what changed, when, and why. Each commit points to its parent, forming a chain of history.
• Branches -- Create parallel timelines to work on different ideas without affecting the main project.
• Staging area -- Choose exactly which changes go into the next commit.
• Diff -- Compare two versions of a file to see what was added or removed.
• Status -- See what files are staged and ready to commit.

Installation

uv sync --all-extras

Running tests

uv run pytest

Project structure

src/pygit/
    __init__.py      -- Package marker
    hashing.py       -- SHA-1 fingerprinting
    objects.py       -- Content-addressed object store
    tree.py          -- Directory snapshots
    commit.py        -- History entries
    diff.py          -- Line-by-line comparison
    repository.py    -- Ties everything together
    errors.py        -- Custom exceptions

Releasing

Other projects in the series (PyStack) use a pinned release of this one, not whatever is on main. To publish a change for them:

1. Merge the change to main.
2. Tag it: git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z. A change to the public API bumps the minor version (v0.1.0 → v0.2.0); anything else bumps the patch (v0.1.0 → v0.1.1).
3. In each project that uses it, edit the tag in [tool.uv.sources], run uv lock --upgrade-package <name>, and open a pull request so CI checks the pair together.

Related Projects

This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the series home for the full story.

Documentation

Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pygit/

License

MIT