Skip to content
Get packs

Guide · Open source

How to use learnGitBranching: levels, sandbox and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

learnGitBranching is an open-source, browser-based tutorial that draws your git repository as a commit tree and updates the diagram each time you type a command. It is aimed at people who find git hard to picture from the command line alone. After this guide you will know how to use sandbox mode, work through levels, and use a few built-in commands to test and share what you have learned.

LearnGitBranchingpcottle/learnGitBranching · ★ 34.2k · MIT

Quick start

  1. 1Open the app. Go to https://pcottle.github.io/learnGitBranching/. It starts in sandbox mode with a basic repository.
  2. 2Type a command. Enter a git command in the input and watch the commit tree update to show its effect.
  3. 3Use undo and reset. Run undo to reverse the last command, or reset to start the repository over.
  4. 4List the levels. Type levels to see the available lessons and which ones you have solved.
  5. 5Solve a level. Work through a level using git commands, and try to use fewer commands for git golf.
  6. 6Share or report. Use the command URL parameter to share a setup, or run debug_copyTree() in the console when reporting a bug.

What learnGitBranching is and who it is for

LearnGitBranching is a git repository visualizer, sandbox, and series of tutorials and challenges. The project describes its main purpose as helping developers understand git through visualization, which the command line does not provide. It is a game with levels that introduce the different git commands.

It suits beginners who want to see what commands do to commits and branches, developers who want to fill gaps in branching, rebasing or remote workflows, and instructors demonstrating git to a class. It is not a replacement for a real git client, and it is not a full reference manual of every git command.

Open learnGitBranching in your browser

The app runs in the browser with no install step needed for the hosted version. The project's homepage is https://pcottle.github.io/learnGitBranching/, and a quick demo is available at the ?demo address on the same site. The app is a 100% clientside JavaScript application with no backend database or AJAX requests, so your work stays in the page.

If you want to run it yourself, the README includes a Docker command that serves the most recently built image on port 8080.

  • Open the homepage to start in sandbox mode
  • Use the ?demo link for a short demo first
  • Docker: serve the image on port 8080 and visit http://localhost:8080/
docker run -p 8080:80 ghcr.io/pcottle/learngitbranching:main

Use sandbox mode to experiment

By default the app launches in sandbox mode with a basic repository already created. You can enter commands and try things as often as you like. Three commands are worth knowing from the start: undo reverses the effects of the last command, reset starts over with a clean slate (and works in levels too), and git fakeCreateRemote simulates creating a remote repository.

Sandbox mode is useful for demonstrating something to a friend, but the project notes that the real learning happens in the levels.

  • undo: reverse the last command
  • reset: start over with a clean repository
  • git fakeCreateRemote: simulate a remote repository

Work through levels and git golf

Type levels to see the available lessons and challenges, along with which ones you have solved. Each level series aims to teach a high-level git concept, and each tab separates a major group of material, such as remote repositories versus local ones.

The app includes a git golf concept that counts how many commands you use to solve each level. You can try to match the project's records by using fewer commands.

  • Type levels to list lessons and see your progress
  • Use reset if you get stuck inside a level
  • Try to lower your command count in git golf
levels

Share a setup or report a bug

You can share a link that runs a set of commands on load using the command URL parameter. The README suggests adding the NODEMO parameter to skip the intro dialog. The README's example link uses echo and git commit as the starting commands.

To report a bug, the README suggests running debug_copyTree() in the JavaScript console just before the bug happens. That avoids copying every command you used to reach the state. The maintainer can then use importTreeNow to reach the same state.

  • command URL parameter: run commands on load
  • NODEMO URL parameter: skip the intro dialog
  • debug_copyTree(): copy the current tree state for a bug report
https://learngitbranching.js.org/?NODEMO&command=echo%20%22hello%22;%20git%20commit

Build your own level (optional)

Run the build level command to create your own level. A dialog walks you through the steps and ends with a JSON blob representing the level. You can paste that JSON into a gist or an issue for the maintainer to review, or have a friend run import level and paste it into the text field.

To contribute code, the README describes cloning your fork, running yarn install, and using yarn dev for a live-reload server. It also lists yarn build, yarn test and yarn lint.

  • build level: create a custom level with a guided dialog
  • import level: load a level someone else shared
  • yarn test runs the Jasmine test suite; yarn lint runs ESLint
git clone https://github.com/pcottle/learnGitBranching

What people use it for

  • Watching how git commit, branch and merge change the commit tree
  • Practising branching and rebasing in a safe sandbox
  • Demonstrating git concepts to a class or friend
  • Sharing a starting state with a link using the command parameter
  • Building a custom level with build level and sharing its JSON

Frequently asked questions

Is learnGitBranching free?

The project is released under the MIT licence, and the README describes it as an open-source app. The hosted version runs in the browser and the source is on GitHub.

What do I need to run learnGitBranching?

The README lists no prerequisites for using the web app. You open the homepage in a browser. Running it locally involves tools like yarn for development, which the README mentions for contributors.

How do I install learnGitBranching?

For the hosted version, you open https://pcottle.github.io/learnGitBranching/ and nothing needs installing. To get the source, the README uses git clone https://github.com/pcottle/learnGitBranching. You can also run the Docker image on port 8080 as shown in this guide.

Can learnGitBranching replace a real git client?

No. The project describes it as a tutorial and sandbox, not a tool for managing your own repositories. Use a real git client for daily work.

Is learnGitBranching a full git reference manual?

No. The README describes it as a game with levels rather than documentation of every git command. Use a reference manual alongside it for complete command details.

What are the alternatives to learnGitBranching?

The source material for this page does not name comparable projects, so this guide does not make a comparison. Look at the project's README and the wider git learning resources to compare options.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

learnGitBranching is a good choice if you want to see how git commands change commits and branches, or if you teach git and need a visual demo. It is not the right tool for managing real repositories or for looking up command syntax, so pair it with a real git client and a reference manual.

Install options & downloads