Simple VCS

Git is the correct answer for source code and the wrong answer for a person who just wants their file history back. The commands that matter to a beginner — "save this", "show me what I saved", "put it back the way it was" — are buried under staging semantics, detached HEADs, and a reflog you have to know exists before it can save you. People coping without it fall back to report_final_v2_actually_final.docx and a folder of dated ZIPs, which works right up until they need to know which copy was current on which day.

The second problem was mine: I wanted to actually understand how a version control system stores things, and reading about content-addressed objects is not the same as writing one and finding out where it leaks.

It had to be installable by someone who only has pip, so no database, no daemon, no compiled dependency — the entire store is plain files and JSON that a human can open in a text editor when something goes wrong. It had to run identically on Windows, macOS and Linux (the root [workflow.yml](workflow.yml) matrix covers all three), and Windows console encoding turned out to be the single most persistent source of breakage. pyproject.toml declares requires-python = ">=3.7", which rules out newer typing and pathlib conveniences. And it is a side project — the gaps between the three work bursts are five months and one month, so every design had to survive me forgetting all of it and coming back cold.

Two layers, deliberately thin. [cli.py](simple_vcs/cli.py) is Click and nothing else: each command constructs a SimpleVCS and calls one method. All state lives in [core.py](simple_vcs/core.py). The split exists so the same class is usable as a Python API — from simple_vcs import SimpleVCS — and the root workflow tests that path separately from the CLI path, asserting on the boolean return of every method. That is why every public method returns bool instead of raising: the return value *is* the API contract, and the Rich output is a side effect on top of it.

The store is content-addressed but only halfway. _calculate_file_hash reads in 4 KB chunks and produces a SHA-256; _store_object writes the bytes to .svcs/objects/<hash> and skips the write if that hash already exists, so re-committing an unchanged file costs nothing. But commits themselves are not objects — they are appended to a single commits.json array with a monotonic integer id, and HEAD is a text file containing that integer. I chose integers over commit hashes because svcs revert 3 is something a person can type from memory and svcs revert a5f62c6 is not. The cost is real and I knew it going in: a JSON array means the whole history is rewritten on every commit, and an integer counter derived from len(commits) + 1 means there is no safe way to grow branches. Diffing inherits the same tradeoff — show_diff compares the *file-hash sets* of two commits, so it reports added, deleted and modified plus a byte-size delta, but never line content. Storing whole blobs instead of deltas made that a design consequence, not an oversight.

I started this because I wanted to know what Git actually does when you type git add, and the fastest way to find out is to try to build the smallest thing that behaves the same. The first day produced most of what still exists — init, add, commit, log, diff, status — under plain print(), and it worked. Then it sat for five months.

What I got wrong early is visible in the git history and it is a little embarrassing. Six of my first seven commits are named "changes" or "complete", dist/ and __pycache__/ were committed for months, setup.py pointed at github.com/yourusername/simple-vcs for four days, and __init__.py credited "Your Name". Those are the marks of writing a package by filling in a template without reading it. The single worst one is the dropped parentheses in e62ec27 — one character, in a commit called "changes", that made python run_svcs.py a no-op for eight months and that I did not find until I came back in January 2026 to add features.

The moment it clicked was _store_object. Three lines: hash the content, write it under the hash, skip if it is already there. Deduplication, integrity and immutability all fall out of one idea, and I stopped thinking of Git's object store as machinery and started thinking of it as a consequence. Everything I like about this codebase is downstream of that afternoon.

The v1.2 rewrite was the other kind of learning. I spent a full session converting every print() to a Rich panel and it genuinely made the tool feel finished — but I put all of it in core.py, so the module that owns the storage format now also owns the border style of the commit table. Two versions later that decision has metastasized: utils.format_file_size is dead because ten methods each inline their own copy.

What I would do differently: write the tests. There is not a single test file in this repository, and the CI job that says "Test with pytest" runs bare pytest against zero tests — which pytest treats as an error, so that job has been failing rather than passing vacuously. The real testing lives in [workflow.yml](workflow.yml), which drives the CLI through a full init/add/commit/log/diff sequence in a temp directory and asserts on the Python API's return values. That file is a decent integration suite and it is sitting in the repo root instead of .github/workflows/, so GitHub has never run it. Moving it and writing real unit tests around _calculate_file_hash, quick_revert and the containment check in add_file is the first thing I would do on picking this back up — closely followed by either fixing compress or removing it.

Shipped as simple-vcs version 1.3.0 (Feb 2026), built into dist/simple_vcs-1.3.0-py3-none-any.whl and .tar.gz, installing a svcs console script. Ten commands: init, add, commit, status, log, diff, revert, snapshot, restore, compress. Both a CLI and an importable Python API, verified separately by the workflow in [workflow.yml](workflow.yml) across Python 3.7–3.12 on Ubuntu, Windows and macOS.

Version numbers are currently inconsistent across three files and that is a shipping defect, not a rounding error: pyproject.toml and setup.py say 1.3.0, click.version_option in [cli.py](simple_vcs/cli.py) says 1.3.0, the help footer four lines below it still prints Version 1.2.0, and simple_vcs/__init__.__version__ is still 1.1.0.

yml](workflow.yml) only fires on a GitHub release event, but there are no tags in this repo.

github/workflows/python-package.yml` pytest step is currently red on main; the repo has no test files, so it should be, but the run history is not in the tree.

Simple VCS is a fully functional version control system inspired by Git, built entirely from scratch in Python. It lets developers track file changes, commit history, and restore previous states without Git overhead.

Published on PyPI as simple-vcs (v1.3.0), it supports the core VCS workflow including init, add, commit, log, diff, and status commands. It features quick revert to any previous commit by ID, zip-based full project backups, and a rich terminal UI using the rich library. Cross-platform compatible with Windows and Unix.