GitQuest: Learn Git by Actually Seeing How It Works

Git can be confusing when you're just starting out. You run commands like git commit, git branch, or git merge, but it's not always clear what's happening behind the scenes.

What exactly is HEAD? How do branches work? What happens when two branches merge, and why do merge conflicts occur?

I built GitQuest to make these concepts easier to understand.

It's an interactive Git simulator where you can run commands and watch the repository change visually in real time. Instead of just reading about Git, you can experiment with it, make mistakes, and see exactly what each command does.

Built for Global Hack Week: Hacktoberfest (Challenge 1: Build a Mini App).

What is GitQuest?

GitQuest is a browser-based game and sandbox designed to help developers understand Git and GitHub through interactive visualizations.

Every command updates a visual commit graph (DAG), so you can follow how commits connect, how branches move, and how changes travel between local and remote repositories.

Repositories:

What Can You Do?

1. Start a Git Repository from Scratch

GitQuest doesn't throw you into an already configured repository. You start with an empty workspace and build everything yourself.

You can run commands like:

  • mkdir my-project and cd my-project to create and enter a project directory.
  • git init to initialize a repository.
  • touch index.js to create your first file.
  • git status to check what's changed.
  • git add . to stage your files.
  • git commit -m "Initial commit" to create your first commit.
  • git remote add to connect a remote repository.
  • git push -u to push commits and set up upstream tracking.

As you progress, GitQuest shows how these commands affect your working directory, staging area, commits, and the files inside .git/.

2. Explore Git Through Three Different Views

I added three canvas modes because looking at a commit graph alone doesn't explain everything.

DAG Graph

Shows your commits, branches, HEAD, and remote-tracking references. You can follow the history of your repository as you create branches and merge changes.

3-Tree Lifecycle

Shows how files move through the different stages of Git:

Working Directory -> Staging Area -> Local Repository -> Remote Repositories

This is especially useful for understanding the difference between git add, git commit, and git push.

.git Internals

Lets you look inside Git's internal structure, including:

  • .git/HEAD
  • .git/refs/heads/
  • .git/refs/remotes/
  • .git/objects/
  • .git/config

You can also click on commits, branches, files, and remotes to inspect their details, including hashes, timestamps, file changes, and simulated git cat-file output.

The canvas supports zooming, resetting the zoom, and expanding to a larger view when the commit history gets complicated.

3. Learn Through Six Playable Stages

I divided the game into six stages, each focusing on a different part of Git.

Stage 1: Project Genesis

Create a directory, initialize Git, add files, and make your first commit.

Stage 2: Branching

Learn how to create and switch branches, and see why branches are essentially pointers to commits.

Stage 3: The 3-Way Merge

Understand common ancestors, how Git combines changes, and why some merges create commits with two parents.

Stage 4: GitLab & GitHub Remotes

Connect your local repository to simulated GitLab and GitHub remotes, push commits, and understand upstream tracking.

Stage 5: Merge Conflicts

Intentionally create a merge conflict and resolve it using an interactive diff editor. You'll also learn what conflict markers like <<<<<<< HEAD, =======, and >>>>>>> mean.

Stage 6: Master Sandbox

An unrestricted playground where you can experiment with branches, commits, merges, and repository internals without following a fixed mission.

Each stage has smaller steps explaining what a command does, why it's useful, and what changes internally.

4. Skip Steps or Experiment Freely

Sometimes you just want to see the result without typing every command.

So I added three shortcuts:

  • Auto Step: Automatically runs the next command in the current stage.
  • Solve Stage: Completes all the steps in the current stage.
  • Master All Levels: Unlocks all six stages and generates a repository with branches, merges, commit history, and GitLab/GitHub remotes.

These are also useful when you want to jump straight into a particular concept instead of replaying everything.

Design and Other Details

I wanted GitQuest to feel more like a small game than another documentation website.

The interface uses a playful geometric design with a warm cream background, bright accent colors, thick borders, and hard offset shadows.

I also added sound effects using the Web Audio API. Running commands, switching branches, encountering errors, and completing stages all have their own sounds.

There are keyboard shortcuts too:

  • M -- Open the Mission Board
  • ? -- Open the Field Manual
  • R -- Restart the current stage
  • Esc -- Close dialogs

Running GitQuest Locally

Clone the repository and install the dependencies:

git clone https://gitlab.com/wdipak/gitquest.git cd gitquest npm install npm run dev

Then open http://localhost:5173 in your browser.

Why I Built It

The main idea behind GitQuest is simple: Git is easier to understand when you can see what it's doing.

Reading that a branch is a pointer to a commit is one thing. Watching that pointer move when you make a new commit is another.

I wanted to bring that kind of visual feedback to the Git learning process, from creating your very first repository to understanding merges, conflicts, and remotes.

GitQuest is my attempt to make learning Git a little less intimidating and a lot more hands-on.