git-hierarchies 🔀

Reveal the real org chart by analyzing who approves whose PRs.

Ever wondered who actually runs things at your company? This CLI analyzes GitHub pull request approval patterns to surface hidden hierarchies, gatekeepers, and power dynamics.

Quick Start

No installation needed — just run with npx:

# Set your GitHub token
export GITHUB_TOKEN=ghp_xxxxx

# Analyze any repository
npx git-hierarchies facebook/react

# Generate interactive visualization
npx git-hierarchies WordPress/gutenberg --since 2024-01-01 --html graph.html

Installation

For frequent use, install globally:

npm install -g git-hierarchies

# Then run directly
git-hierarchies owner/repo

Features

📊 Power Rankings

See who really runs things — ranked by approval authority and contribution patterns.

🔗 Reporting Lines Detection

Automatically detects likely manager relationships based on who consistently approves whose work.

🎨 Interactive Visualization

Generate beautiful, interactive force-directed graphs with:

• Nodes colored by role (Tech Lead, Gatekeeper, Core Team, etc.)
• Connection strength shown by line thickness and color
• Hover tooltips with detailed stats
• Search, zoom, and filter controls

⏱️ Time-Based Analysis

Analyze specific time periods to see how team dynamics evolve:

• --since 2024-01-01 — Custom date
• --last-week, --last-month, --last-quarter, --last-year

Usage

git-hierarchies [repo] [options]

Arguments

| Argument | Description | |----------|-------------| | repo | GitHub repository (owner/repo or URL). Auto-detects if in a git directory. |

Options

| Option | Description | |--------|-------------| | -n, --limit <number> | Maximum PRs to analyze (default: unlimited) | | -t, --token <token> | GitHub token (or set GITHUB_TOKEN env) | | --since <date> | Only include PRs merged after this date | | --last-week | Shortcut for --since "1 week ago" | | --last-month | Shortcut for --since "1 month ago" | | --last-quarter | Shortcut for --since "3 months ago" | | --last-year | Shortcut for --since "1 year ago" | | --html <file> | Generate HTML visualization | | --json <file> | Export raw data as JSON |

Examples

# Analyze all PRs from 2024
git-hierarchies facebook/react --since 2024-01-01

# Quick analysis of last month
git-hierarchies vuejs/core --last-month

# Generate visualization with limited PRs
git-hierarchies microsoft/vscode --limit 500 --html vscode-hierarchy.html

# Export data for custom analysis
git-hierarchies torvalds/linux --last-year --json linux-data.json

Example Output

🔀 git-hierarchies: facebook/react
   The real org chart, revealed by PR approvals

👑 POWER RANKINGS
   Who really runs things around here

┌────────┬─────────────┬───────┬──────────┬───────────┬─────────────┬────────────┐
│ Rank   │ Name        │ Power │ Approved │ Submitted │ Self-Merged │ Role       │
├────────┼─────────────┼───────┼──────────┼───────────┼─────────────┼────────────┤
│ 👑 1   │ gaearon     │ 847   │ 412      │ 23        │ 8           │ Tech Lead  │
│ 🥈 2   │ sebmarkbage │ 523   │ 245      │ 33        │ 12          │ Tech Lead  │
│ 🥉 3   │ acdlite     │ 412   │ 189      │ 34        │ 5           │ Core Team  │
└────────┴─────────────┴───────┴──────────┴───────────┴─────────────┴────────────┘

📊 LIKELY REPORTING LINES
   Who approves whose work most consistently

┌────────────┬───┬─────────────┬────────────────┐
│ Developer  │ → │ Likely Mgr  │ % of Approvals │
├────────────┼───┼─────────────┼────────────────┤
│ poteto     │ → │ gaearon     │ 73%            │
│ lunaruan   │ → │ acdlite     │ 65%            │
└────────────┴───┴─────────────┴────────────────┘

HTML Visualization

The --html flag generates a standalone HTML file with an interactive force-directed graph:

• Fullscreen layout — Graph fills the entire viewport
• Role-based colors — Orange (Tech Lead), Purple (Gatekeeper), Blue (Core Team), etc.
• Connection strength — Thicker, bluer lines = stronger relationships
• Search — Find any contributor instantly
• Power rankings sidebar — Click to zoom to that person
• Filters — Adjust link strength threshold and node sizes
• Zoom/pan — Mouse wheel or button controls

git-hierarchies owner/repo --html output.html
open output.html

Authentication

You need a GitHub token to fetch PR data:

# Option 1: Environment variable (recommended)
export GITHUB_TOKEN=ghp_xxxxx
git-hierarchies owner/repo

# Option 2: Pass directly
git-hierarchies owner/repo --token ghp_xxxxx

# Option 3: Use GitHub CLI auth
gh auth login  # git-hierarchies will use GH_TOKEN

Create a token: https://github.com/settings/tokens

Required scopes: repo (for private repos) or public_repo (for public only)

Role Detection

Contributors are automatically classified based on their activity patterns:

| Role | Criteria | |------|----------| | Tech Lead | High self-merge rate (≥50%) or high approvals + submissions | | Gatekeeper | Many approvals, few submissions | | Core Team | Self-merge ability + regular approvals | | Senior/Reviewer | Approves more than submits | | Builder | Submits more than approves | | Contributor | Regular participation |

How It Works

1. Fetches merged PRs using GitHub's GraphQL API
2. Uses monthly time windows to bypass the 1000-result search limit
3. Builds an approval graph (who approved whose PRs)
4. Calculates power scores based on approval patterns
5. Detects likely reporting relationships
6. Visualizes the results

Privacy & Ethics

This tool reveals patterns in approval behavior, not actual reporting structures. Please use responsibly:

• ✅ Understanding team dynamics
• ✅ Identifying knowledge silos
• ✅ Finding collaboration opportunities
• ❌ Political maneuvering
• ❌ Performance evaluation
• ❌ Circumventing official processes

Remember: correlation ≠ causation. 👀

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

License

MIT © Riad Benguella