gitopo

Topology-preserving Git commit graph visualizer that highlights key branches.

Overview

gitopo visualizes Git commit history with special treatment for mainline branches following Git Flow, GitHub Flow, and GitLab Flow conventions. It displays commits in columns based on their branch lineage, making it easy to understand the relationship between branches.

Built with Electron, Vite, and D3.js.

Features

• Key Branch Columns: Up to 3 main branches displayed in dedicated columns with distinct colors
• Sub-branch Detection: Automatically detects and groups commits based on branch lineage, with background rectangles for visual grouping
• Sub-branch Hover: Highlight sub-branch commits and edges on hover
• Pull Request Display: Shows open PRs from GitHub (requires gh CLI), toggleable in settings
• Settings Menu: Customize merge commit display style (circle/square) and merge edge style (dashed/solid)
• Rich Tooltips: Show commit details including branches, tags, author, and PR info
• Time Axis Zoom: Ctrl/Cmd + scroll to zoom in/out on the time axis
• Pan Navigation: Scroll or drag to navigate the graph
• Configurable Commit Limit: Adjust the number of commits to display

Installation

npx gitopo

Or install globally:

npm install -g gitopo

Troubleshooting

If you encounter "Electron failed to install correctly" error, run:

cd $(npm root -g)/gitopo
node node_modules/electron/install.js

This is a known Electron issue.

Usage

Run in any Git repository:

cd your-project
npx gitopo

The application launches in the background. Close the window to exit.

Controls

Action	Description
Scroll	Pan the graph
Drag	Pan the graph
Ctrl/Cmd + Scroll	Zoom time axis
Ctrl/Cmd + R	Fetch from remotes and refresh
Hover on commit	Show commit details tooltip
Hover on sub-branch	Highlight sub-branch rectangle and edges
Hover on Other commit	Highlight connecting edges to key branches

UI Elements

• Refresh Button: Fetch from remotes and reload the graph
• Branch Selectors (1-3): Choose which branches to display as key columns
• Commits Input: Set the maximum number of commits to load
• Settings Button (gear icon): Open settings menu for display options
• Column Headers: Branch names displayed at the top (follows horizontal scroll)

Configuration

Add a gitopo key to your project's package.json:

{
  "gitopo": {
    "keyBranches": ["origin/main", "origin/staging", "origin/production"]
  }
}

Options

Option	Type	Description
keyBranches	string[]	Default branches for the 3 branch selectors (in order)

If keyBranches is not specified, the first selector defaults to main or master.

Requirements

• Node.js
• Git
• GitHub CLI (gh) - optional, for PR display

Development

# Install dependencies
npm install

# Start Vite dev server
npm run dev

# In another terminal, start Electron in dev mode
npm run electron:dev

# Build for production
npm run build

# Run production build
npx gitopo

Testing with npm link

To test the development version in a project that has gitopo as a dependency:

# In this directory
npm link

# In the target project
npm link gitopo

To restore the original version:

# In the target project
npm unlink gitopo
npm install

License

MIT