Skip to main content
Learn Git Branching is a 100% client-side JavaScript application that simulates git operations and visualizes them in real-time. This page provides a high-level overview of the system architecture.

​
Core Philosophy

Learn Git Branching has no backend database or AJAX requests. Everything runs in the browser:
  • All git operations are simulated using in-memory data structures
  • The visualization updates dynamically as commands are executed
  • Educational levels are embedded in the JavaScript bundle
  • State is transient - no persistence between sessions (unless using localStorage)

​
System Components

​
GitEngine

Location: src/js/git/index.js The heart of the application. GitEngine simulates all git operations:
  • Manages the commit graph (commits, branches, tags, refs, HEAD)
  • Processes git commands and updates internal state
  • Dispatches events to the visualization system
  • Supports both git and Mercurial (hg) command modes
  • Uses the EventBaton pattern for command handling
Key responsibilities:
  • Creating and manipulating commits
  • Branch and tag management
  • Simulating merge, rebase, cherry-pick, and other git operations
  • HEAD pointer management
  • Remote repository simulation (via separate GitEngine instances)

​
Visualization System

Location: src/js/visuals/ Renders the commit tree using Raphael.js (SVG graphics):

visualization.js

Main visualization controller that coordinates all visual updates

tree.js

Renders the commit tree structure using Raphael.js

visNode.js

Visual representation of individual commits

visBranch.js

Visual representation of branches

visTag.js

Visual representation of tags

visEdge.js

Visual representation of commit parent relationships
Animation system (src/js/visuals/animation/):
  • All visual updates go through an animation queue
  • Uses Q promises to chain animations smoothly
  • Can be disabled for testing (headless mode)
  • Ensures visual consistency during complex operations

​
Command Processing

Location: src/js/commands/index.js, src/js/git/commands.js Processes user input and executes commands:
  • Commands are defined with regex patterns for parsing
  • Each command has an execute function that manipulates GitEngine
  • Supports command delegation (commands can invoke other commands)
  • Handles both git and Mercurial command syntaxes
  • Provides help text and command documentation
Example command flow: 
User types "git commit" 
  → Command parser matches regex pattern
    → Execute function creates new commit in GitEngine
      → GitEngine updates internal state
        → Dispatches event to visualization
          → Animation plays showing new commit

​
Levels System

Location: src/levels/ Educational challenges organized into sequences:
Each level is a JavaScript module with:
  • Name and description: What the level teaches
  • Starting tree state: Initial commit graph configuration
  • Goal description: What the user needs to achieve
  • Solution validation: TreeCompare logic to verify completion
  • Hint system: Optional hints for stuck users
Level definition (src/levels/index.js):
  • Imports all level modules
  • Organizes them into sequences
  • Provides level metadata and progression tracking

​
Flux Architecture

The app uses a unidirectional data flow pattern inspired by Facebook’s Flux: 
┌─────────────┐
│   Actions   │  (User interactions, URL changes)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Dispatcher  │  (Central event bus)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Stores    │  (Application state)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Views    │  (React/Backbone components)
└─────────────┘
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: Command line state and history
  • LevelStore.js: Current level and completion progress
  • LocaleStore.js: Internationalization and language
  • GlobalStateStore.js: Global application state
Actions (src/js/actions/):
  • Action creators for CommandLine, Level, Locale, and GlobalState
  • Provide a clean API for triggering state changes

​
UI Components

Learn Git Branching uses a mix of legacy and modern UI frameworks: React Components (src/js/react_views/):
  • Command line interface with syntax highlighting
  • Toolbar and helper bars
  • Command history view
  • Modern, maintainable components
Backbone Views (src/js/views/):
  • Legacy modal dialogs and builders
  • gitDemonstrationView.js: Animated command demonstrations
  • Level builder and custom level import
  • Gradually being migrated to React

​
Key Patterns

​
EventBaton

