Skip to main content

​
Overview

The Level Builder lets you create custom Git challenges and share them with others. You can design your own teaching scenarios, create practice exercises, or build puzzles for your team.

​
Starting the Level Builder

To enter the level builder mode: 
build level
This launches an interactive dialog that walks you through the process of creating a level.
You can skip the intro dialog with the --skipIntro flag:
build level --skipIntro

​
Building a Level: Step-by-Step

The level builder follows a structured process to help you create complete, functional levels.

​
Step 1: Create the Starting Repository

First, build the repository state that learners will start with: 
# Create commits, branches, and other Git structures
git commit
git branch feature
git checkout feature
git commit
git commit
Once you’re satisfied with the starting state, define it: 
define start
This saves the current repository as the level’s starting point.
When you define start, your command history is cleared. This prevents accidentally including setup commands in your solution.

​
Step 2: Create the Solution

Now, from the starting state, execute the commands that solve the level: 
# Execute the solution commands
git checkout main
git merge feature
git branch -d feature
These commands will become the level’s official solution and define the goal state.

​
Step 3: Define the Goal

Once you’ve reached the desired end state, capture it: 
define goal
This saves:
  • The current repository state as the goal visualization
  • Your command history as the solution
You can view the goal state at any time: 
show goal  # View the goal
hide goal  # Close the goal window

​
Step 4: Name Your Level

Give your level a descriptive name: 
define name
This opens a prompt where you can enter the level name (e.g., “Merge Feature Branch”).

​
Step 5: Add a Hint (Optional)

Provide a hint for learners who get stuck: 
define hint
Enter a helpful hint like: “Try using git merge to combine branches.”

​
Step 6: Create Introduction Dialog (Optional)

Add an instructional dialog that explains the level: 
edit dialog
This opens an editor where you can:
  • Add multiple dialog screens
  • Include markdown-formatted instructions
  • Add images or diagrams
  • Provide context and learning objectives

​
Step 7: Export the Level

Finally, generate the JSON that defines your level: 
finish
This will:
  1. Prompt for any missing information (name, hint, dialog)
  2. Generate a JSON blob representing your complete level
  3. Display the JSON in a modal window
Copy the entire JSON output - you’ll need it to share or import your level!

​
Level Builder Commands Reference

​
Define Commands

define start    # Save current state as the starting point
define goal     # Save current state as the goal and capture solution
define name     # Set the level name
define hint     # Add a helpful hint

​
View Commands

show start      # Display the starting state visualization
hide start      # Close the starting state window
show goal       # Display the goal state visualization  
hide goal       # Close the goal window

​
Dialog Commands

edit dialog     # Create or edit the instructional dialog
objective       # Preview the current dialog

​
Completion

finish          # Complete the level and export JSON

​
Utility

help builder    # Show the level builder help dialog
reset           # Clear and start over
undo            # Undo the last command

​
Sharing Your Level

Once you’ve finished building, you have several options for sharing:

​
Option 1: Share the JSON Directly

  1. Copy the JSON output from the finish command
  2. Share it with others (via email, chat, etc.)
  3. They can import it using:
import level
# Then paste the JSON into the text field

​
Option 2: Create a GitHub Gist

For easier sharing:
  1. Copy the JSON output
  2. Create a new gist at gist.github.com
  3. Paste the JSON and save the gist
  4. Note the gist ID from the URL (e.g., a84407351f9c9f0cb241)
  5. Share this URL with others:
https://learngitbranching.js.org/?gist_level_id=a84407351f9c9f0cb241
Anyone visiting that URL will automatically load your custom level!
Gist URLs are perfect for sharing levels in documentation, tutorials, or course materials.

​
Option 3: Submit to the Repository

If your level is particularly good, consider submitting it to be included in Learn Git Branching:
  1. Copy your JSON output
  2. Open an issue or pull request
  3. Include your level JSON and explain what it teaches
The maintainers will review it and potentially add it to the official level collection!

​
Level JSON Structure

Your level is exported as JSON with this structure: 
{
  "name": {
    "en_US": "Your Level Name"
  },
  "hint": {
    "en_US": "Your helpful hint"
  },
  "startTree": "{...}",
  "goalTreeString": "{...}",
  "solutionCommand": "git checkout main;git merge feature",
  "startDialog": {
    "en_US": {
      "childViews": [...]
    }
  }
}
Key fields:
  • name: The level’s display name
  • hint: Optional hint text
  • startTree: JSON representing the starting repository state
  • goalTreeString: JSON representing the target goal state
  • solutionCommand: Semicolon-separated solution commands
  • startDialog: Optional instructional dialog screens

​
Importing Levels

To try someone else’s custom level: 
import level
This opens a text field where you can paste the level JSON. After importing, the level will start immediately.
Imported levels are temporary and won’t appear in the regular levels list. They’re perfect for one-off challenges or testing.

​
Examples of Custom Levels

​
Example 1: Simple Merge Exercise

Goal: Learn basic branch merging 
# Starting state
git commit
git branch feature  
git checkout feature
git commit
git checkout main
git commit
define start

# Solution
git merge feature
define goal

# Metadata
define name
# Enter: "Simple Merge Exercise"
define hint  
# Enter: "Use git merge to combine the feature branch into main"

finish

​
Example 2: Complex Rebase Challenge

Goal: Practice interactive rebasing 
# Starting state - messy history
git commit
git commit
git commit
git commit
define start

# Solution - clean it up
git rebase -i HEAD~4
# In real usage, you'd squash/reorder commits
define goal

finish

​
Best Practices

Keep it focused - Each level should teach one specific concept or technique.
Make goals clear - Use edit dialog to provide clear instructions about what learners should achieve.
Test your level - After finishing, import it and try solving it yourself to ensure it works as expected.
Provide helpful hints - Good hints guide learners without giving away the complete solution.
Keep solutions concise - The best levels have elegant solutions that aren’t too long or complex.
Avoid ambiguity - Make sure there’s only one clear way to achieve the goal, or explicitly state that multiple solutions are acceptable.

​
Troubleshooting

​
”Solution is empty” error

This means you tried to define goal before executing any commands. Make sure to:
  1. Run define start to set the starting point
  2. Execute solution commands
  3. Then run define goal

​
Lost your starting state

If you accidentally modify the starting state after defining it: 
show start  # View the saved starting state
reset       # Start completely over if needed

​
Editing an existing level

You can edit a previously created level: 
# Import your level
import level
# Paste the JSON

# Make modifications
# Re-export with finish
finish

​
Advanced Features

​
Disabled Commands

In your level JSON, you can disable specific Git commands to increase difficulty: 
{
  "disabledMap": {
    "git rebase": true
  }
}
This forces learners to solve the level without using certain commands.

​
Multiple Languages

You can add translations to make your level accessible to more learners: 
{
  "name": {
    "en_US": "Branch Merge",
    "es_AR": "Fusión de Ramas",
    "zh_CN": "分支合并"
  }
}

​
Next Steps

  • Study existing levels in the source code for inspiration
  • Share your levels using permalinks
  • Join the community to get feedback on your level designs
  • Contribute your best levels back to the project!

Build docs developers (and LLMs) love

Get started for freeTalk to us