gitTOW - Git Internals Visualizer

An advanced, interactive Git internals visualizer built with React and TypeScript

Live Demo • Report Bug • Request Feature

---

Overview

gitTOW is a sophisticated, browser-based Git simulator that provides real-time visualization of Git's internal data structures. It's an educational tool designed to help developers understand how Git works under the hood by simulating a complete Git environment with an animated Directed Acyclic Graph (DAG) representation.

Key Features

• Interactive Terminal - Full-featured Git command simulation with 20+ commands
• Real-time DAG Visualization - Animated commit graph with branches, tags, and merge nodes
• Pan & Zoom Controls - Navigate large commit histories with mouse drag and scroll
• Cyberpunk Aesthetic - Eye-catching dark mode UI with neon colors and glow effects
• State Inspector - View staging area, working directory, and stash in real-time
• Instant Feedback - See how Git commands affect the repository structure immediately
• Educational - Perfect for learning Git internals and visualizing complex workflows

---

Quick Start

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/Shreyas8905/gitTOW.git
   cd gitTOW

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

4. Open your browser Navigate to http://localhost:5173/

Build for Production

npm run build

The production build will be created in the dist/ directory.

---

📖 Usage Guide

Getting Started

1. Initialize a repository

   git init

2. Create and modify files

   touch README.md
   echo "Hello World" > app.js

3. Stage and commit changes

   git add .
   git commit -m "Initial commit"

4. Work with branches

   git branch feature
   git checkout feature
   touch feature.js
   git add .
   git commit -m "Add feature"

5. Merge branches

   git checkout master
   git merge feature

Supported Commands

Repository Management

• git init - Initialize a new repository
• git status - Show working tree status
• git log [--oneline] - Display commit history

Staging & Committing

• git add <files> - Stage files (use . for all)
• git commit -m "message" - Create a commit

Branching

• git branch [name] - List or create branches
• git branch -m <new-name> - Rename current branch
• git branch -d <name> - Delete a branch
• git checkout <ref> - Switch to branch/commit
• git switch <branch> - Modern checkout alternative
• git tag <name> [hash] - Create a tag

Integration

• git merge <branch> - Merge with three-way merge
• git rebase <branch> - Replay commits on new base
• git cherry-pick <hash> - Apply specific commit

Undo Operations

• git reset [--soft|--mixed|--hard] <target> - Move HEAD
• git revert <hash> - Create inverse commit
• git restore <file> [--staged] - Restore files

Advanced

• git stash [push|pop|list] - Save/restore work-in-progress
• git clean -fd - Remove untracked files

File Simulation

• touch <filename> - Create empty file
• echo "text" > <filename> - Write content to file
• help - Show available commands
• clear - Clear terminal output

---

Architecture

Tech Stack

Technology	Purpose
React 19	UI framework with functional components and hooks
TypeScript	Type-safe development
Vite 7	Lightning-fast build tool and dev server
Zustand	Lightweight state management
Framer Motion	Smooth animations and transitions
Tailwind CSS v3	Utility-first styling with custom cyberpunk theme
d3-hierarchy	Graph layout calculations

Project Structure

gitTOW/
├── src/
│   ├── components/
│   │   ├── Graph/
│   │   │   ├── GitGraph.tsx        # Main SVG graph visualization
│   │   │   └── GraphNode.tsx       # Individual commit rendering
│   │   ├── StateInspector/
│   │   │   └── StateInspector.tsx  # File state panel
│   │   └── Terminal/
│   │       └── Terminal.tsx        # Command interface
│   ├── engine/
│   │   ├── gitEngine.ts            # Core Git operations
│   │   └── commands.ts             # Command parser & dispatcher
│   ├── store/
│   │   └── gitStore.ts             # Zustand state management
│   ├── types/
│   │   └── git.types.ts            # TypeScript interfaces
│   ├── App.tsx                     # Main application
│   ├── index.css                   # Global styles + Tailwind
│   └── main.tsx                    # React entry point
├── public/                         # Static assets
├── dist/                           # Production build output
└── package.json

Core Components

1. GitEngine - Simulates Git's internal data structures (commits, refs, HEAD, index)
2. Command Parser - Routes commands to appropriate handlers with validation
3. GitGraph - SVG-based visualization with layered layout algorithm
4. Terminal - Interactive command input with history navigation
5. StateInspector - Real-time view of staging area, working directory, and stash

---

Design Philosophy

gitTOW features a Cyberpunk/Hacker aesthetic with:

• Dark Mode Only - Deep charcoal backgrounds (#0F111A)
• Neon Color Palette:
  • Primary (Neon Green): #00FF9F
  • Secondary (Cyan): #00D9FF
  • Accent (Pink): #FF006E
• Glow Effects - Text and UI elements with cyberpunk glow
• Monospace Fonts - Fira Code, Cascadia Code for that terminal feel
• Smooth Animations - Powered by Framer Motion

---

Educational Value

gitTOW is ideal for:

• Learning Git Internals - Visualize how commits, branches, and HEAD interact
• Understanding Complex Workflows - See merge vs rebase side-by-side
• Teaching Git Concepts - Perfect for workshops and tutorials
• Debugging Mental Models - Clarify confusing concepts like detached HEAD
• Practicing Git Commands - Safe environment to experiment

---

Screenshots

Main Interface

Interactive Git graph with commit nodes, branches, and tags

Terminal & State Inspector

Command execution with real-time state updates

Pan & Zoom

Navigate large commit histories effortlessly

---

Development

Available Scripts

npm run dev        # Start development server
npm run build      # Build for production
npm run preview    # Preview production build
npm run lint       # Run ESLint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Known Limitations

• No conflict resolution simulation (merges auto-succeed)
• Simplified file content tracking (no diffs)
• Single user mode (all commits by "User")
• No remote repository simulation (no push/pull/fetch)
• Limited undo for reset --hard (mimics real Git)

---

Future Enhancements

• Remote repository simulation (origin/master)
• Conflict resolution UI
• Interactive graph manipulation (drag nodes, right-click menus)
• Export graph as PNG/SVG
• Time-travel replay of command history
• Multi-user simulation with different authors
• Git hooks visualization
• Mobile responsive design

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Author

Shreyas

• GitHub: @Shreyas8905
• Project Link: https://github.com/Shreyas8905/gitTOW

---

Acknowledgments

• Inspired by Git's internal architecture
• Built with modern web technologies
• Designed for education and learning
• Community feedback and contributions

---

Show Your Support

If you found this project helpful, please consider giving it a star on GitHub!

---

Made with passion by Shreyas Kulkarni

⬆ Back to Top