📈 GitHub Stargazers Growth Plotter

Note: As the stargazers API for 3rd party repos gets deprecated or restricted, repository owners can use this tool to easily fetch and publish their own repository's growth charts!

🚀 GitHub Stargazers Growth Plotter is an automated tool that fetches the stargazers history of any GitHub repository, caches it locally, and generates a stunning SVG growth plot. Designed for repository owners, this script can auto-publish charts directly to your README.md for maximum visibility and better SEO indexing of project metrics.

✨ Features

• 🔐 Automated Authentication: Seamlessly integrates with your active GitHub CLI (gh) token. Zero manual token configuration required!
• 🎯 Zero-Config Context: Automatically detects your current repository from your git config if run without arguments.
• 🗄️ Local Caching: Caches historical stargazer data in a CSV file and dynamically appends it to your .gitignore to prevent accidental commits.
• 📊 High-Quality Plotting: Renders beautiful, scalable vector .svg plots optimized for web display, saving them cleanly in an assets/ directory.
• 📝 Auto-Publishing: With a simple flag, automatically inject your latest growth chart into your README.md within a perfectly centered HTML block.

🛠️ Prerequisites

1. Python 3.x: Ensure Python is installed on your system.
2. GitHub CLI (gh): You must have the GitHub CLI installed and authenticated.

   gh auth login

3. Installation: Install the tool via PyPI:

   pip install github-growth-plotter

   (To install from source locally, clone the repo and run pip install .)

🚀 Usage Guide

1️⃣ Run for the current repository

If you are already inside a Git repository folder, you can simply run:

github-growth-plot

This detects the repository, downloads the stargazers to a CSV, and outputs the SVG plot in the assets/ directory.

2️⃣ Run for a specific repository

You can specify any repository using the standard owner/repo format:

github-growth-plot "google/jax"

3️⃣ Auto-publish to README

Want to display the chart on your project's main page? Pass the --publish flag:

github-growth-plot --publish

This automatically appends the following HTML snippet to the bottom of your README.md:

## Star History

<a href="https://star-history.com/#<username>/<reponame>&Timeline" align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/<username>_<reponame>_growth.svg">
    <img alt="Star History Chart" src="assets/<username>_<reponame>_growth.svg">
  </picture>
</a>

📂 Generated Files

When executed, the script generates and manages the following files:

• 🖼️ assets/<username>_<reponame>_growth.svg: The generated vector graph showing star growth over time.
• 📄 <username>_<reponame>_stargazers.csv: Raw historical star data (automatically ignored via .gitignore).
• 🙈 .gitignore: Updated automatically to ignore the generated CSV file.

Star History

---

Made with ❤️ for Open Source Maintainers.