LearnGitBranching: a git simulator in the browser, with a yarn-only build and a clean target that does nothing

It models git in the browser: no backend, no AJAX, one HTML page

The technical description is short and worth taking literally. There is no backend database and there are no AJAX requests. It is a 100 percent clientside application written in JavaScript, and the production version on github.io serves an HTML page with some JavaScript and CSS. The homepage field in the manifest points at a custom domain, learngitbranching.js.org, and the repository carries a CNAME file and a netlify.toml alongside a Dockerfile, so the same build is servable in several ways.

What that means for the teaching is precise. The thing on screen is a visualisation of a repository, and the commands you type are interpreted by the application's own model of git. As commands are processed, the nearby commit tree updates dynamically to reflect the effects of each command.

So this is a simulator, not a client. Nothing you type reaches a working repository, and a command that behaves subtly differently in your real git is not going to be caught here. The value is that you can type fast, break things, and watch the graph answer back, which is exactly what the command line cannot show you.

Sandbox mode hands you undo, reset and a remote that does not exist

The application launches in sandbox mode with a basic repository already created, and three commands make it safe to play in. `undo` reverts the effects of the last command, `reset` starts over with a clean slate, and it works in levels as well as in the sandbox. `git fakeCreateRemote` simulates creating a remote repository, which is how you get a second side to push to without leaving the page.

Those three are the whole safety net, and they are what makes the app worth opening before the levels. A command that surprises you costs one `undo`, and a state that is thoroughly confusing costs one `reset`.

The name fake in that third command is the honest part. The remote is a construct inside the page, so a level about remotes teaches you how the model is supposed to behave, not how your hosting provider will answer. Keep that distinction in mind when the levels start talking about push, fetch and remote tracking branches.

The levels are the course, and git golf is how you are scored

Type `levels` to see the available lessons and challenges, and which ones you have already solved. Each level series aims to teach one high-level git concept, and the levels are arranged in tabs that separate major worlds of information, remote repositories on one side and local operations on the other.

The scoring is command count. There is a git golf concept where the app keeps track of how many commands you used to solve each level, and the project asks you to see whether you can match its records. That is a small design decision with a real effect: it rewards a direct solution over an exploratory one, which is a different lesson from a tutorial that only cares whether you eventually get there.

The README is candid about the relationship between the two modes, saying that sandbox mode can be great for demonstrating something to a friend but that the real learning is with the levels. Treat the sandbox as the shop window and the levels as the course.

A command parameter turns any session into a link that runs on load

Any set of commands can be shared as a URL. The `command` query parameter takes the commands and executes them when the page loads, and the `NODEMO` parameter disables the intro dialog so the recipient lands on the content instead. The example given is a link that echoes a string and then makes a commit.

That is the feature that makes the app good for teaching other people, and it is also the one to treat carefully. A link you did not write executes a scripted sequence of commands the moment it opens, and the README offers no confirmation step and no sandbox boundary around it. Nothing reaches your filesystem, since the application is clientside, but the state you land in is chosen by the sender, and a shared link is indistinguishable from one that arrived from a stranger.

For your own bug reports there is a related tool. Run `debug_copyTree()` in the JavaScript console just before a bug reproduces, and the maintainer can use `importTreeNow` to reach that exact state instead of replaying your command history by hand.

build level produces a JSON blob that can live in a gist or an issue

Levels are not only shipped by the maintainer. The `build level` command opens a dialog that walks you through building one, and at the end it shows a JSON blob representing the level you just made. That blob is the whole deliverable: paste it into a gist, or paste it directly into an issue.

Two sharing routes follow from it. A friend can run `import level` and paste the JSON into the resulting text field, or you can send a URL carrying the gist ID in a gist_level_id parameter, and the level loads from there. The example URL in the README shows the shape of that link.

The consequence is that levels are user supplied content, and the same caution as with permalinks applies: import JSON from someone you trust, or read it first, because the JSON is interpreted by the page you are already running. The project also ships generatedDocs and a docs:levels script that turns levels into documentation, which is how a level becomes part of the tutorial rather than a private puzzle.

preinstall checks the package manager, and build runs the tests first

The manifest settles the toolchain questions. The package manager is [email protected], the declared engine is Node 20.19.0 or newer, and the scripts begin with a preinstall that runs a package manager check. In practice that means npm is not the supported route into this repository.

The rest of the scripts show how seriously the build is gated. `generate` produces the level data, and the same script runs ahead of dev, of build and of test, so a level edit is regenerated in every workflow. The build script is a chain of yarn test, then vite build, then a postbuild step, which means the jasmine suite runs before any production output exists. A failing spec does not produce a warning, it stops the build. `lint` is ESLint across src, __tests__, scripts and the config files, `test:coverage` runs the same suite under nyc, and `lint:strings` exists because the app is translated.

For a local run, yarn install followed by yarn dev gives you the dev server with live reload at http://localhost:5173, and yarn build writes index.html and hashed assets into the ./build directory.

The Makefile requires PowerShell, and clean prints not implemented

The Docker path in the Makefile opens with a shell decision that catches people out. On Windows it sets SHELL to pwsh.exe, and on everything else it sets SHELL to pwsh, with .SHELLFLAGS as -NoProfile -Command. So the make targets drive PowerShell, not sh, and pwsh has to be on the path before make build will do anything.

The build target itself runs two throwaway containers rather than a local toolchain:

docker run --rm -v $${PWD}:/mnt --workdir /mnt node:20-alpine yarn install --frozen-lockfile
docker run --rm -v $${PWD}:/mnt --workdir /mnt node:20-alpine yarn build

The Dockerfile does the same thing in stages: a node:20-alpine build stage that installs with a frozen lockfile and ignores scripts, a scratch export stage, and a final nginx:stable-alpine stage that serves the exported files. The published image runs with `docker run -p 8080:80 ghcr.io/pcottle/learngitbranching:main`.

Two smaller notes. The clean target echoes not implemented, so make clean is a message rather than a cleanup, and it will leave build output and containers behind. And the test target depends on build, so asking make test builds the app first.

Editorial conclusion

Use LearnGitBranching to build the mental model of the commit graph, to practise the commands until the shape of a merge or a rebase is obvious, and to send a colleague a permalink that reproduces a state exactly. Do not use it to check what a command does to your real repository, because it models git rather than running it, and do not follow the build instructions with npm, because a preinstall script checks the package manager and expects [email protected] on Node 20.19 or newer. Before you build: remember that the production build runs the jasmine suite first, so a failing spec blocks it; that the Makefile needs PowerShell and prints not implemented for clean; and that a level or a permalink from someone else is content you did not write, so read the JSON behind it before importing.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository