Repository: pcottle/learnGitBranching

Stars: 33352

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview Copy Chapter

LearnGitBranching is an interactive git visualization tool for teaching git concepts through a game-like interface. It's a 100% client-side JavaScript application that simulates git operations and renders them visually using Raphael.js for SVG graphics.

Build & Development Commands Copy Chapter

Setup Copy Section

yarn install

Building Copy Section

yarn gulp fastBuild    # Fast build without tests/linting
yarn gulp build        # Full production build with tests & lint
yarn gulp watching     # Watch mode - rebuilds on file changes

Testing & Linting Copy Section

yarn test              # Run Jasmine test suite
yarn test:coverage     # Run tests with nyc coverage
gulp jshint            # Run JSHint linter
gulp lintStrings       # Validate internationalization strings

Development Server Copy Section

yarn dev               # Start Vite dev server
After building, open index.html directly in browser

Single Test Execution Copy Section

Run specific test file

npx gulp-jasmine __tests__/git.spec.js

Architecture Overview Copy Chapter

Core Components Copy Section

GitEngine (src/js/git/index.js)
- The heart of the application - simulates all git operations
- Manages the commit graph, branches, tags, refs, and HEAD
- Processes commands and updates the visualization
- Supports both git and Mercurial (hg) modes via mode property
- Uses EventBaton pattern for command dispatching

Visualization System (src/js/visuals/)
- visualization.js: Main visualization controller
- tree.js: Renders the commit tree using Raphael.js
- visNode.js, visBranch.js, visTag.js, visEdge.js: Individual visual components
- animation/: Animation system using promise chains (Q library)

Command Processing (src/js/commands/index.js, src/js/git/commands.js)
- Commands are defined with regex patterns, options, and execute functions
- Supports both git and Mercurial command sets
- Command delegation system allows commands to internally invoke other commands
- All git commands are simulated - they manipulate in-memory data structures

Levels System (src/levels/)
- Each level is a JavaScript module exporting level configuration
- Organized into sequences: intro, rampup, move, mixed, advanced, remote, remoteAdvanced
- Level definition includes: name, goal description, starting tree state, solution validation
- See src/levels/index.js for all level sequences

Flux Architecture Copy Section

The app uses a Flux-like architecture:

Dispatcher (src/js/dispatcher/AppDispatcher.js)
- Central event bus using Facebook's Flux Dispatcher
- Handles VIEW_ACTION and URI_ACTION payload sources

Stores (src/js/stores/)
- CommandLineStore.js: Manages command line state
- LevelStore.js: Tracks current level and progress
- LocaleStore.js: Handles internationalization
- GlobalStateStore.js: Global application state

Actions (src/js/actions/)
- Action creators for CommandLine, Level, Locale, and GlobalState

UI Components Copy Section

Backbone Views (src/js/views/)
- Legacy Backbone.js views for modals, dialogs, builders
- gitDemonstrationView.js: Shows animated git command demonstrations

React Components (src/js/react_views/)
- Modern React components for command line, toolbar, helper bars
- Command history view with syntax highlighting

Key Patterns Copy Section

EventBaton (src/js/util/eventBaton.js)
- Pattern for transferring event handling responsibility
- Used extensively for command processing and level events

TreeCompare (src/js/graph/treeCompare.js)
- Compares two commit trees for level completion validation
- Handles branch positions, commit structure, tags

Animation Chains
- All visual updates go through animation queue
- Uses Q promises to chain animations
- Can be disabled for testing (headless mode)

Project Structure Copy Chapter

src/
├── js/
│   ├── app/           # Application bootstrapping
│   ├── git/           # Git engine and commands
│   ├── mercurial/     # Mercurial (hg) support
│   ├── commands/      # Command parsing and execution
│   ├── level/         # Level loading and validation
│   ├── visuals/       # Visualization and animation
│   ├── views/         # Backbone views
│   ├── react_views/   # React components
│   ├── stores/        # Flux stores
│   ├── actions/       # Flux actions
│   ├── models/        # Backbone models and collections
│   ├── intl/          # Internationalization
│   ├── graph/         # Tree comparison logic
│   └── util/          # Utilities
├── levels/            # Level definitions organized by category
├── style/             # CSS files
└── template.index.html # HTML template
__tests__/             # Jasmine test specs

Build Process Copy Chapter

The gulp build process:
1. Browserify bundles all JS files (including JSX with Babel transform)
2. CSS files concatenated and minified (production)
3. Files are hashed for cache busting
4. template.index.html is processed with hashed filenames to generate index.html
5. Tests run with Jasmine, linting with JSHint

Production builds minify JS with Terser and HTML with html-minifier.

Key Technologies Copy Chapter

- Backbone.js: MVC framework (legacy parts)
- React 17: UI components (modern parts)
- Flux: Unidirectional data flow
- Raphael.js: SVG graphics for visualization
- Q: Promises for animation chains
- jQuery/jQuery UI: DOM manipulation and dialogs
- Browserify + Babel: Module bundling and JSX transform
- Gulp: Build automation
- Jasmine: Testing framework

Testing Conventions Copy Chapter

- Tests in __tests__/ directory
- Headless git engine for testing (src/js/git/headless.js)
- Use create.js helper to set up test git trees
- Mock commands with mock.js utility
- Tests cover git operations, remote operations, levels, tree comparison

Remote Repository Simulation Copy Chapter

Remote operations (push/pull/fetch) are simulated by creating a separate GitEngine instance for the "origin" repository. The o/ prefix denotes remote tracking branches.

Internationalization Copy Chapter

String translations in src/js/intl/strings.js. Use intl.str() and intl.getDialog() to access localized strings. Locale validation via checkStrings.js.

README.md Copy Chapter

LearnGitBranching


