Understanding How Git Works

An interactive tool for exploring how Git works, commit history, and merge mechanics.

中文文档

Features

1. Read commit history from a Git repository
2. Display commits (commit id, author, date, message)
3. After selecting a commit, show the list of changed files
4. After selecting a commit and file, show the file diff
5. After selecting a commit, show the tree hash, file contents, and a visual directory tree
6. After selecting multiple commits, draw a commit graph (parent/child, branches, merges) in commit order
7. Show commit ids on each node in the graph
8. After selecting a node, show details (commit id, author, date, message, tree hash)
9. After selecting a node, open snapshot details (tree hash, tree structure, file list)
10. Scrollable commit list with checkboxes to control which commits appear in the graph

Tech stack

• Framework: React + TypeScript + Vite
• Git: simple-git (via Vite plugin)
• Visualization: D3.js

Install and run

From npm (CLI)

Repository: hitzhangjie/git-vis. The npm package is @hitzhangjie/git-vis (the unscoped name git-vis is taken); the CLI command is still git-vis:

npm install -g @hitzhangjie/git-vis
git-vis /path/to/your/repo
git-vis .

From source (development)

npm install

Desktop app (Electron)

# Dev mode (Vite + Electron)
npm run dev:electron

# Build installers (macOS: dmg / Windows: nsis / Linux: AppImage)
npm run dist

CLI behavior:

• No path: open the repo input page
• Valid repo path: go straight to the visualization
• Invalid path: fall back to the repo input page

CLI (recommended)

Open a local Git repository from any directory:

# Inside the project (development)
npm run git-vis -- .

# Or after linking globally
npm link
git-vis /path/to/your/repo
git-vis .

The command validates the repo path, starts the dev server, and opens the UI in your browser so you do not need to type the path again.

Web dev server only

npm run dev

Open http://localhost:3000 and enter the repository path in the UI.

Usage

1. Open a repo — Run git-vis <repo> or enter a path in the web UI and click “Open repository”
2. Commit list — The left panel lists commits; click one for details
3. Commit details — The center panel lists changed files; click a file for the diff
4. Snapshot — On the commit detail view, click “View snapshot” for the tree structure
5. Graph — Check commits in the left list; the right panel shows the relationship graph
   • Force-directed layout (D3.js); nodes are draggable
   • Click a node for more details

Notes

• Git must be installed on your system
• The path must point to a valid Git repository
• Large repositories may take longer to load

Bad case: badcase/git_cp_mistake.tgz is a constructed example where git merge feature and cherry-picking commits from feature do not report conflicts even when changes overlap—Git’s three-way merge does not flag them the way intuition suggests. That puzzle motivated this project: visualize Git internals so more users can see what actually happens.

Documentation: Developer guide (project layout, API, local dev). Design notes: docs/1-SUMMARY.md (Chinese).