� Repository Timeline Generator

Generate beautiful commit timeline charts for your Git repositories across multiple platforms.

Beautiful CLI • Multi-Platform • Interactive • Analytics

✨ Features

🎨 15 Chart Types - 10 2D charts (Chart.js) + 5 3D charts (Three.js)
🎨 Full Customization - Colors, gradients, borders, animations, scales, labels, tooltips, and legends
🌐 Multi-Platform Support - GitHub, GitLab, Bitbucket, and SourceHut
💻 Interactive CLI - Gradient banners, colored prompts, progress spinners
📊 Smart Analytics - Statistics dashboard with top repositories
🎯 Flexible Selection - Analyze all repos or choose specific ones
🚀 Real-time Progress - Live updates while fetching commit data
� 3D Visualizations - Modern Three.js powered 3D charts
💾 Export Options - High-resolution PNG images
⚙️ Config Management - Save default settings

📊 Detailed Chart Documentation: See docs/CHARTS.md for comprehensive information about all chart types, including visual examples, use cases, and best practices.

� Quick Start

Prerequisites

Install system dependencies for canvas rendering:

Ubuntu/Debian:

sudo apt update
sudo apt install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

macOS:

brew install pkg-config cairo pango libpng jpeg giflib librsvg

Fedora/RHEL:

sudo dnf install gcc-c++ cairo-devel pango-devel libjpeg-turbo-devel giflib-devel

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g @0xshariq/timeline

# If you get canvas errors, rebuild it:
npm rebuild canvas -g

# Run anywhere
timeline

Or with pnpm:

pnpm add -g @0xshariq/timeline

# If you get canvas errors:
pnpm rebuild canvas -g

timeline

Or with yarn:

yarn global add @0xshariq/timeline

# If you get canvas errors:
yarn global rebuild canvas

timeline

Note: Canvas automatically rebuilds on every run to ensure compatibility. This takes a few seconds initially. If you still encounter issues, see the Troubleshooting Guide.

Option 2: Install from Source

# Clone the repository
git clone https://github.com/0xshariq/timeline.git
cd timeline

# Install dependencies
pnpm install

# Run the CLI
pnpm start

# Or link globally
pnpm link --global
timeline  # Now you can use it anywhere!

Option 3: Run with npx (No Installation)

npx @0xshariq/timeline

💻 How to Use

🔧 Having issues? Check the Troubleshooting Guide for solutions to common problems including canvas errors and rate limits.

⚠️ Important: GitHub Authentication (Avoid Rate Limits)

GitHub API has strict rate limits:

Without authentication: 60 requests/hour ❌ (Will fail for most users!)
With authentication: 5,000 requests/hour ✅ (Recommended)

Step 1: Create a GitHub Personal Access Token

