Git Visualizer: Building a Git Simulator from Scratch

Visualizing the Git commit graph is the only way to actually understand what rebase or cherry-pick is doing under the hood. Most people just memorize commands and pray they don't blow up their main branch, but simulating the internal state of a repository—without actually touching the filesystem—is a great exercise in state management.

I've been digging into the architecture of Commitea, a tool that replicates Git behavior in a browser-based simulator. Instead of just being a static tutorial, it implements a logic engine that handles fast-forward vs. merge commit detection and history rewriting.

The Technical Architecture

The project uses a lean stack (Astro + Tailwind v4) but the heavy lifting happens in the vanilla JS engine that manages the commit graph.

• The Content Pipeline: To avoid duplicating documentation, the site uses a custom Astro Content Layer loader. It fetches .md files directly from a public GitHub repo at build time. This means the GitHub repo acts as the CMS, and a Vercel deploy hook triggers a rebuild whenever a markdown file is updated.
• SVG Rendering Logic: Rather than re-rendering the entire graph on every command—which would look janky—it uses incremental DOM updates. The nodes and edges are tracked by stable IDs; the engine diffs the state and updates only the changed attributes. This is why the commit nodes actually animate into place during a merge or rebase.
• Serverless State: To keep the site mostly static for speed, only the feedback mechanism is dynamic. It uses a single Vercel serverless function to push vote counts to Redis, while the rest of the site is prerendered HTML.

Simulating Git Logic

The simulator doesn't use a real .git folder. It mimics the behavior of the Git HEAD and branch pointers. For example, to simulate "uncommitted changes" (which normally require a filesystem), the project implements a custom edit helper command.

Here is a conceptual look at how a simulator handles a reset --hard vs a checkout in terms of pointer manipulation:

// Conceptual logic for pointer movement in a Git simulator
const gitState = {
  branches: {
    main: 'commit_a',
    feature: 'commit_c'
  },
  HEAD: 'feature'
};

function handleResetHard(targetCommit) {
  // Move the current branch pointer to the target commit
  const currentBranch = gitState.HEAD;
  gitState.branches[currentBranch] = targetCommit;
  // In a real repo, the working directory would be wiped here
}

function handleCheckout(branchName) {
  if (gitState.branches[branchName]) {
    gitState.HEAD = branchName;
  } else {
    throw new Error("Branch not found");
  }
}

Real-World Scenarios Covered

The tool is particularly useful for visualizing the "danger zone" commands. I've found that seeing the graph change in real-time makes these concepts click:

• Rebase: Watching the commits physically detach from one branch and re-attach to the tip of another.
• Cherry-pick: Seeing a specific commit hash duplicated onto the current HEAD.
• Fast-forward: Understanding why some merges create a new "merge commit" while others just slide the pointer forward.

For anyone building their own AI-powered dev tools or documentation sites, the approach of using a GitHub-based content layer combined with a specialized JS engine for visualization is a high-performance pattern. It keeps the site fast (static) while providing a deep, interactive experience.

# If you want to explore the source code:
git clone https://github.com/davidbc01/commitea.git