Location: src/js/util/eventBaton.js A pattern for transferring event handling responsibility:
  • Commands can “grab” the event baton to handle subsequent events
  • Used extensively for multi-step operations (interactive rebase, level building)
  • Prevents event conflicts during complex workflows

​
TreeCompare

Location: src/js/graph/treeCompare.js Compares two commit trees for level completion validation:
  • Checks commit structure, branch positions, and tags
  • Allows flexible matching (order-independent, ref-name-independent)
  • Provides detailed diff output for debugging
  • Used by both the level system and test suite

​
Remote Repository Simulation

Remote operations (push/pull/fetch) are simulated by:
  1. Creating a separate GitEngine instance for the “origin” repository
  2. Implementing network operation logic (transfer commits, update refs)
  3. Using the o/ prefix to denote remote tracking branches
  4. Synchronizing state between local and remote engines
This allows teaching remote workflows without actual network calls.

​
Project Structure

src/
├── js/
│   ├── app/              # Application bootstrapping
│   ├── git/              # Git engine core
│   ├── mercurial/        # Mercurial (hg) support
│   ├── commands/         # Command parsing
│   ├── level/            # Level loading and validation
│   ├── visuals/          # Visualization and animation
│   ├── views/            # Backbone views (legacy)
│   ├── react_views/      # React components (modern)
│   ├── stores/           # Flux stores
│   ├── actions/          # Flux actions
│   ├── dispatcher/       # Flux dispatcher
│   ├── models/           # Backbone models
│   ├── intl/             # Internationalization
│   ├── graph/            # Tree comparison
│   └── util/             # Utilities and helpers
├── levels/               # Level definitions by category
├── style/                # CSS stylesheets
└── template.index.html   # HTML template

__tests__/                # Jasmine test specs

​
Key Technologies

Backbone.js

MVC framework for legacy UI components

React 17

Modern UI components and views

Flux

Unidirectional data flow architecture

Raphael.js

SVG graphics library for visualization

Q Promises

Promise library for animation chains

jQuery

DOM manipulation and UI widgets

Browserify

Module bundling and dependency management

Babel

JSX transformation and modern JavaScript

​
Testing Architecture

Location: __tests__/ The test suite uses Jasmine and several custom utilities:
  • Headless GitEngine (src/js/git/headless.js): Git engine without visualization for fast tests
  • Create helper (__tests__/util/create.js): Set up test commit trees quickly
  • Mock utility (__tests__/util/mock.js): Mock commands and responses
  • Test coverage: Git operations, remote operations, levels, tree comparison, command parsing

​
Internationalization

Location: src/js/intl/ Supports multiple languages:
  • String translations in strings.js (keyed by locale)
  • Dialog translations via getDialog()
  • Level descriptions and hints localized
  • Locale validation via checkStrings.js
  • Use intl.str() to access translated strings throughout the codebase

​
Build Process Flow

1

JavaScript Bundling

Browserify bundles all modules starting from entry points, handling require() statements and dependencies
2

JSX Transformation

Babel transforms React JSX syntax to standard JavaScript function calls
3

CSS Concatenation

All CSS files are concatenated into a single stylesheet (minified in production)
4

Template Processing

template.index.html is processed to inject bundled asset paths and generate index.html
5

Optimization (Production)

  • JavaScript minified with Terser
  • CSS minified with clean-css
  • Filenames hashed for cache busting
  • HTML minified
6

Validation

  • Jasmine tests executed
  • JSHint linting runs
  • String validation for i18n

​
Understanding the Codebase

When contributing, focus on these key areas:
  1. GitEngine (src/js/git/index.js) - Core git simulation logic
  2. Commands (src/js/commands/, src/js/git/commands.js) - Adding new commands
  3. Visualization (src/js/visuals/) - How commits are rendered
  4. Levels (src/levels/) - Creating educational content
  5. Tests (__tests__/) - Ensuring correctness
For most features, you’ll touch GitEngine, add or modify commands, update visualization if needed, and write tests.

Build docs developers (and LLMs) love

Get started for freeTalk to us