# GitHub Repository Clone Statistics Tracker
Git Stats is the missing piece of GitHub analytics - even if you pay, they will only give you 14 days of history. Bizarre gap for a company built on data...
But I digress. Git Stats is an agressively simple Python application for tracking and storing GitHub repository clone statistics. It has an extremely minimal HTML & JS frontend that requires no building, compiling or transpiling.
The tool fetches clone data from the GitHub API and maintains historical records in a SQLite database. It runs as an always on service and periodically fetches clone stats (total and unique) and displays them in an easy to use dashboard with shields.io badges available for use.
<div align="center">
<video width=832 src="https://github.com/user-attachments/assets/ba4b670f-f0d3-4db6-9c18-e9480486ba84"></video>
</div>
---
## Features
- **Complete GitHub Analytics**: Fetches repository clone statistics (total clones and unique cloners) and star counts from the GitHub API
- **Historical Data Storage**: Maintains unlimited historical records in a SQLite database with robust querying capabilities
- **Smart Data Management**: Avoids duplicate entries by only recording new data points
- **Web Dashboard**: Modern, responsive UI with automatic background synchronization and dark/light theme support
- **Interactive Visualizations**: Time-series charts with customizable date ranges and repository filtering
- **Shields.io Badge Integration**: Generates embeddable badges for README files and documentation
- **Cloud-Ready Deployment**: One-command deployment to Google App Engine with auto-scaling
- **Repository Management**: Add/remove tracked repositories through the web interface
- **Data Export/Import**: Backup and migration functionality for database portability
- **Flexible Sync Intervals**: Configurable automatic synchronization (daily, weekly, biweekly)
- **Modern CLI Interface**: Subcommands for sync and server operations with comprehensive help
- **PyPI-Ready Packaging**: Modern Python tooling support with uv compatibility for fast installation
### Quickstart with uv
Run directly without installation:
```bash
uv run git-clone-stats sync
uv run git-clone-stats server
```
## Installation
### From PyPI (recommended)
```bash
pip install git-clone-stats
```
### With uv (fastest)
```bash
uv tool install git-clone-stats
# or run directly without installing
uv run git-clone-stats --help
```
### From source
```bash
git clone https://github.com/taylorwilsdon/git-clone-stats.git
cd git-clone-stats
pip install -e .
```
## Configuration
Set up your GitHub Personal Access Token and Username. This requires a GitHub Personal Access Token with the `repo` scope to access repository traffic data.
1. Create a token in your [GitHub Developer settings](https://github.com/settings/tokens)
2. Set the required environment variables:
```bash
export GITHUB_TOKEN='your_github_personal_access_token'
export GITHUB_USERNAME='your_github_username'
```
## Usage
### Command Line Interface
The application provides a modern CLI with subcommands:
```bash
git-clone-stats --help
```
#### Sync clone data
To fetch the latest clone statistics from GitHub and update the database:
```bash
git-clone-stats sync
```
#### Start web server
To start the web dashboard server:
```bash
git-clone-stats server --port 8000
```
### Retrieving Stored Data
You can query the `github_stats.db` SQLite database directly to retrieve historical data.
Here are some example queries you can run from your terminal:
**1. Open the database:**
```bash
sqlite3 github_stats.db
```
**2. View all records for a specific repository:**
```sql
SELECT * FROM clone_history WHERE repo = 'reclaimed';
```
**3. Get the total clone count for a repository:**
```sql
SELECT SUM(count) FROM clone_history WHERE repo = 'reclaimed';
```
**4. Get the total unique cloners for a repository:**
```sql
SELECT SUM(uniques) FROM clone_history WHERE repo = 'reclaimed';
```
**5. View all data, ordered by repository and date:**
```sql
SELECT * FROM clone_history ORDER BY repo, timestamp;
```
## Web Server & User Interface
The application includes a web server that provides a user interface for viewing repository statistics, a JSON API, and automatic background synchronization.
### Running the Server
To start the server:
```bash
git-clone-stats server --port 8000
```
The server will be available at `http://localhost:8000`.
### Automatic Background Sync
By default, the server will automatically sync with GitHub every 24 hours. You can configure the sync interval by setting the `SYNC_INTERVAL` environment variable before running the server.
Supported values are:
- `daily` (default)
- `weekly`
- `biweekly`
**Example:**
```bash
export SYNC_INTERVAL='weekly'
git-clone-stats server
```
### User Interface
Navigate to `http://localhost:8000` in your web browser to access the user interface. The dashboard provides two viewing modes:
<div align="center">
<img width="70%" height="70%" alt="image" src="https://github.com/user-attachments/assets/f16b879d-f629-49a0-9fec-c17e827156b2" />
</div>
#### Card View (Default)
Displays a card for each repository with:
- The repository name and star count
- Total clone and unique cloner counts
- Collection date range (first/last sync)
- A shields.io badge preview
- A button to copy the badge's Markdown code
#### Chart View
Interactive time-series visualization showing:
- **Line charts** for each repository displaying clone trends over time
- **Dual metrics**: Both total clones (blue) and unique clones (green) on the same chart
- **Time period filters**: View data for the last 7 days, 30 days, 3 months, or all time
- **Repository filtering**: Focus on specific repositories or view all
- **Responsive design**: Charts adapt to screen size and respect dark/light themes
- **Interactive tooltips**: Hover over data points for detailed daily statistics
<div align="center">
<img width="70%" height="70%" alt="image" src="https://github.com/user-attachments/assets/4d6248ee-292b-41a6-b79d-179c53c8baf7" />
</div>
#### Additional Features
- **Dark/Light theme toggle** in the top-right corner
- **Search and sorting** functionality for repositories (card view)
- **Repository management** modal for adding/removing tracked repositories
- **Data export/import** functionality for backup and migration
- **"Sync with GitHub"** button that triggers a fresh data pull from the GitHub API
### API Endpoints
- **`GET /stats`**
Returns a JSON array of all clone statistics from the database.
**Example Response:**
```json
[
{
"repo": "google_workspace_mcp",
"timestamp": "2024-07-05T00:00:00Z",
"count": 1,
"uniques": 1
},
{
"repo": "google_workspace_mcp",
"timestamp": "2024-07-06T00:00:00Z",
"count": 1,
"uniques": 1
}
]
```
- **`GET /chart-data?days=<number>&repo=<repo-name>`**
Returns time-series data formatted for chart visualization.
**Query Parameters:**
- `days` (optional): Number of days to include (7, 30, 90, or 0 for all time). Default: 30
- `repo` (optional): Filter by specific repository name
**Example:**
`http://localhost:8000/chart-data?days=30&repo=my-repo`
**Example Response:**
```json
{
"chart_data": {
"my-repo": {
"labels": ["2024-07-01", "2024-07-02", "2024-07-03"],
"clones": [5, 3, 8],
"uniques": [4, 2, 6]
}
},
"days_requested": 30,
"repo_filter": "my-repo"
}
```
- **`GET /badge/<repo-name>`**
Returns a shields.io badge displaying the total clone count for the specified repository.
**Example:**
`http://localhost:8000/badge/reclaimed` will redirect to:
`https://img.shields.io/badge/clones-123-blue` (where 123 is the total clone count)
## Easy Deployment to App Engine
Deploy to Google Cloud App Engine in minutes. See the complete deployment guide: [gcloud_deploy.md](gcloud_deploy.md)
## Development
### Building from source
```bash
pip install build
python -m build
```
### Installing in development mode
```bash
pip install -e ".[dev]"
```
This installs the package in development mode with additional tools for linting, formatting, and testing.
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "git-clone-stats",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "analytics, clone-tracking, dashboard, github, statistics",
"author": null,
"author_email": "Taylor Wilsdon <taylor@example.com>",
"download_url": "https://files.pythonhosted.org/packages/37/de/8752188f37c0c31629346c9c91147433b0cc66b5112c023bea29fe55316f/git_clone_stats-1.0.3.tar.gz",
"platform": null,
"description": "# GitHub Repository Clone Statistics Tracker\n\nGit Stats is the missing piece of GitHub analytics - even if you pay, they will only give you 14 days of history. Bizarre gap for a company built on data... \n\nBut I digress. Git Stats is an agressively simple Python application for tracking and storing GitHub repository clone statistics. It has an extremely minimal HTML & JS frontend that requires no building, compiling or transpiling. \n\nThe tool fetches clone data from the GitHub API and maintains historical records in a SQLite database. It runs as an always on service and periodically fetches clone stats (total and unique) and displays them in an easy to use dashboard with shields.io badges available for use.\n\n\n<div align=\"center\">\n<video width=832 src=\"https://github.com/user-attachments/assets/ba4b670f-f0d3-4db6-9c18-e9480486ba84\"></video>\n</div>\n\n---\n\n## Features\n\n- **Complete GitHub Analytics**: Fetches repository clone statistics (total clones and unique cloners) and star counts from the GitHub API\n- **Historical Data Storage**: Maintains unlimited historical records in a SQLite database with robust querying capabilities\n- **Smart Data Management**: Avoids duplicate entries by only recording new data points\n- **Web Dashboard**: Modern, responsive UI with automatic background synchronization and dark/light theme support\n- **Interactive Visualizations**: Time-series charts with customizable date ranges and repository filtering\n- **Shields.io Badge Integration**: Generates embeddable badges for README files and documentation\n- **Cloud-Ready Deployment**: One-command deployment to Google App Engine with auto-scaling\n- **Repository Management**: Add/remove tracked repositories through the web interface\n- **Data Export/Import**: Backup and migration functionality for database portability\n- **Flexible Sync Intervals**: Configurable automatic synchronization (daily, weekly, biweekly)\n- **Modern CLI Interface**: Subcommands for sync and server operations with comprehensive help\n- **PyPI-Ready Packaging**: Modern Python tooling support with uv compatibility for fast installation\n\n### Quickstart with uv\n\nRun directly without installation:\n\n```bash\nuv run git-clone-stats sync\nuv run git-clone-stats server\n```\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install git-clone-stats\n```\n\n### With uv (fastest)\n\n```bash\nuv tool install git-clone-stats\n# or run directly without installing\nuv run git-clone-stats --help\n```\n\n### From source\n\n```bash\ngit clone https://github.com/taylorwilsdon/git-clone-stats.git\ncd git-clone-stats\npip install -e .\n```\n\n## Configuration\n\nSet up your GitHub Personal Access Token and Username. This requires a GitHub Personal Access Token with the `repo` scope to access repository traffic data.\n\n1. Create a token in your [GitHub Developer settings](https://github.com/settings/tokens)\n2. Set the required environment variables:\n\n```bash\nexport GITHUB_TOKEN='your_github_personal_access_token'\nexport GITHUB_USERNAME='your_github_username'\n```\n\n## Usage\n\n### Command Line Interface\n\nThe application provides a modern CLI with subcommands:\n\n```bash\ngit-clone-stats --help\n```\n\n#### Sync clone data\n\nTo fetch the latest clone statistics from GitHub and update the database:\n\n```bash\ngit-clone-stats sync\n```\n\n#### Start web server\n\nTo start the web dashboard server:\n\n```bash\ngit-clone-stats server --port 8000\n```\n\n### Retrieving Stored Data\n\nYou can query the `github_stats.db` SQLite database directly to retrieve historical data.\n\nHere are some example queries you can run from your terminal:\n\n**1. Open the database:**\n```bash\nsqlite3 github_stats.db\n```\n\n**2. View all records for a specific repository:**\n```sql\nSELECT * FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**3. Get the total clone count for a repository:**\n```sql\nSELECT SUM(count) FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**4. Get the total unique cloners for a repository:**\n```sql\nSELECT SUM(uniques) FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**5. View all data, ordered by repository and date:**\n```sql\nSELECT * FROM clone_history ORDER BY repo, timestamp;\n```\n\n## Web Server & User Interface\n\nThe application includes a web server that provides a user interface for viewing repository statistics, a JSON API, and automatic background synchronization.\n\n### Running the Server\n\nTo start the server:\n```bash\ngit-clone-stats server --port 8000\n```\n\nThe server will be available at `http://localhost:8000`.\n\n### Automatic Background Sync\n\nBy default, the server will automatically sync with GitHub every 24 hours. You can configure the sync interval by setting the `SYNC_INTERVAL` environment variable before running the server.\n\nSupported values are:\n- `daily` (default)\n- `weekly`\n- `biweekly`\n\n**Example:**\n```bash\nexport SYNC_INTERVAL='weekly'\ngit-clone-stats server\n```\n\n### User Interface\n\nNavigate to `http://localhost:8000` in your web browser to access the user interface. The dashboard provides two viewing modes:\n\n<div align=\"center\">\n<img width=\"70%\" height=\"70%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/f16b879d-f629-49a0-9fec-c17e827156b2\" />\n</div>\n\n#### Card View (Default)\nDisplays a card for each repository with:\n- The repository name and star count\n- Total clone and unique cloner counts\n- Collection date range (first/last sync)\n- A shields.io badge preview\n- A button to copy the badge's Markdown code\n\n#### Chart View\nInteractive time-series visualization showing:\n- **Line charts** for each repository displaying clone trends over time\n- **Dual metrics**: Both total clones (blue) and unique clones (green) on the same chart\n- **Time period filters**: View data for the last 7 days, 30 days, 3 months, or all time\n- **Repository filtering**: Focus on specific repositories or view all\n- **Responsive design**: Charts adapt to screen size and respect dark/light themes\n- **Interactive tooltips**: Hover over data points for detailed daily statistics\n\n<div align=\"center\">\n<img width=\"70%\" height=\"70%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4d6248ee-292b-41a6-b79d-179c53c8baf7\" />\n</div>\n\n#### Additional Features\n- **Dark/Light theme toggle** in the top-right corner\n- **Search and sorting** functionality for repositories (card view)\n- **Repository management** modal for adding/removing tracked repositories\n- **Data export/import** functionality for backup and migration\n- **\"Sync with GitHub\"** button that triggers a fresh data pull from the GitHub API\n\n### API Endpoints\n\n- **`GET /stats`**\n\n Returns a JSON array of all clone statistics from the database.\n\n **Example Response:**\n ```json\n [\n {\n \"repo\": \"google_workspace_mcp\",\n \"timestamp\": \"2024-07-05T00:00:00Z\",\n \"count\": 1,\n \"uniques\": 1\n },\n {\n \"repo\": \"google_workspace_mcp\",\n \"timestamp\": \"2024-07-06T00:00:00Z\",\n \"count\": 1,\n \"uniques\": 1\n }\n ]\n ```\n\n- **`GET /chart-data?days=<number>&repo=<repo-name>`**\n\n Returns time-series data formatted for chart visualization.\n\n **Query Parameters:**\n - `days` (optional): Number of days to include (7, 30, 90, or 0 for all time). Default: 30\n - `repo` (optional): Filter by specific repository name\n\n **Example:**\n `http://localhost:8000/chart-data?days=30&repo=my-repo`\n\n **Example Response:**\n ```json\n {\n \"chart_data\": {\n \"my-repo\": {\n \"labels\": [\"2024-07-01\", \"2024-07-02\", \"2024-07-03\"],\n \"clones\": [5, 3, 8],\n \"uniques\": [4, 2, 6]\n }\n },\n \"days_requested\": 30,\n \"repo_filter\": \"my-repo\"\n }\n ```\n\n- **`GET /badge/<repo-name>`**\n\n Returns a shields.io badge displaying the total clone count for the specified repository.\n\n **Example:**\n `http://localhost:8000/badge/reclaimed` will redirect to:\n `https://img.shields.io/badge/clones-123-blue` (where 123 is the total clone count)\n\n## Easy Deployment to App Engine\n\nDeploy to Google Cloud App Engine in minutes. See the complete deployment guide: [gcloud_deploy.md](gcloud_deploy.md)\n\n## Development\n\n### Building from source\n\n```bash\npip install build\npython -m build\n```\n\n### Installing in development mode\n\n```bash\npip install -e \".[dev]\"\n```\n\nThis installs the package in development mode with additional tools for linting, formatting, and testing.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "GitHub repository clone statistics tracker with web dashboard",
"version": "1.0.3",
"project_urls": {
"Documentation": "https://github.com/taylorwilsdon/git-clone-stats#readme",
"Homepage": "https://github.com/taylorwilsdon/git-clone-stats",
"Issues": "https://github.com/taylorwilsdon/git-clone-stats/issues",
"Repository": "https://github.com/taylorwilsdon/git-clone-stats"
},
"split_keywords": [
"analytics",
" clone-tracking",
" dashboard",
" github",
" statistics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0cedf81e6331adcda033f533a1bc611aa9551d3b53cd42f63326d9d0d0895e7c",
"md5": "3c779e30b8de54c7f1d25da0e5efdb3e",
"sha256": "0894427bea7b1fbf98dd829e205b8e44966a526ec48519d73d8ecbf2d5083b82"
},
"downloads": -1,
"filename": "git_clone_stats-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c779e30b8de54c7f1d25da0e5efdb3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 46762,
"upload_time": "2025-07-28T15:51:41",
"upload_time_iso_8601": "2025-07-28T15:51:41.502416Z",
"url": "https://files.pythonhosted.org/packages/0c/ed/f81e6331adcda033f533a1bc611aa9551d3b53cd42f63326d9d0d0895e7c/git_clone_stats-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "37de8752188f37c0c31629346c9c91147433b0cc66b5112c023bea29fe55316f",
"md5": "393dbdba03c50371059b42b80d7ae560",
"sha256": "b8ba84bee3cf8969a3edba4939f3a07d7f439130a25f971a513ca5196ca6b45f"
},
"downloads": -1,
"filename": "git_clone_stats-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "393dbdba03c50371059b42b80d7ae560",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29098,
"upload_time": "2025-07-28T15:51:42",
"upload_time_iso_8601": "2025-07-28T15:51:42.886023Z",
"url": "https://files.pythonhosted.org/packages/37/de/8752188f37c0c31629346c9c91147433b0cc66b5112c023bea29fe55316f/git_clone_stats-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 15:51:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taylorwilsdon",
"github_project": "git-clone-stats#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": []
}
],
"lcname": "git-clone-stats"
}
JSON