LearnGitBranching is a git repository visualizer, sandbox, and a series of educational tutorials and challenges. Its primary purpose is to help developers understand git through the power of visualization (something that's absent when working on the command line). This is achieved through a game with different levels to get acquainted with the different git commands.

You can input a variety of commands into LearnGitBranching (LGB) -- as commands are processed, the nearby commit tree will dynamically update to reflect the effects of each command:

!demo-gif

This visualization combined with tutorials and "levels" can help both beginners and intermediate developers polish their version control skills. A quick demo is available here:
https://pcottle.github.io/learnGitBranching/?demo

Or, you can launch the application normally here:
https://pcottle.github.io/learnGitBranching/

Sandbox Mode Copy Section

By default the application launches in "sandbox mode" with a basic repository already created. Here you can enter commands and mess around with a repository as much as you like. Keep in mind you can

* undo to undo the effects of the last command
* reset to start over with a clean slate (works in levels too)
* git clone to simulate remote repositories!

Sandbox mode can be great for demonstrating something to a friend, but the real learning is with levels...

Levels Copy Chapter

Type levels to see the available lessons / challenges (and which ones you have solved so far). Each level series aims to teach some high-level git concept, and each tab of levels separates major worlds of info (like remote repositories versus local).

For some added fun, there is a "git golf" concept where we keep track of how many commands you use to solve each level. See if you can match all of our records!

Sharing permalinks Copy Section

You can share a link to LearnGitBranching with an arbitrary set of commands that will execute upon load by using the command URL parameter. You will also likely want to disable the intro dialog for this case with the NODEMO url param; here is an example to get started.

Level Builder Copy Section

You can build levels with the build level command. A dialog will walk you through the process, and at the end it will show you a JSON blob that represents the level you just created. Paste that in a gist or directly into an issue and I can check it out / merge in your changes! You can also share this level directly with friends by having them run import level and paste the JSON in the resulting text field, or simply send them a custom URL with the the gist ID in the parameters, like so:
https://pcottle.github.io/learnGitBranching/?gist_level_id=a84407351f9c9f0cb241

Reporting Bugs / Opening Issues Copy Chapter

When reporting bugs, try running the command debug_copyTree() in your JS console when in a state just before reproducing a bug. This can avoid having to copy all the commands you used to get into a specific state. (I can then use the importTreeNow command to get to that exact state)

Building yourself / Contributing Functionality Copy Chapter

For contributing core functionality in the app, you'll probably want to test your changes
at least once before submitting a pull request. That means you'll need the "gulp.js" build tool to build the app:

https://gulpjs.com/docs/en/getting-started/quick-start

You'll also need yarn to download all the dependencies of the project.

The general workflow / steps are below:

git clone <your fork of the repo>
cd learnGitBranching
yarn install
git checkout -b newAwesomeFeature
vim ./src/js/git/index.js # some changes
yarn gulp fastBuild # skips tests and linting, faster build
after building you can open up your browser to the index.html

open ./index.html
file generated and see your changes
vim ./src/js/git/index.js # more changes
yarn gulp build # runs tests and lint
git commit -am "My new sweet feature!"
git push
go online and request a pull

Alternatively, you can also build and run the app in a pre-configured online workspace:


Other Technical Details Copy Chapter

LearnGitBranching is a pretty simple application (from a technical perspective). There's no backend database or any AJAX requests -- it's a 100% clientside application written in JavaScript. The production version (on github.io) literally just serves up an HTML page with some JS and CSS.

Here is the high-level process of the build:

* CSS is written into just one stylesheet (there is not a whole ton of styling)
* New HTML is written into a template HTML file (template.index.html). This is only needed
for new views
* The app is "built", which outputs:
* index.html in the root directory
* CSS and JS files in ./build directory
* If the app is being built for production, then these CSS and JS files
are hashed (to bust caches) and tests are run
* That's it!

Thus, if you build the app locally, all you have to do in order to run the app is just open up index.html in the root directory of the repo. Pretty simple

Docker Copy Section

You can run the most recently built stable image with docker run -p 8080:80 ghcr.io/pcottle/learngitbranching:main. Access your environment with at http://localhost:8080/

You can build the app and image with the command: docker build -t ghcr.io/pcottle/learngitbranching:latest. See the Makefile for information on how to build locally with docker.

Some of our amazing contributors Copy Chapter

[//]: contributor-faces
<a href="https://github.com/pcottle"><img src="https://avatars0.githubusercontent.com/u/1135007?v=4" title="pcottle" width="80" height="80"></a>
<a href="https://github.com/Hongarc"><img src="https://avatars1.githubusercontent.com/u/19208123?v=4" title="Hongarc" width="80" height="80"></a>
<a href="https://github.com/twmht"><img src="https://avatars1.githubusercontent.com/u/1567200?v=4" title="twmht" width="80" height="80"></a>
<a href="https://github.com/JuhoKang"><img src="https://avatars1.githubusercontent.com/u/4745294?v=4" title="JuhoKang" width="80" height="80"></a>
<a href="https://github.com/sunshowers"><img src="https://avatars3.githubusercontent.com/u/180618?v=4" title="sunshowers" width="80" height="80"></a>
<a href="https://github.com/sPATROL"><img src="https://avatars0.githubusercontent.com/u/11875983?v=4" title="sPATROL" width="80" height="80"></a>
<a href="https://github.com/coyl"><img src="https://avatars1.githubusercontent.com/u/274452?v=4" title="coyl" width="80" height="80"></a>
<a href="https://github.com/alexeiberkov"><img src="https://avatars1.githubusercontent.com/u/4151345?v=4" title="alexeiberkov" width="80" height="80"></a>
<a href="https://github.com/aschrab"><img src="https://avatars1.githubusercontent.com/u/39620?v=4" title="aschrab" width="80" height="80"></a>
<a href="https://github.com/bcbcarl"><img src="https://avatars0.githubusercontent.com/u/135734?v=4" title="bcbcarl" width="80" height="80"></a>
<a href="https://github.com/ahonorat"><img src="https://avatars1.githubusercontent.com/u/5851945?v=4" title="ahonorat" width="80" height="80"></a>
<a href="https://github.com/nem75"><img src="https://avatars0.githubusercontent.com/u/1327785?v=4" title="nem75" width="80" height="80"></a>
<a href="https://github.com/eatdrinksleepcode"><img src="https://avatars0.githubusercontent.com/u/2099560?v=4" title="eatdrinksleepcode" width="80" height="80"></a>
<a href="https://github.com/nlehuby"><img src="https://avatars3.githubusercontent.com/u/919962?v=4" title="nlehuby" width="80" height="80"></a>
<a href="https://github.com/alexandear"><img src="https://avatars2.githubusercontent.com/u/3228886?v=4" title="alexandear" width="80" height="80"></a>
<a href="https://github.com/PanAeon"><img src="https://avatars3.githubusercontent.com/u/686076?v=4" title="PanAeon" width="80" height="80"></a>
<a href="https://github.com/donkirkby"><img src="https://avatars1.githubusercontent.com/u/1639148?v=4" title="donkirkby" width="80" height="80"></a>
<a href="https://github.com/lroellin"><img src="https://avatars1.githubusercontent.com/u/3150983?v=4" title="lroellin" width="80" height="80"></a>
<a href="https://github.com/ptsoccer"><img src="https://avatars1.githubusercontent.com/u/1102725?v=4" title="ptsoccer" width="80" height="80"></a>
<a href="https://github.com/jankeromnes"><img src="https://avatars2.githubusercontent.com/u/599268?v=4" title="jankeromnes" width="80" height="80"></a>
<a href="https://github.com/qiansen1386"><img src="https://avatars2.githubusercontent.com/u/1759658?v=4" title="qiansen1386" width="80" height="80"></a>
<a href="https://github.com/renderf0x"><img src="https://avatars1.githubusercontent.com/u/6155643?v=4" title="renderf0x" width="80" height="80"></a>
<a href="https://github.com/filipefilardi"><img src="https://avatars1.githubusercontent.com/u/7308241?v=4" title="filipefilardi" width="80" height="80"></a>
<a href="https://github.com/rebangm"><img src="https://avatars2.githubusercontent.com/u/1638136?v=4" title="rebangm" width="80" height="80"></a>
<a href="https://github.com/marcolivierarsenault"><img src="https://avatars2.githubusercontent.com/u/2634090?v=4" title="marcolivierarsenault" width="80" height="80"></a>
<a href="https://github.com/pengi"><img src="https://avatars0.githubusercontent.com/u/1087673?v=4" title="pengi" width="80" height="80"></a>
<a href="https://github.com/waldyrious"><img src="https://avatars2.githubusercontent.com/u/478237?v=4" title="waldyrious" width="80" height="80"></a>
<a href="https://github.com/tym-network"><img src="https://avatars1.githubusercontent.com/u/2879545?v=4" title="tym-network" width="80" height="80"></a>
<a href="https://github.com/zhyu"><img src="https://avatars1.githubusercontent.com/u/1728523?v=4" title="zhyu" width="80" height="80"></a>
<a href="https://github.com/mgarciaisaia"><img src="https://avatars1.githubusercontent.com/u/1190974?v=4" title="mgarciaisaia" width="80" height="80"></a>
<a href="https://github.com/YourSenseiCreeper"><img src="https://avatars1.githubusercontent.com/u/6324814?&v=4" title="YourSenseiCreeper" width="80" height="80"></a>
<a href="https://github.com/olsza"><img src="https://avatars1.githubusercontent.com/u/12556170?v=4" title="Olsza" width="80" height="80"></a>

[//]: contributor-faces

Helpful Folks Copy Chapter

* Nikita Kouevda
* Maksim Ioffe
* Dan Miller

And the following heroes for assisting in translating:
* Jake Chen
* 우리깃 ("urigit")
* "bcho"
* "scientific-coder"
* "ace-coder"
* Joël Thieffry
* Jens Bremmekamp ("nem75")
* "hilojack"
* Ming-Hsuan-Tu ("twmht")
* Mikhail Usov ("mikhailusov")
* Matias Garcia Isaia ("mgarciaisaia")
* Marc-Olivier Arsenault ("marcolivierarsenault")
* Eroany H Leader ("lhyqy5")
* Honorat ("ahonorat")
* Vasil Kulakov ("coyl") & Lyubov Agadjanyan ("shayenblue")
* Aliaksei Berkau ("alexeiberkov")
* Mizunashi Mana ("mizunashi-mana")
* YourSenseiCreeper
* Olsza

Also huge shoutout for everyone who has put up a pull request that was pulled! Check out the 30+ contributors we have in the Contributors View

And everyone who has reported an issue that was successfully closed!