GitMap

A CLI tool and web app that visualizes git commands, their flags, relationships, conflicts, and common usage patterns — right in your terminal or browser.

Features

CLI

• Command Explorer - View detailed info about any git command with flags, examples, and tips
• Interactive Mode - Browse all commands by category with keyboard navigation
• Search - Fuzzy search across all commands, flags, and descriptions
• Compare - Side-by-side comparison of similar commands (rebase vs merge, etc.)
• Cheatsheets - Quick reference guides for common workflows (13 topics)

Web Interface

• Visual Graph - Interactive D3 visualization of command relationships
• Flag Builder - Build git commands by selecting flags interactively
• Workflow Guides - Step-by-step guides with progress tracking
• Quiz Mode - Test your git knowledge with auto-generated questions
• State Diagram - Visualize how commands affect working dir, staging, repo, and remote
• Pitfalls & Tips - Learn common mistakes and how to avoid them

Installation

From npm (Recommended)

# Install globally
npm install -g gitmap

# Now use anywhere
gitmap commit
gitmap web

From Source

# Clone and install
git clone https://github.com/vsthakur101/gitmap.git
cd gitmap
npm install

# Link for global usage
npm link

# Or run directly
node bin/gitmap.js <command>

Usage

Explore a Command

gitmap commit
gitmap rebase
gitmap stash

Output:

╭─────────────────────────────────────────────────╮
│  git commit                                     │
│  Record changes to the repository               │
├─────────────────────────────────────────────────┤
│  FLAGS                                          │
│  -m, --message <msg> ★                          │
│    Use the given message as the commit message  │
│  --amend ★                                      │
│    Replace the tip of the current branch...    │
│  ...                                            │
│                                                 │
│  COMMON COMBINATIONS                            │
│  git commit -am "msg"     Stage + commit        │
│  git commit --amend --no-edit  Quick amend      │
│                                                 │
│  RELATED COMMANDS                               │
│  git add → git commit → git push                │
╰─────────────────────────────────────────────────╯

Interactive Mode

gitmap

Navigate with arrow keys, Enter to select, Escape to go back, q to quit.

Search

gitmap search "undo"
gitmap search "branch delete"
gitmap search --natural "how to undo last commit"

Compare Commands

gitmap compare rebase merge
gitmap compare reset revert
gitmap compare fetch pull
gitmap compare checkout switch

Cheatsheets

gitmap cheat              # List available cheatsheets
gitmap cheat quick        # Quick reference
gitmap cheat branching    # Branching commands
gitmap cheat undo         # Undo operations
gitmap cheat remote       # Remote commands
gitmap cheat stash        # Stash commands
gitmap cheat log          # Log and history
gitmap cheat rebase       # Interactive rebase
gitmap cheat cicd         # CI/CD workflows
gitmap cheat monorepo     # Monorepo operations
gitmap cheat submodules   # Git submodules
gitmap cheat hooks        # Git hooks
gitmap cheat recovery     # Recovery operations
gitmap cheat security     # Security best practices

List Commands

gitmap list                    # All categories
gitmap list branching          # Commands in category
gitmap list remote             # Remote commands

Related Commands

gitmap related commit          # Commands related to commit
gitmap related branch          # Commands related to branch

CLI Options

gitmap <command>              # View command details
gitmap <command> --flags-only      # Show only flags
gitmap <command> --examples-only   # Show only examples
gitmap <command> --json           # Output as JSON
gitmap --no-color                 # Disable colors

Available Cheatsheets

| Name | Description | |------|-------------| | quick | Most common commands | | branching | Branch operations | | undo | Undo and recovery | | remote | Remote operations | | stash | Stash management | | log | Log and history | | rebase | Interactive rebase | | cicd | CI/CD workflows (shallow clones, tags, PRs) | | monorepo | Monorepo operations (sparse checkout, subtree) | | submodules | Git submodules management | | hooks | Git hooks setup and usage | | recovery | Recovering lost commits and files | | security | Signing commits, removing secrets |

Pre-written Comparisons

| Commands | Key Differences | |----------|----------------| | rebase vs merge | History rewriting vs preserving | | reset vs revert | Local vs pushed commits | | fetch vs pull | Download only vs download + merge | | checkout vs switch | Multi-purpose vs branch-only | | merge vs cherry-pick | Whole branch vs specific commits | | stash vs commit | Temporary vs permanent | | reset --soft vs --hard | Keep vs discard changes |

Web Interface

Launch the interactive web visualizer:

# Start the web UI (uses pre-built static files)
gitmap web

# Custom port
gitmap web --port 4000

# Development mode (if you cloned from source)
gitmap web --dev

Views

| View | Description | |------|-------------| | Explorer | Browse commands by category with full details | | Graph | Interactive D3 visualization of command relationships | | Compare | Side-by-side command comparisons | | Cheatsheets | Quick reference guides | | Flag Builder | Build commands by selecting flags | | Workflows | Step-by-step workflow guides | | State Diagram | Visualize git areas (working dir, staging, repo) | | Quiz | Test your git knowledge |

Workflow Guides

• Feature Branch Workflow
• Hotfix Workflow
• Code Review Process
• Release Workflow
• Conflict Resolution
• Undoing Common Mistakes
• Working in Monorepos
• Finding Bugs with Bisect

Command Coverage

GitMap includes detailed information for 30+ git commands across categories:

• Getting Started: init, clone, config
• Staging: add, commit, status, diff, stash, reset, restore, rm, mv
• Branching: branch, checkout, switch, merge, rebase
• Remote: remote, fetch, pull, push
• History: log, show, blame, bisect, reflog
• Advanced: cherry-pick, tag, revert, clean, submodule, worktree

Data Files

GitMap includes rich data for learning git:

| File | Contents | |------|----------| | commands.json | 30+ commands with flags, examples, tips | | comparisons.json | 8 pre-written command comparisons | | cheatsheets.json | 13 topic-specific cheatsheets | | workflows.json | 8 step-by-step workflow guides | | pitfalls.json | Common mistakes for 15+ commands | | aliases.json | 50+ recommended git aliases | | categories.json | Command categorization |

Requirements

• Node.js 18+

License

MIT