I Built a Game That Teaches Git by Making You Type Real Commands

I work in IT, and there's one scene I keep witnessing. A developer joins the team, they're sharp, they ship features, they write clean code. And then someone asks them to rebase, and you can see the panic set in.

It's not their fault. Git is taught badly.

Every git tutorial I've ever seen follows the same formula: here's a diagram of branches, here's a table of commands, now go practice on your own repo and try not to destroy anything. It's like learning to drive by reading the car manual. Technically accurate. Practically useless.

I've watched junior developers memorize git add . && git commit -m "fix" && git push like an incantation, terrified to deviate because the one time they tried git rebase they ended up in a state that required a senior engineer and 45 minutes of git reflog to unfurl.

And I've watched senior developers, people with a decade of experience, avoid git bisect entirely because nobody ever showed them what it actually does in a safe environment.

So I built one.

Gitvana

Gitvana is a browser game. You play a monk climbing toward "git enlightenment" at the Monastery of Version Control. There's a Head Monk who assigns you tasks, a judgmental cat, and pixel art that looks like it belongs on a Game Boy.

But underneath the retro charm, there's a real git engine. When you type git init in the terminal, it runs git init. When you type git commit, it creates an actual commit in an actual repository. The repository lives in your browser, powered by isomorphic-git and an in-memory filesystem, but it's real. Every command, every SHA, every ref.

35 levels. 6 acts. 21 git commands. From git init to git bisect. No slides, no diagrams, no hand-holding. Just you and a terminal.

Play it at gitvana.pixari.dev. It's free, it works offline, and it doesn't want your email.

Why a Game

I could have written another tutorial. I could have built a sandbox. But I've been thinking a lot about how people actually learn, and the answer isn't "reading."

People learn by doing things that are slightly too hard, failing, figuring out why, and trying again. That's what games are. They're structured failure environments with feedback loops.

Every level in Gitvana has a target state, a set of conditions that the git repository must satisfy. "There must be exactly 3 commits on main." "The branch feature must be deleted." "The file config.yml must not contain the API key in any commit." The game validates these conditions in real time as you type commands. You see the checklist turn green, one objective at a time.

This isn't gamification bolted onto a tutorial. The game is the learning.

The Journey: 6 Acts

The structure mirrors how a developer actually encounters git:

Act 1: Awakening — The basics. init, add, commit, status, log, diff. You're a new monk. The Head Monk is patient. The cat is skeptical.

Act 2: The Middle Path — Branching, merging, cherry-pick, revert, stash. Things start getting interesting. You begin to understand that git isn't a linear timeline, it's a tree.

Act 3: Rewriting Reality — rebase, amend, squashing commits, purging secrets from history. This is where most developers tap out in real life. In Gitvana, you can't tap out. The monastery doors are locked.

Act 4: The Safety Net — reflog, blame, bisect, disaster recovery. The levels where you learn that git never truly forgets, and that reflog is the "undo" button nobody told you about.

Act 5: Advanced Techniques — Surgical staging, dependency chains, the operations that separate "uses git" from "understands git."

Act 6: Gitvana — The final trial.

Each act introduces new commands gradually, with in-game documentation you can pull up without leaving the terminal.

The Tech

The stack is deliberately minimal. Svelte 5 for the UI, xterm.js for the terminal, isomorphic-git for the git engine, and lightning-fs for the in-memory filesystem. No backend. No database. No accounts. Everything runs in your browser and your progress saves to localStorage.

The interesting engineering problems were all in the details:

Rebase was the hardest command to implement. The real git rebase is a multi-step, stateful operation. It collects commits, replays them one by one, and can pause mid-way for conflict resolution. I had to build a state machine that saves rebase progress to .git/rebase-merge/, handles --continue and --abort, and writes proper conflict markers when files clash.

Bisect maintains its own state files in .git/, just like real git. It performs an actual binary search across commits to find where a bug was introduced. In one level, you have to find which commit broke a test by using git bisect start, marking commits as good or bad, and letting the algorithm narrow it down.

The blame algorithm walks the entire commit history, builds a content-at-commit map, and attributes each line to the oldest commit where it appeared unchanged. It's not efficient. It doesn't need to be, these repos are tiny. But it's correct.

The level validator checks 12 types of conditions in real time: file existence, file content, branch existence, HEAD position, commit count, commit message patterns, merge commits, conflict state, staging area state, and tag existence. Every keystroke can potentially satisfy an objective, and the UI updates instantly.

Sound effects are procedurally generated with the Web Audio API. No audio files. Just oscillators, frequency envelopes, and square waves. Every commit gets a satisfying chiptune beep. Every merge conflict gets an ominous buzz.

What I Learned Building It

Building an educational game taught me more about git than 15 years of using it.

I had to read the git internals documentation to implement commands correctly. I discovered that git stash is essentially syntactic sugar over a specific commit-and-reset workflow. I learned that the reflog is just a flat file of HEAD movements. I finally understood, at the implementation level, why a detached HEAD happens and what it actually means in terms of refs.

There's a difference between using a tool and understanding it deeply enough to rebuild it. This project forced the second.

The Pixel Art Problem

I can't draw. At all. My artistic ability peaked at stick figures in 1993. But I wanted Gitvana to have a specific aesthetic: 16-bit monastery vibes, cherry blossoms, monks in robes, a cat that judges your commits.

I used PixelLab to generate the sprites. I'd describe what I wanted: "pixel art monk in grey robes, standing, 64x64, side view, retro game style" and iterate until it felt right. The landing page monastery, the mountain progression map, the four monk tiers (grey, brown, blue, golden) were all generated this way.

It's not hand-crafted pixel art. But it has soul. And it's consistent, which matters more than perfection when you're a solo developer trying to ship something.

Why It's Free

Because I built it for fun. That's the honest answer.

I had a problem: I wanted to understand git at the implementation level, not just the "copy this command from Stack Overflow" level. Building a game that teaches it forced me to actually learn it. Selfish motivation, great side effect.

And maybe other people have the same problem. Maybe there's a developer out there who's been using git for five years and still gets nervous when someone says "rebase." If Gitvana helps them, great. If not, I still had a blast building it.

There's no paywall, no signup, no "premium" tier. The source code is on GitHub. It's MIT licensed. Fork it, improve it, translate it, add levels.

Try It

gitvana.pixari.dev

35 levels. Real terminal. Real git. Zero setup.

Start at Act 1. Get to Gitvana. The cat is waiting.

Originally published on pixari.dev