Go to GitHub.com → Click your profile picture → Settings
Scroll down to Developer settings (bottom of left sidebar)
Click Personal access tokens → Tokens (classic)
Click Generate new token (classic)
Give it a name (e.g., "timeline-cli")
Select scopes:
- ✅ public_repo (required for public repositories)
- ✅ repo (only if you want to access private repos)
Click Generate token at the bottom
⚠️ Copy the token immediately (you won't see it again!)

Step 2: Set the Token

Option A: Temporary (Current Session Only)

export GITHUB_TOKEN=ghp_your_token_here
timeline -p github -u 0xshariq

Option B: Permanent (Recommended)

For Bash users (~/.bashrc):

echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc

For Zsh users (~/.zshrc):

echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc
source ~/.zshrc

For Fish users:

set -Ux GITHUB_TOKEN ghp_your_token_here

Step 3: Verify It's Working

# Check if token is set
echo $GITHUB_TOKEN

# Test with timeline
timeline -p github -u 0xshariq --verbose

Troubleshooting Rate Limits

If you still see "403: rate limit exceeded":

Make sure token is set: echo $GITHUB_TOKEN
Verify token has correct permissions on GitHub
Wait for rate limit reset (error shows reset time)
Try with fewer repositories: timeline -p github -u username -r "repo1,repo2"

Security Tips:

Never commit tokens to Git repositories
Use minimum required permissions
Rotate tokens periodically
Revoke unused tokens in GitHub settings

Basic Usage

# Interactive mode (recommended for beginners)
timeline

# Or with npx (no installation)
npx @0xshariq/timeline

Command-Line Flags

Timeline supports powerful command-line flags for automation:

timeline [options]
timeline <command> [options]

Global Options

Flag	Alias	Description	Example
`-p, --platform <name>`		Git platform	`-p github`
`-u, --username <name>`		Username	`-u octocat`
`-r, --repos <list>`		Comma-separated repos	`-r "repo1,repo2"`
`-a, --all`		Analyze all repos	`--all`
`-t, --type <type>`	`-c, --chart`	Chart type	`-t line`
`-v, --verbose`		Show detailed output	`--verbose`
`-q, --quiet`		Minimal output	`--quiet`
`--no-merge`		Exclude merge commits	`--no-merge`
`-o, --open`		Open chart after generation	`--open`
`-V, --version`		Show version	`--version`
`-h, --help`		Show help	`--help`

Chart Customization Options

Colors & Gradients:

Flag	Description	Example
`--colors <colors>`	Custom colors (hex, comma-separated)	`--colors "#FF5733,#33FF57,#3357FF"`
`--gradient`	Enable gradient colors	`--gradient`
`--gradient-start <color>`	Gradient start color	`--gradient-start "#667eea"`
`--gradient-end <color>`	Gradient end color	`--gradient-end "#764ba2"`

Borders:

Flag	Description	Example
`--border-width <width>`	Border width (number)	`--border-width 3`
`--border-color <color>`	Border color (hex)	`--border-color "#000000"`

Animations:

Flag	Description	Example
`--no-animate`	Disable animations	`--no-animate`
`--animation-duration <ms>`	Animation duration	`--animation-duration 2000`
`--animation-easing <easing>`	Easing function	`--animation-easing "easeInOutCubic"`

Scales:

Flag	Description	Example
`--scale-type <type>`	Scale type (linear, logarithmic, time)	`--scale-type logarithmic`
`--no-zero`	Don't begin Y-axis at zero	`--no-zero`
`--no-grid`	Hide grid lines	`--no-grid`

Labels & Text:

Flag	Description	Example
`--no-labels`	Hide labels	`--no-labels`
`--label-size <size>`	Label font size	`--label-size 14`
`--label-color <color>`	Label color (hex)	`--label-color "#333333"`

Tooltips:

Flag	Description	Example
`--no-tooltips`	Disable tooltips	`--no-tooltips`
`--tooltip-bg <color>`	Tooltip background color	`--tooltip-bg "rgba(0,0,0,0.9)"`

Legend:

Flag	Description	Example
`--no-legend`	Hide legend	`--no-legend`
`--legend-position <pos>`	Position (top, bottom, left, right)	`--legend-position right`

Refer customization guide CUSTOMIZATION.md

Subcommands

1. `quick` - Quick generation

timeline quick -p <platform> -u <username> [options]

# Examples
timeline quick -p github -u octocat
timeline quick -p gitlab -u johndoe -t pie
timeline quick -p bitbucket -u alice --no-merge

Required options:

-p, --platform - Platform name
-u, --username - Username

Optional:

-t, --type - Chart type (default: line)
--no-merge - Exclude merge commits

2. `platforms` - List platforms

timeline platforms

# Output:
# 📦 Supported Platforms:
#   🐙 github     - GitHub
#   🦊 gitlab     - GitLab
#   🪣 bitbucket  - Bitbucket
#   🎯 sourcehut  - SourceHut

3. `charts` - List chart types

timeline charts

# Output:
# 📊 Available Chart Types:
#   📈 line      - Timeline of commits over time
#   📊 bar       - Compare commits across repositories
#   🥧 pie       - Repository contribution percentage
#   🍩 doughnut  - Like pie chart with center hole
#   📡 radar     - Multi-dimensional comparison
#   🔥 heatmap   - Activity calendar (GitHub-style)

4. `config` - Show configuration

timeline config

# Shows package version, Node version, etc.

5. `examples` - Show usage examples

timeline examples

# Displays common usage patterns

Usage Examples

Interactive Mode

# Full interactive experience
timeline

You'll be prompted for:

Platform Selection - Choose your Git platform
Username - Enter your username
Repository Selection - All or specific repos
Chart Type - Choose visualization type
Options - Verbosity, merge commits, auto-open

Quick Commands

# GitHub user with line chart (default)
timeline quick -p github -u octocat

# GitLab user with pie chart
timeline quick -p gitlab -u johndoe -t pie

# Bitbucket with bar chart, no merge commits
timeline quick -p bitbucket -u alice -t bar --no-merge

With Flags (Skip Prompts)

# Specific platform and user
timeline -p github -u octocat

# All repos with verbose output
timeline -p github -u octocat --all --verbose

# Specific repos with heatmap
timeline -p gitlab -u johndoe -r "project1,project2,project3" -t heatmap

# Pie chart, open automatically
timeline -p bitbucket -u bob --all -t pie --open

# Bar chart without merge commits, quiet mode
timeline -p github -u charlie --all -t bar --no-merge --quiet

Chart Customization Examples

# Custom colors (3 repositories with specific colors)
timeline -p github -u octocat -t bar --colors "#FF5733,#33FF57,#3357FF"

# Gradient colors for line chart
timeline -p github -u octocat -t line --gradient --gradient-start "#667eea" --gradient-end "#764ba2"

# Thick borders with custom color
timeline -p github -u octocat -t pie --border-width 5 --border-color "#FF0000"

# No animations for faster generation
timeline -p github -u octocat -t bar --no-animate

# Logarithmic scale for large value differences
timeline -p github -u octocat -t line --scale-type logarithmic

# Large labels with custom color
timeline -p github -u octocat -t bar --label-size 16 --label-color "#FF6B6B"

# No grid lines, no legend for clean look
timeline -p github -u octocat -t line --no-grid --no-legend

# Right-positioned legend
timeline -p github -u octocat -t pie --legend-position right

# Combine multiple customizations
timeline -p github -u octocat -t bar \
  --colors "#FF6B6B,#4ECDC4,#45B7D1,#FFA07A,#98D8C8" \
  --border-width 3 \
  --label-size 14 \
  --no-grid \
  --animation-duration 2000

# Perfect for presentations (clean, no tooltips)
timeline -p github -u octocat -t pie \
  --colors "#667eea,#764ba2,#f093fb,#4facfe" \
  --no-tooltips \
  --label-size 16 \
  --border-width 0

# Heatmap with custom colors
timeline -p github -u octocat -t heatmap \
  --gradient \
  --gradient-start "#9be9a8" \
  --gradient-end "#216e39"

Automation & CI/CD

# Perfect for scripts and automation
timeline quick -p github -u $GIT_USERNAME -t line

# Generate multiple charts
for type in line bar pie; do
  timeline quick -p github -u octocat -t $type
done

# Environment variables
export TIMELINE_PLATFORM=github
export TIMELINE_USER=octocat
timeline quick -p $TIMELINE_PLATFORM -u $TIMELINE_USER

Interactive Workflow

When you run timeline in interactive mode:

Step 1: Platform

Step 4: Chart Type

? Select chart type: (Use arrow keys)
❯ 📈 Line Chart      - Timeline of commits over time
  📊 Bar Chart       - Compare commits across repositories
  🥧 Pie Chart       - Repository contribution percentage
  🍩 Doughnut Chart  - Like pie chart with center hole
  📡 Radar Chart     - Multi-dimensional repository comparison
  🔥 Heatmap         - Activity calendar (GitHub-style)

Step 5: Options

? Select options: (Press space to select)
❯ ◉ Show detailed progress
  ◉ Include merge commits
  ◯ Open chart after generation

Step 6: Processing

──────────────────────────────────────────────────

⠼ Processing awesome-project (3/12)
ℹ Found 12 repositories
✓ my-library: 89 commits
✓ cli-tool: 143 commits
⚠ Skipped empty-repo: No commits found
✓ awesome-project: 67 commits
...

Step 7: Results

Statistics Summary:

📊 Statistics Summary
─────────────────────
Total Commits: 847
Repositories: 12
Date Range: 2023-01-15 to 2024-11-02 (657 days)
Average per Repo: 70 commits
Average per Day: 1.29 commits

🏆 Top Repositories:
  1. cli-tool: 143 commits
  2. my-library: 89 commits
  3. awesome-project: 67 commits
  4. web-app: 58 commits
  5. api-server: 52 commits

Success Message:

╭─────────────────────────────────────────────╮
│                                             │
│   ✨ Chart saved as timeline.png ✨        │
│                                             │
│   You can find it in the current directory │
│                                             │
╰─────────────────────────────────────────────╯

🌐 Supported Platforms

Platform	Support	API Version	Rate Limit
GitHub 🐙	✅ Full	REST v3	60/hour
GitLab 🦊	✅ Full	REST v4	10/sec
Bitbucket 🪣	✅ Full	API 2.0	Varies
SourceHut 🎯	✅ Full	GraphQL	Check docs

Increase Rate Limits (Optional)

Add authentication tokens to provider files for higher limits:

GitHub (src/providers/github.js):

async fetchRepos() {
  const res = await fetch(`${this.baseUrl}/users/${this.username}/repos`, {
    headers: { 'Authorization': 'token YOUR_GITHUB_TOKEN' }
  });
  // ...
}

GitLab (src/providers/gitlab.js):

headers: { 'PRIVATE-TOKEN': 'YOUR_GITLAB_TOKEN' }

📈 Chart Types

2D Charts (Chart.js)

Chart Type	Best For	Output
📈 Line	Timeline trends, activity patterns	`timeline-line.png`
📊 Bar	Repository comparison, totals	`timeline-bar.png`
🥧 Pie	Contribution percentages	`timeline-pie.png`
🍩 Doughnut	Modern contribution breakdown	`timeline-doughnut.png`
📡 Radar	Multi-metric comparison	`timeline-radar.png`
🔥 Heatmap	Daily activity calendar	`timeline-heatmap.png`
🎯 Polar Area	Radial visualization	`timeline-polarArea.png`
⚡ Scatter	Pattern detection	`timeline-scatter.png`
� Bubble	Multi-dimensional data	`timeline-bubble.png`
🎨 Mixed	Combined line + bar	`timeline-mixed.png`

3D Charts (Three.js)

Chart Type	Best For	Output	Status
� Bar 3D	Impressive presentations	`timeline-bar3d.png`	✅ Available
📈 Line 3D	3D trend visualization	`timeline-line3d.png`	🚧 Coming Soon
🔮 Scatter 3D	Multi-dimensional patterns	`timeline-scatter3d.png`	🚧 Coming Soon
🌊 Surface 3D	Activity landscapes	`timeline-surface3d.png`	🚧 Coming Soon
� Bubble 3D	Four-dimensional data	`timeline-bubble3d.png`	🚧 Coming Soon

📚 Full Documentation: For detailed information about each chart type, including visual characteristics, features, and usage examples, see docs/CHARTS.md

Quick Examples

# 2D Line chart (default)
timeline -p github -u octocat

# 3D Bar chart
timeline -p github -u octocat -t bar3d

# Heatmap for daily patterns
timeline -p github -u octocat -t heatmap

# Pie chart with custom colors
timeline -p github -u octocat -t pie --colors "#FF6B6B,#4ECDC4,#45B7D1"

🏗️ Project Structure

repo-timeline/
├── src/
│   ├── index.js              # CLI entry point (styled prompts)
│   ├── timeline.js           # Core logic & orchestration
│   ├── chart.js              # Chart.js configuration
│   ├── config.default.js     # Default settings
│   ├── providers/            # Platform-specific APIs
│   │   ├── github.js         # GitHub integration
│   │   ├── gitlab.js         # GitLab integration
│   │   ├── bitbucket.js      # Bitbucket integration
│   │   └── sourcehut.js      # SourceHut integration
│   └── utils/                # Helper utilities
│       ├── colors.js         # Color schemes
│       └── stats.js          # Statistics calculations
├── index.js                  # Entry point
├── package.json              # Dependencies & scripts
└── README.md                 # Documentation

🎨 CLI Features

Visual Components

Feature	Description
🎨 Gradient Banners	Eye-catching startup screen
🌈 Colored Prompts	Cyan questions, gray feedback
⏳ Progress Spinners	Real-time animated feedback
📦 Styled Boxes	Important messages in frames
✓ Status Icons	Success (✓), Info (ℹ), Warning (⚠)
🎯 Emoji Indicators	Visual context throughout

Interactive Options

// Available configurations
{
  verbose: true,           // Show detailed progress
  includeMerges: true,     // Include merge commits
  openChart: false         // Auto-open after generation
}

🔧 Development

Run in Development Mode

pnpm run dev  # Auto-reload on file changes

Adding New Platforms

Create Provider (src/providers/newplatform.js):

export class NewPlatformProvider {
  constructor(username) {
    this.username = username;
    this.baseUrl = "https://api.newplatform.com";
  }

  async fetchRepos() {
    // Return array of repo names
  }

  async fetchAllCommits(repo, config) {
    // Return array of commits
    // Format: [{ date, author, message }, ...]
  }
}

Register in Timeline (src/timeline.js):

import { NewPlatformProvider } from "./providers/newplatform.js";

const providers = {
  // ...existing
  newplatform: NewPlatformProvider,
};

Add to CLI Menu (src/index.js):

choices: [
  // ...existing
  { name: "🎯 NewPlatform", value: "newplatform" },
];

Dependencies

Package	Purpose
`@inquirer/prompts`	Interactive CLI prompts
`chalk`	Terminal styling
`ora`	Progress spinners
`boxen`	Terminal boxes
`gradient-string`	Gradient text
`chart.js`	Chart generation
`canvas`	Node canvas renderer
`node-fetch`	HTTP requests

🐛 Troubleshooting

Refer the troubleshooting guide TROUBLESHOOTING.md

📝 Scripts

# For users
npm install -g @0xshariq/timeline  # Install globally
npx @0xshariq/timeline              # Run without installing
timeline                            # Run if installed globally

# For developers
pnpm start          # Run the CLI
pnpm run dev        # Run with auto-reload
node index.js       # Direct execution

📦 Publishing to npm

For maintainers:

# Login to npm
npm login

# Bump version
npm version patch  # or minor, or major

# Publish (scoped package)
npm publish --access public

# Verify
npm view @0xshariq/timeline

� License

ISC License - Feel free to use and modify!

🤝 Contributing

Contributions welcome! Ideas:

🔐 Add built-in auth token support
📊 More chart types (bar, pie)
🎨 Additional color schemes
📁 Export to JSON/CSV
🌍 More Git platforms
📱 Generate HTML reports

🙏 Acknowledgments

Built with amazing open-source tools:

Chart.js - Powerful charting
Inquirer - Beautiful prompts
Chalk - Terminal styling
Ora - Elegant spinners

Made with ❤️ and ☕

Happy Analyzing! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
docs		docs
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

0xshariq/timeline

Folders and files

Latest commit

History

Repository files navigation