GitQuest

• 

  01-boot.png

• 

  02-select.png

• 

  06-conflict.png

• 

  05-diverge.png

• 

  04-win.png

• 

  07-final-win.png

Inspiration

Every developer remembers their first week with Git — the wall-of-red errors, the cryptic man pages, the fear of typing the wrong flag into a repo you care about. Tutorials hand you commands to memorize, not a mental model to build. For a hackathon called FirstCommit, we wanted to build the thing we wish we'd had on day one: a game where your first commit is literally the first level, and where breaking things is not only safe — it's the point.

What it does

GitQuest is a terminal-styled browser game that teaches Git by letting you play it. You type real git commands into a mock terminal — git add, git commit, git switch, git merge, git rebase, git push — and a live SVG commit graph draws itself beside you in real time.

• 11 levels: from git init through branching, merging, resolving a real merge conflict with markers, tagging, rebasing, reset --hard time travel, and pushing to a fake remote.
• Target graph per level — win when your repo's structure matches, not when you type the magic keystrokes. Any valid history wins.
• Safety nets for beginners: a undo meta-command that pops your last commit (even the root), automatic unreachable-commit garbage collection, and a warning the moment your history can no longer grow into the target.
• Git-golf star ratings: finish under par for ★★★ — but peeking at solution caps you at ★, because understanding beats copying.
• Sandbox mode, tab-completion, command history, hints, WebAudio bleeps, scanlines — the whole phosphor-terminal fantasy.

How we built it

Zero dependencies, no build step — vanilla HTML/CSS/JS with ES modules, deployed as a static site on GitHub Pages.

The heart is js/engine/git.js: a real Git state machine, not a scripted toy. It models commits, branches, HEAD (including detached), a staging area, merge bases, fast-forward vs. true merges, conflict markers, rebases, tags, and a fake remote — so everything you learn transfers to the real tool. js/ui/graph.js renders the DAG with a hand-rolled lane-assignment layout like git log --graph. js/engine/check.js decides wins by structural graph equality (DAG isomorphism over commit topology, branches, HEAD, tags and remote state), with a strict file-content mode only for the level where content is the lesson.

It also tests itself: npm test runs 51 engine/level assertions in node — including a proof that every level is solvable — and npm run playtest drives headless Firefox through all 11 levels and every button: 31 checks, plus screenshots. The demo video was produced the same way — a scripted headless-browser pipeline (demo-recorder) with generated slides and TTS narration.

Challenges we ran into

• The win condition was wrong twice. First, exact file matching punished players for using notes.txt instead of README.md — the history was structurally right and we still said "no." We split checking into topology (always) vs. strict content (only where it matters). Lesson: be strict where the pedagogy demands it, flexible everywhere else.
• Beginners got stuck permanently. A stray commit before git init'd correctly could make a level unwinnable with no way back. We added commit GC, undo that works on the root commit, and a divergence detector that warns the moment recovery becomes impossible — so a mistake costs you one keystroke, not the level.
• Merge conflicts had to be real but fair. Simulating merge, conflict markers, and resolution staging correctly enough to teach — while keeping it forgiving — took the most iterations (and a regression test for the "staged but markers still in the file" edge case).

Accomplishments that we're proud of

• A real merge conflict, resolved by you, in a tutorial that fits in a browser tab.
• 82 automated checks — every level provably solvable, plus a headless browser that plays the whole game itself and screenshots it.
• The diverge-warning + undo system: the game doesn't just let you fail, it notices when you've wandered somewhere unrecoverable and hands you the rope back.
• Zero dependencies. git clone, python3 -m http.server, done.

What we learned

• How Git actually works under the hood — you can't fake merge bases, detached HEAD, or conflict resolution without understanding them first.
• That forgiveness mechanics are the pedagogy: the ability to safely undo is what turns fear of the terminal into willingness to experiment.
• Topological equivalence checking vs. literal matching — and when each is the honest answer.

What's next for GitQuest

• More levels: stash, cherry-pick, revert, interactive rebase, remotes that push back (fetch/pull with divergence).
• Custom level sharing — the engine already supports arbitrary start/goal graphs; a URL-encoded level format would make every level a puzzle you can send to a friend.
• Localization and a proper mobile layout.
• Smarter hints that read your actual repo state, not just the level number.

Built With

• css3
• education
• game
• git
• html5
• javascript
• playwright
• svg
• web-audio-api