{"_id":"@0xshariq/timeline","_rev":"5-6880411bfb63501ab641a653a68fc9ca","name":"@0xshariq/timeline","dist-tags":{"latest":"3.1.1"},"versions":{"2.0.0":{"name":"@0xshariq/timeline","version":"2.0.0","keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"author":{"name":"0xshariq"},"license":"ISC","_id":"@0xshariq/timeline@2.0.0","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"homepage":"https://github.com/0xshariq/timeline#readme","bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"bin":{"timeline":"index.js"},"dist":{"shasum":"f39ef1273f16668d6218b039a7abfa1214047255","tarball":"https://registry.npmjs.org/@0xshariq/timeline/-/timeline-2.0.0.tgz","fileCount":13,"integrity":"sha512-nyWfD7UPQEKgu5uh0NlYZjW7JrXU8vHsxrob+K2wKCj2cgV4UwVkpz8kv9l8I3I/rG5Vgm56ihGjWBaFgsJUdA==","signatures":[{"sig":"MEYCIQDt5zJIkxK6he464kqDhnaQprGN62Vg3URNI2n5lRRAdAIhANNlYzsNWwuKFg3ukpler27i1FkpZYbHVdL8E9vCFdCn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68669},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"fb6755478eadcac3f9c52e74d2c9b3d5a3b8e0a7","scripts":{"dev":"node --watch index.js","start":"node index.js"},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"repository":{"url":"git+https://github.com/0xshariq/timeline.git","type":"git"},"_npmVersion":"11.6.1","description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","directories":{},"_nodeVersion":"24.9.0","dependencies":{"ora":"^9.0.0","boxen":"^8.0.1","chalk":"^5.3.0","canvas":"^3.0.0","chart.js":"^4.4.7","date-fns":"^4.1.0","commander":"^12.1.0","node-fetch":"^3.3.2","gradient-string":"^3.0.0","@inquirer/prompts":"^7.0.1","chartjs-chart-matrix":"^2.0.1","chartjs-plugin-datalabels":"^2.2.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/timeline_2.0.0_1762081140991_0.2746467352825752","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@0xshariq/timeline","version":"2.1.0","keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"author":{"name":"0xshariq"},"license":"ISC","_id":"@0xshariq/timeline@2.1.0","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"homepage":"https://github.com/0xshariq/timeline#readme","bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"bin":{"timeline":"dist/index.js"},"dist":{"shasum":"4e4367a5087371133ed6d4e20c37cd860e5f94f1","tarball":"https://registry.npmjs.org/@0xshariq/timeline/-/timeline-2.1.0.tgz","fileCount":86,"integrity":"sha512-X7RYmLSxHO5uOs8PWbs3rHdKFtY2kX/5tRRGUgcnvHR9ji27vSCk3cwYav5VEbY2YZbJmD5ND6HlryuczOmMFQ==","signatures":[{"sig":"MEQCIAXUdfDecrjCJ/T7q5ZSGHUwMY12Xpz4gIdaEgiEAXE1AiA/413vc5qZP2drbKhT7+gVsKPhjSj2p8JPuyQLv790+A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":280321},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9e55249bc69cb6b74f34f09933e66c558d9f82b7","scripts":{"dev":"node --watch dist/index.js","build":"tsc -p .","start":"node dist/index.js","postinstall":"pnpm rebuild canvas || echo 'Canvas rebuild failed, will auto-fix on first run'"},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"repository":{"url":"git+https://github.com/0xshariq/timeline.git","type":"git"},"_npmVersion":"11.6.1","description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","directories":{},"_nodeVersion":"24.9.0","dependencies":{"ora":"^9.0.0","boxen":"^8.0.1","chalk":"^5.3.0","canvas":"^3.0.0","chart.js":"^4.4.7","date-fns":"^4.1.0","commander":"^12.1.0","node-fetch":"^3.3.2","typescript":"5.9.3","gradient-string":"^3.0.0","@inquirer/prompts":"^7.0.1","chartjs-chart-matrix":"^2.0.1","chartjs-plugin-datalabels":"^2.2.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.9.2","@types/gradient-string":"1.1.6"},"_npmOperationalInternal":{"tmp":"tmp/timeline_2.1.0_1762162385805_0.4038290050130522","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@0xshariq/timeline","version":"3.0.0","keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"author":{"name":"0xshariq"},"license":"ISC","_id":"@0xshariq/timeline@3.0.0","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"homepage":"https://github.com/0xshariq/timeline#readme","bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"bin":{"timeline":"dist/index.js"},"dist":{"shasum":"2ccbe6089091de6fd57a212f75ecff42c0d49628","tarball":"https://registry.npmjs.org/@0xshariq/timeline/-/timeline-3.0.0.tgz","fileCount":119,"integrity":"sha512-syMCr5DPyF/v8Q1KfXKAKWrXvOC7gT2fvxtHzoJwJ/X+9Z6MWeS5nziek7b3zWYnfB74rkfRa/eQ9dCWDwiyAQ==","signatures":[{"sig":"MEUCIBnFC14njPJrB1UgY6k19JtGNdf2VPfyp4CHxlZZ2LTiAiEA3qTdclbfDiGj1fN3SKo5RO+7GBmTJ9JY8E+dRcs/yNs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":364595},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"f1365e4accfe241830ec60e94acf27e6463e901f","scripts":{"dev":"node --watch dist/index.js","build":"tsc -p .","start":"node dist/index.js","postinstall":"pnpm rebuild canvas || echo 'Canvas rebuild failed, will auto-fix on first run'"},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"repository":{"url":"git+https://github.com/0xshariq/timeline.git","type":"git"},"_npmVersion":"11.6.1","description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","directories":{},"_nodeVersion":"24.9.0","dependencies":{"ora":"^9.0.0","boxen":"^8.0.1","chalk":"^5.3.0","three":"0.181.0","canvas":"^3.0.0","chart.js":"^4.4.7","date-fns":"^4.1.0","commander":"^12.1.0","node-fetch":"^3.3.2","typescript":"5.9.3","@types/three":"0.181.0","gradient-string":"^3.0.0","@inquirer/prompts":"^7.0.1","chartjs-chart-matrix":"^2.0.1","chartjs-plugin-datalabels":"^2.2.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.9.2","@types/gradient-string":"1.1.6"},"_npmOperationalInternal":{"tmp":"tmp/timeline_3.0.0_1762171799134_0.6911987312425434","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@0xshariq/timeline","version":"3.1.0","keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"author":{"name":"0xshariq"},"license":"ISC","_id":"@0xshariq/timeline@3.1.0","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"homepage":"https://github.com/0xshariq/timeline#readme","bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"bin":{"timeline":"dist/index.js"},"dist":{"shasum":"36434280a82c1c272c441d7e3a73dc87729acce4","tarball":"https://registry.npmjs.org/@0xshariq/timeline/-/timeline-3.1.0.tgz","fileCount":119,"integrity":"sha512-rUmbGX/GATdx7zbCt8y40ktELWJyBuTGzqFtC9q8JsUmekqIbVIaklqhl6ClXV5vPO8VvbVMrowoMz3G/IULow==","signatures":[{"sig":"MEQCIG6X2Z2HSvUuQw83IZiKfTD0PlKVkBX1j/Td1HIq6j+2AiBlFkKME9ER5hBMmX/9PCGxKtx5auRwM0ErfqJ3iZKPvw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":366167},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"c5ae6921de732c97b4aa873034671332fe476cfc","scripts":{"dev":"node --watch dist/index.js","build":"tsc -p .","start":"node dist/index.js","postinstall":"pnpm rebuild canvas || echo 'Canvas rebuild failed, will auto-fix on first run'"},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"repository":{"url":"git+https://github.com/0xshariq/timeline.git","type":"git"},"_npmVersion":"11.6.1","description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","directories":{},"_nodeVersion":"24.9.0","dependencies":{"ora":"^9.0.0","boxen":"^8.0.1","chalk":"^5.3.0","three":"0.181.0","canvas":"^3.0.0","chart.js":"^4.4.7","date-fns":"^4.1.0","commander":"^12.1.0","node-fetch":"^3.3.2","typescript":"5.9.3","@types/three":"0.181.0","gradient-string":"^3.0.0","@inquirer/prompts":"^7.0.1","chartjs-chart-matrix":"^2.0.1","chartjs-plugin-datalabels":"^2.2.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"24.9.2","@types/gradient-string":"1.1.6"},"_npmOperationalInternal":{"tmp":"tmp/timeline_3.1.0_1762172676981_0.5810419397411821","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@0xshariq/timeline","version":"3.1.1","description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","main":"dist/index.js","bin":{"timeline":"dist/index.js"},"scripts":{"start":"node dist/index.js","build":"tsc -p .","dev":"node --watch dist/index.js","postinstall":"pnpm rebuild canvas || echo 'Canvas rebuild failed, will auto-fix on first run'"},"keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"repository":{"type":"git","url":"git+https://github.com/0xshariq/timeline.git"},"bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"homepage":"https://github.com/0xshariq/timeline#readme","author":{"name":"0xshariq"},"license":"ISC","type":"module","dependencies":{"@inquirer/prompts":"^7.0.1","@types/three":"0.181.0","boxen":"^8.0.1","canvas":"^3.2.0","chalk":"^5.3.0","chart.js":"^4.4.7","chartjs-chart-matrix":"^2.0.1","chartjs-node-canvas":"5.0.0","chartjs-plugin-datalabels":"^2.2.0","commander":"^12.1.0","date-fns":"^4.1.0","gradient-string":"^3.0.0","node-fetch":"^3.3.2","ora":"^9.0.0","three":"0.181.0","typescript":"5.9.3"},"engines":{"node":">=18.0.0"},"devDependencies":{"@types/gradient-string":"1.1.6","@types/node":"24.9.2"},"gitHead":"22c45075ce03604337383940eeb8da104706ef43","types":"./dist/index.d.ts","_id":"@0xshariq/timeline@3.1.1","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-PHJhdnXAJ89OYHUzpVsoWR+LNutarJthVvOpJJJj7cadKm0SHgJh2BqfX33uU0aQ9LiH/VZl32VRhurTI7Sp+A==","shasum":"80a8c6a63fcac33d18be93c09838ea92d2e68f6e","tarball":"https://registry.npmjs.org/@0xshariq/timeline/-/timeline-3.1.1.tgz","fileCount":67,"unpackedSize":202616,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD5TWoqAEKtr+NFW7aMhkwZdszcjrk78U+GbOHId3Jv6wIgM3xw7zKf01G66HGVwnv43KAcDfTF/T/H14sWFhVDI9A="}]},"_npmUser":{"name":"0xshariq","email":"khanshariq92213@gmail.com"},"directories":{},"maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/timeline_3.1.1_1774542569142_0.7850674991378708"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-02T10:59:00.904Z","modified":"2026-03-26T16:29:29.420Z","2.0.0":"2025-11-02T10:59:01.188Z","2.1.0":"2025-11-03T09:33:06.025Z","3.0.0":"2025-11-03T12:09:59.333Z","3.1.0":"2025-11-03T12:24:37.226Z","3.1.1":"2026-03-26T16:29:29.293Z"},"bugs":{"url":"https://github.com/0xshariq/timeline/issues"},"author":{"name":"0xshariq"},"license":"ISC","homepage":"https://github.com/0xshariq/timeline#readme","keywords":["git","timeline","github","gitlab","bitbucket","sourcehut","cli","visualization","chart","analytics","commits","pie-chart","bar-chart","heatmap","statistics"],"repository":{"type":"git","url":"git+https://github.com/0xshariq/timeline.git"},"description":"Generate beautiful commit timeline charts for GitHub, GitLab, Bitbucket, and SourceHut repositories with an interactive CLI - supports multiple chart types","maintainers":[{"name":"0xshariq","email":"khanshariq92213@gmail.com"}],"readme":"\n# � Repository Timeline Generator\n\n\n\n\n\n\n**Generate beautiful commit timeline charts for your Git repositories across multiple platforms.**\n\n_Beautiful CLI • Multi-Platform • Interactive • Analytics_\n\n
\n\n---\n\n## ✨ Features\n\n- 🎨 **15 Chart Types** - 10 2D charts (Chart.js) + 5 3D charts (Three.js)\n- 🎨 **Full Customization** - Colors, gradients, borders, animations, scales, labels, tooltips, and legends\n- 🌐 **Multi-Platform Support** - GitHub, GitLab, Bitbucket, and SourceHut\n- 💻 **Interactive CLI** - Gradient banners, colored prompts, progress spinners\n- 📊 **Smart Analytics** - Statistics dashboard with top repositories\n- 🎯 **Flexible Selection** - Analyze all repos or choose specific ones\n- 🚀 **Real-time Progress** - Live updates while fetching commit data\n- � **3D Visualizations** - Modern Three.js powered 3D charts\n- 💾 **Export Options** - High-resolution PNG images\n- ⚙️ **Config Management** - Save default settings\n\n> 📊 **Detailed Chart Documentation:** See [docs/CHARTS.md](docs/CHARTS.md) for comprehensive information about all chart types, including visual examples, use cases, and best practices.\n\n---\n\n## � Quick Start\n\n### Prerequisites\n\nInstall system dependencies for canvas rendering:\n\n**Ubuntu/Debian:**\n\n```bash\nsudo apt update\nsudo apt install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev\n```\n\n**macOS:**\n\n```bash\nbrew install pkg-config cairo pango libpng jpeg giflib librsvg\n```\n\n**Fedora/RHEL:**\n\n```bash\nsudo dnf install gcc-c++ cairo-devel pango-devel libjpeg-turbo-devel giflib-devel\n```\n\n### Installation\n\n#### Option 1: Install from npm (Recommended)\n\n```bash\n# Install globally\nnpm install -g @0xshariq/timeline\n\n# If you get canvas errors, rebuild it:\nnpm rebuild canvas -g\n\n# Run anywhere\ntimeline\n```\n\nOr with pnpm:\n\n```bash\npnpm add -g @0xshariq/timeline\n\n# If you get canvas errors:\npnpm rebuild canvas -g\n\ntimeline\n```\n\nOr with yarn:\n\n```bash\nyarn global add @0xshariq/timeline\n\n# If you get canvas errors:\nyarn global rebuild canvas\n\ntimeline\n```\n\n**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](TROUBLESHOOTING.md).\n\n#### Option 2: Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/0xshariq/timeline.git\ncd timeline\n\n# Install dependencies\npnpm install\n\n# Run the CLI\npnpm start\n\n# Or link globally\npnpm link --global\ntimeline # Now you can use it anywhere!\n```\n\n#### Option 3: Run with npx (No Installation)\n\n```bash\nnpx @0xshariq/timeline\n```\n\n---\n\n## 💻 How to Use\n\n> **🔧 Having issues?** Check the [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems including canvas errors and rate limits.\n\n### ⚠️ Important: GitHub Authentication (Avoid Rate Limits)\n\nGitHub API has strict rate limits:\n\n- **Without authentication**: 60 requests/hour ❌ (Will fail for most users!)\n- **With authentication**: 5,000 requests/hour ✅ (Recommended)\n\n#### Step 1: Create a GitHub Personal Access Token\n\n1. Go to **GitHub.com** → Click your profile picture → **Settings**\n2. Scroll down to **Developer settings** (bottom of left sidebar)\n3. Click **Personal access tokens** → **Tokens (classic)**\n4. Click **Generate new token (classic)**\n5. Give it a name (e.g., \"timeline-cli\")\n6. Select scopes:\n - ✅ **`public_repo`** (required for public repositories)\n - ✅ **`repo`** (only if you want to access private repos)\n7. Click **Generate token** at the bottom\n8. **⚠️ Copy the token immediately** (you won't see it again!)\n\n#### Step 2: Set the Token\n\n**Option A: Temporary (Current Session Only)**\n\n```bash\nexport GITHUB_TOKEN=ghp_your_token_here\ntimeline -p github -u 0xshariq\n```\n\n**Option B: Permanent (Recommended)**\n\nFor **Bash** users (~/.bashrc):\n\n```bash\necho 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc\nsource ~/.bashrc\n```\n\nFor **Zsh** users (~/.zshrc):\n\n```bash\necho 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc\nsource ~/.zshrc\n```\n\nFor **Fish** users:\n\n```bash\nset -Ux GITHUB_TOKEN ghp_your_token_here\n```\n\n#### Step 3: Verify It's Working\n\n```bash\n# Check if token is set\necho $GITHUB_TOKEN\n\n# Test with timeline\ntimeline -p github -u 0xshariq --verbose\n```\n\n#### Troubleshooting Rate Limits\n\n**If you still see \"403: rate limit exceeded\":**\n\n1. Make sure token is set: `echo $GITHUB_TOKEN`\n2. Verify token has correct permissions on GitHub\n3. Wait for rate limit reset (error shows reset time)\n4. Try with fewer repositories: `timeline -p github -u username -r \"repo1,repo2\"`\n\n**Security Tips:**\n\n- Never commit tokens to Git repositories\n- Use minimum required permissions\n- Rotate tokens periodically\n- Revoke unused tokens in GitHub settings\n\n### Basic Usage\n\n```bash\n# Interactive mode (recommended for beginners)\ntimeline\n\n# Or with npx (no installation)\nnpx @0xshariq/timeline\n```\n\n### Command-Line Flags\n\nTimeline supports powerful command-line flags for automation:\n\n```bash\ntimeline [options]\ntimeline [options]\n```\n\n#### Global Options\n\n| Flag | Alias | Description | Example |\n| ----------------------- | ------------- | --------------------------- | ------------------ |\n| `-p, --platform ` | | Git platform | `-p github` |\n| `-u, --username ` | | Username | `-u octocat` |\n| `-r, --repos ` | | Comma-separated repos | `-r \"repo1,repo2\"` |\n| `-a, --all` | | Analyze all repos | `--all` |\n| `-t, --type ` | `-c, --chart` | Chart type | `-t line` |\n| `-v, --verbose` | | Show detailed output | `--verbose` |\n| `-q, --quiet` | | Minimal output | `--quiet` |\n| `--no-merge` | | Exclude merge commits | `--no-merge` |\n| `-o, --open` | | Open chart after generation | `--open` |\n| `-V, --version` | | Show version | `--version` |\n| `-h, --help` | | Show help | `--help` |\n\n#### Chart Customization Options\n\n**Colors & Gradients:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--colors ` | Custom colors (hex, comma-separated) | `--colors \"#FF5733,#33FF57,#3357FF\"` |\n| `--gradient` | Enable gradient colors | `--gradient` |\n| `--gradient-start ` | Gradient start color | `--gradient-start \"#667eea\"` |\n| `--gradient-end ` | Gradient end color | `--gradient-end \"#764ba2\"` |\n\n**Borders:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--border-width ` | Border width (number) | `--border-width 3` |\n| `--border-color ` | Border color (hex) | `--border-color \"#000000\"` |\n\n**Animations:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--no-animate` | Disable animations | `--no-animate` |\n| `--animation-duration ` | Animation duration | `--animation-duration 2000` |\n| `--animation-easing ` | Easing function | `--animation-easing \"easeInOutCubic\"` |\n\n**Scales:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--scale-type ` | Scale type (linear, logarithmic, time) | `--scale-type logarithmic` |\n| `--no-zero` | Don't begin Y-axis at zero | `--no-zero` |\n| `--no-grid` | Hide grid lines | `--no-grid` |\n\n**Labels & Text:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--no-labels` | Hide labels | `--no-labels` |\n| `--label-size ` | Label font size | `--label-size 14` |\n| `--label-color ` | Label color (hex) | `--label-color \"#333333\"` |\n\n**Tooltips:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--no-tooltips` | Disable tooltips | `--no-tooltips` |\n| `--tooltip-bg ` | Tooltip background color | `--tooltip-bg \"rgba(0,0,0,0.9)\"` |\n\n**Legend:**\n| Flag | Description | Example |\n|------|-------------|---------|\n| `--no-legend` | Hide legend | `--no-legend` |\n| `--legend-position ` | Position (top, bottom, left, right) | `--legend-position right` |\n\n> Refer customization guide [CUSTOMIZATION.md](docs/CUSTOMIZATION.md)\n\n### Subcommands\n\n#### 1. `quick` - Quick generation\n\n```bash\ntimeline quick -p -u [options]\n\n# Examples\ntimeline quick -p github -u octocat\ntimeline quick -p gitlab -u johndoe -t pie\ntimeline quick -p bitbucket -u alice --no-merge\n```\n\n**Required options:**\n\n- `-p, --platform` - Platform name\n- `-u, --username` - Username\n\n**Optional:**\n\n- `-t, --type` - Chart type (default: line)\n- `--no-merge` - Exclude merge commits\n\n#### 2. `platforms` - List platforms\n\n```bash\ntimeline platforms\n\n# Output:\n# 📦 Supported Platforms:\n# 🐙 github - GitHub\n# 🦊 gitlab - GitLab\n# 🪣 bitbucket - Bitbucket\n# 🎯 sourcehut - SourceHut\n```\n\n#### 3. `charts` - List chart types\n\n```bash\ntimeline charts\n\n# Output:\n# 📊 Available Chart Types:\n# 📈 line - Timeline of commits over time\n# 📊 bar - Compare commits across repositories\n# 🥧 pie - Repository contribution percentage\n# 🍩 doughnut - Like pie chart with center hole\n# 📡 radar - Multi-dimensional comparison\n# 🔥 heatmap - Activity calendar (GitHub-style)\n```\n\n#### 4. `config` - Show configuration\n\n```bash\ntimeline config\n\n# Shows package version, Node version, etc.\n```\n\n#### 5. `examples` - Show usage examples\n\n```bash\ntimeline examples\n\n# Displays common usage patterns\n```\n\n### Usage Examples\n\n#### Interactive Mode\n\n```bash\n# Full interactive experience\ntimeline\n```\n\nYou'll be prompted for:\n\nYou'll be prompted for:\n\n1. **Platform Selection** - Choose your Git platform\n2. **Username** - Enter your username\n3. **Repository Selection** - All or specific repos\n4. **Chart Type** - Choose visualization type\n5. **Options** - Verbosity, merge commits, auto-open\n\n#### Quick Commands\n\n```bash\n# GitHub user with line chart (default)\ntimeline quick -p github -u octocat\n\n# GitLab user with pie chart\ntimeline quick -p gitlab -u johndoe -t pie\n\n# Bitbucket with bar chart, no merge commits\ntimeline quick -p bitbucket -u alice -t bar --no-merge\n```\n\n#### With Flags (Skip Prompts)\n\n```bash\n# Specific platform and user\ntimeline -p github -u octocat\n\n# All repos with verbose output\ntimeline -p github -u octocat --all --verbose\n\n# Specific repos with heatmap\ntimeline -p gitlab -u johndoe -r \"project1,project2,project3\" -t heatmap\n\n# Pie chart, open automatically\ntimeline -p bitbucket -u bob --all -t pie --open\n\n# Bar chart without merge commits, quiet mode\ntimeline -p github -u charlie --all -t bar --no-merge --quiet\n```\n\n#### Chart Customization Examples\n\n```bash\n# Custom colors (3 repositories with specific colors)\ntimeline -p github -u octocat -t bar --colors \"#FF5733,#33FF57,#3357FF\"\n\n# Gradient colors for line chart\ntimeline -p github -u octocat -t line --gradient --gradient-start \"#667eea\" --gradient-end \"#764ba2\"\n\n# Thick borders with custom color\ntimeline -p github -u octocat -t pie --border-width 5 --border-color \"#FF0000\"\n\n# No animations for faster generation\ntimeline -p github -u octocat -t bar --no-animate\n\n# Logarithmic scale for large value differences\ntimeline -p github -u octocat -t line --scale-type logarithmic\n\n# Large labels with custom color\ntimeline -p github -u octocat -t bar --label-size 16 --label-color \"#FF6B6B\"\n\n# No grid lines, no legend for clean look\ntimeline -p github -u octocat -t line --no-grid --no-legend\n\n# Right-positioned legend\ntimeline -p github -u octocat -t pie --legend-position right\n\n# Combine multiple customizations\ntimeline -p github -u octocat -t bar \\\n --colors \"#FF6B6B,#4ECDC4,#45B7D1,#FFA07A,#98D8C8\" \\\n --border-width 3 \\\n --label-size 14 \\\n --no-grid \\\n --animation-duration 2000\n\n# Perfect for presentations (clean, no tooltips)\ntimeline -p github -u octocat -t pie \\\n --colors \"#667eea,#764ba2,#f093fb,#4facfe\" \\\n --no-tooltips \\\n --label-size 16 \\\n --border-width 0\n\n# Heatmap with custom colors\ntimeline -p github -u octocat -t heatmap \\\n --gradient \\\n --gradient-start \"#9be9a8\" \\\n --gradient-end \"#216e39\"\n```\n\n#### Automation & CI/CD\n\n```bash\n# Perfect for scripts and automation\ntimeline quick -p github -u $GIT_USERNAME -t line\n\n# Generate multiple charts\nfor type in line bar pie; do\n timeline quick -p github -u octocat -t $type\ndone\n\n# Environment variables\nexport TIMELINE_PLATFORM=github\nexport TIMELINE_USER=octocat\ntimeline quick -p $TIMELINE_PLATFORM -u $TIMELINE_USER\n```\n\n### Interactive Workflow\n\nWhen you run `timeline` in interactive mode:\n\n**Step 1: Platform**\n\n**Step 4: Chart Type**\n\n```\n? Select chart type: (Use arrow keys)\n❯ 📈 Line Chart - Timeline of commits over time\n 📊 Bar Chart - Compare commits across repositories\n 🥧 Pie Chart - Repository contribution percentage\n 🍩 Doughnut Chart - Like pie chart with center hole\n 📡 Radar Chart - Multi-dimensional repository comparison\n 🔥 Heatmap - Activity calendar (GitHub-style)\n```\n\n**Step 5: Options**\n\n**Step 5: Options**\n\n```\n? Select options: (Press space to select)\n❯ ◉ Show detailed progress\n ◉ Include merge commits\n ◯ Open chart after generation\n```\n\n**Step 6: Processing**\n\n**Step 6: Processing**\n\n```\n──────────────────────────────────────────────────\n\n⠼ Processing awesome-project (3/12)\nℹ Found 12 repositories\n✓ my-library: 89 commits\n✓ cli-tool: 143 commits\n⚠ Skipped empty-repo: No commits found\n✓ awesome-project: 67 commits\n...\n```\n\n**Step 7: Results**\n\n**Statistics Summary:**\n\n```\n📊 Statistics Summary\n─────────────────────\nTotal Commits: 847\nRepositories: 12\nDate Range: 2023-01-15 to 2024-11-02 (657 days)\nAverage per Repo: 70 commits\nAverage per Day: 1.29 commits\n\n🏆 Top Repositories:\n 1. cli-tool: 143 commits\n 2. my-library: 89 commits\n 3. awesome-project: 67 commits\n 4. web-app: 58 commits\n 5. api-server: 52 commits\n```\n\n**Success Message:**\n\n```\n╭─────────────────────────────────────────────╮\n│ │\n│ ✨ Chart saved as timeline.png ✨ │\n│ │\n│ You can find it in the current directory │\n│ │\n╰─────────────────────────────────────────────╯\n```\n\n---\n\n## 🌐 Supported Platforms\n\n| Platform | Support | API Version | Rate Limit |\n| ---------------- | ------- | ----------- | ---------- |\n| **GitHub** 🐙 | ✅ Full | REST v3 | 60/hour |\n| **GitLab** 🦊 | ✅ Full | REST v4 | 10/sec |\n| **Bitbucket** 🪣 | ✅ Full | API 2.0 | Varies |\n| **SourceHut** 🎯 | ✅ Full | GraphQL | Check docs |\n\n### Increase Rate Limits (Optional)\n\nAdd authentication tokens to provider files for higher limits:\n\n**GitHub** (`src/providers/github.js`):\n\n```javascript\nasync fetchRepos() {\n const res = await fetch(`${this.baseUrl}/users/${this.username}/repos`, {\n headers: { 'Authorization': 'token YOUR_GITHUB_TOKEN' }\n });\n // ...\n}\n```\n\n**GitLab** (`src/providers/gitlab.js`):\n\n```javascript\nheaders: { 'PRIVATE-TOKEN': 'YOUR_GITLAB_TOKEN' }\n```\n\n---\n\n## 📈 Chart Types\n\n### 2D Charts (Chart.js)\n\n| Chart Type | Best For | Output |\n|------------|----------|--------|\n| 📈 **Line** | Timeline trends, activity patterns | `timeline-line.png` |\n| 📊 **Bar** | Repository comparison, totals | `timeline-bar.png` |\n| 🥧 **Pie** | Contribution percentages | `timeline-pie.png` |\n| 🍩 **Doughnut** | Modern contribution breakdown | `timeline-doughnut.png` |\n| 📡 **Radar** | Multi-metric comparison | `timeline-radar.png` |\n| 🔥 **Heatmap** | Daily activity calendar | `timeline-heatmap.png` |\n| 🎯 **Polar Area** | Radial visualization | `timeline-polarArea.png` |\n| ⚡ **Scatter** | Pattern detection | `timeline-scatter.png` |\n| � **Bubble** | Multi-dimensional data | `timeline-bubble.png` |\n| 🎨 **Mixed** | Combined line + bar | `timeline-mixed.png` |\n\n### 3D Charts (Three.js)\n\n| Chart Type | Best For | Output | Status |\n|------------|----------|--------|--------|\n| � **Bar 3D** | Impressive presentations | `timeline-bar3d.png` | ✅ Available |\n| 📈 **Line 3D** | 3D trend visualization | `timeline-line3d.png` | 🚧 Coming Soon |\n| 🔮 **Scatter 3D** | Multi-dimensional patterns | `timeline-scatter3d.png` | 🚧 Coming Soon |\n| 🌊 **Surface 3D** | Activity landscapes | `timeline-surface3d.png` | 🚧 Coming Soon |\n| � **Bubble 3D** | Four-dimensional data | `timeline-bubble3d.png` | 🚧 Coming Soon |\n\n> 📚 **Full Documentation:** For detailed information about each chart type, including visual characteristics, features, and usage examples, see [docs/CHARTS.md](docs/CHARTS.md)\n\n### Quick Examples\n\n```bash\n# 2D Line chart (default)\ntimeline -p github -u octocat\n\n# 3D Bar chart\ntimeline -p github -u octocat -t bar3d\n\n# Heatmap for daily patterns\ntimeline -p github -u octocat -t heatmap\n\n# Pie chart with custom colors\ntimeline -p github -u octocat -t pie --colors \"#FF6B6B,#4ECDC4,#45B7D1\"\n```\n\n---\n\n## 🏗️ Project Structure\n\n```\nrepo-timeline/\n├── src/\n│ ├── index.js # CLI entry point (styled prompts)\n│ ├── timeline.js # Core logic & orchestration\n│ ├── chart.js # Chart.js configuration\n│ ├── config.default.js # Default settings\n│ ├── providers/ # Platform-specific APIs\n│ │ ├── github.js # GitHub integration\n│ │ ├── gitlab.js # GitLab integration\n│ │ ├── bitbucket.js # Bitbucket integration\n│ │ └── sourcehut.js # SourceHut integration\n│ └── utils/ # Helper utilities\n│ ├── colors.js # Color schemes\n│ └── stats.js # Statistics calculations\n├── index.js # Entry point\n├── package.json # Dependencies & scripts\n└── README.md # Documentation\n```\n\n---\n\n## 🎨 CLI Features\n\n### Visual Components\n\n| Feature | Description |\n| -------------------- | ---------------------------------- |\n| 🎨 Gradient Banners | Eye-catching startup screen |\n| 🌈 Colored Prompts | Cyan questions, gray feedback |\n| ⏳ Progress Spinners | Real-time animated feedback |\n| 📦 Styled Boxes | Important messages in frames |\n| ✓ Status Icons | Success (✓), Info (ℹ), Warning (⚠) |\n| 🎯 Emoji Indicators | Visual context throughout |\n\n### Interactive Options\n\n```javascript\n// Available configurations\n{\n verbose: true, // Show detailed progress\n includeMerges: true, // Include merge commits\n openChart: false // Auto-open after generation\n}\n```\n\n---\n\n## 🔧 Development\n\n### Run in Development Mode\n\n```bash\npnpm run dev # Auto-reload on file changes\n```\n\n### Adding New Platforms\n\n1. **Create Provider** (`src/providers/newplatform.js`):\n\n```javascript\nexport class NewPlatformProvider {\n constructor(username) {\n this.username = username;\n this.baseUrl = \"https://api.newplatform.com\";\n }\n\n async fetchRepos() {\n // Return array of repo names\n }\n\n async fetchAllCommits(repo, config) {\n // Return array of commits\n // Format: [{ date, author, message }, ...]\n }\n}\n```\n\n2. **Register in Timeline** (`src/timeline.js`):\n\n```javascript\nimport { NewPlatformProvider } from \"./providers/newplatform.js\";\n\nconst providers = {\n // ...existing\n newplatform: NewPlatformProvider,\n};\n```\n\n3. **Add to CLI Menu** (`src/index.js`):\n\n```javascript\nchoices: [\n // ...existing\n { name: \"🎯 NewPlatform\", value: \"newplatform\" },\n];\n```\n\n### Dependencies\n\n| Package | Purpose |\n| ------------------- | ----------------------- |\n| `@inquirer/prompts` | Interactive CLI prompts |\n| `chalk` | Terminal styling |\n| `ora` | Progress spinners |\n| `boxen` | Terminal boxes |\n| `gradient-string` | Gradient text |\n| `chart.js` | Chart generation |\n| `canvas` | Node canvas renderer |\n| `node-fetch` | HTTP requests |\n\n---\n\n## 🐛 Troubleshooting\n\n> Refer the troubleshooting guide [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)\n\n---\n\n## 📝 Scripts\n\n```bash\n# For users\nnpm install -g @0xshariq/timeline # Install globally\nnpx @0xshariq/timeline # Run without installing\ntimeline # Run if installed globally\n\n# For developers\npnpm start # Run the CLI\npnpm run dev # Run with auto-reload\nnode index.js # Direct execution\n```\n\n---\n\n## 📦 Publishing to npm\n\nFor maintainers:\n\n```bash\n# Login to npm\nnpm login\n\n# Bump version\nnpm version patch # or minor, or major\n\n# Publish (scoped package)\nnpm publish --access public\n\n# Verify\nnpm view @0xshariq/timeline\n```\n\n---\n\n## � License\n\nISC License - Feel free to use and modify!\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Ideas:\n\n- 🔐 Add built-in auth token support\n- 📊 More chart types (bar, pie)\n- 🎨 Additional color schemes\n- 📁 Export to JSON/CSV\n- 🌍 More Git platforms\n- 📱 Generate HTML reports\n\n---\n\n## 🙏 Acknowledgments\n\nBuilt with amazing open-source tools:\n\n- [Chart.js](https://www.chartjs.org/) - Powerful charting\n- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Beautiful prompts\n- [Chalk](https://github.com/chalk/chalk) - Terminal styling\n- [Ora](https://github.com/sindresorhus/ora) - Elegant spinners\n\n---\n\n\n\n**Made with ❤️ and ☕**\n\n_Happy Analyzing!_ 🚀\n\n
\n","readmeFilename":"README.md"}