{"id":30047351,"url":"https://github.com/taylorwilsdon/git-clone-stats","last_synced_at":"2025-08-07T09:39:41.464Z","repository":{"id":306786863,"uuid":"1027211482","full_name":"taylorwilsdon/git-clone-stats","owner":"taylorwilsdon","description":"Self-hosted Github Repo Analytics Platform - Track Git Clones, Stars \u0026 More over time! ","archived":false,"fork":false,"pushed_at":"2025-08-03T17:50:43.000Z","size":125,"stargazers_count":13,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-03T18:17:56.977Z","etag":null,"topics":["analytics","badges","clones-badge","dashboard","developer-tools","github","github-api","scraper","shields-io","statistics"],"latest_commit_sha":null,"homepage":"https://git-stats.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taylorwilsdon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T14:52:14.000Z","updated_at":"2025-08-03T17:24:28.000Z","dependencies_parsed_at":"2025-07-27T17:24:47.028Z","dependency_job_id":"18779b5c-fdf5-4b3c-9cfe-9afca25845a5","html_url":"https://github.com/taylorwilsdon/git-clone-stats","commit_stats":null,"previous_names":["taylorwilsdon/git-clone-stats"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/taylorwilsdon/git-clone-stats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwilsdon%2Fgit-clone-stats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwilsdon%2Fgit-clone-stats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwilsdon%2Fgit-clone-stats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwilsdon%2Fgit-clone-stats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taylorwilsdon","download_url":"https://codeload.github.com/taylorwilsdon/git-clone-stats/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylorwilsdon%2Fgit-clone-stats/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269235782,"owners_count":24383225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","badges","clones-badge","dashboard","developer-tools","github","github-api","scraper","shields-io","statistics"],"created_at":"2025-08-07T09:39:38.805Z","updated_at":"2025-08-07T09:39:41.456Z","avatar_url":"https://github.com/taylorwilsdon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# git-stats - GitHub Repo Clone Stats \u0026 Analytics \u003cimg src=\"https://github.com/user-attachments/assets/dd25bc31-87e2-43ea-88de-e3de2222d066\" width=\"80\" align=\"right\" /\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/git-clone-stats)](https://pypi.org/project/git-clone-stats/)\n[![Python versions](https://img.shields.io/pypi/pyversions/git-clone-stats)](https://pypi.org/project/git-clone-stats/)\n[![License](https://img.shields.io/github/license/taylorwilsdon/git-clone-stats)](LICENSE)\n\n\u003c/div\u003e\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. This repo is an agressively simple Python application for tracking and storing GitHub repository clone statistics. It has an extremely minimal HTML \u0026 JS frontend that requires no building, compiling or transpiling. \n\nThe tool fetches clone data and view/traffic statistics from the GitHub API and maintains historical records in a SQLite or Firestore database. It runs as an always on service and periodically fetches clone stats (total and unique) plus view data and displays them in an easy to use dashboard with shields.io badges available for use.\n\n\n\u003cdiv align=\"center\"\u003e\n\u003cvideo width=832 src=\"https://github.com/user-attachments/assets/c8704ac1-fd99-4bb7-8763-421eebc7c487\"\u003e\u003c/video\u003e\n\u003c/div\u003e\n\n---\n\n## Features\n\n- **Complete GitHub Analytics**: Fetches repository clone statistics, view/traffic data (total views and unique viewers), and star counts from the GitHub API\n- **Historical Data Storage**: Maintains unlimited historical records in SQLite (local) or Firestore (cloud) databases 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 and Firestore database support\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### Docker (recommended for production)\n\nRun git-stats in a production-ready Docker container:\n\n```bash\n# Using Docker Compose (easiest)\ndocker-compose up -d\n\n# Or build and run manually\ndocker build -t git-stats .\ndocker run -d \\\n  -p 8080:8080 \\\n  -e GITHUB_TOKEN=your_token \\\n  -e GITHUB_USERNAME=your_username \\\n  -e GITHUB_ORG=your_organization \\\n  -v $(pwd)/data:/app/data \\\n  git-stats\n```\n\nThe Docker image includes:\n- Multi-stage build for minimal size (~150MB)\n- Non-root user execution for security\n- Health checks for container orchestration\n- Automatic restart on failure\n- Volume mounting for persistent SQLite storage\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'\nexport GITHUB_ORG='your_organization_name'  # Optional: for tracking organization repositories\n```\n\n### Organization Repository Support\n\nGit-Stats provides intelligent support for tracking repositories from both personal accounts and organizations with individual control over each repository's owner type:\n\n#### Features:\n- **Smart Repository Resolution**: Automatically determines the correct GitHub API path based on repository owner type\n- **Mixed Repository Support**: Track both personal and organization repositories simultaneously  \n- **Intelligent UI**: Owner type selection appears automatically when `GITHUB_ORG` is configured\n- **Flexible Repository Specification**: Support for explicit `owner/repo` format\n\n#### Configuration Options:\n\n1. **Personal repositories only** (default)\n   - Set only `GITHUB_USERNAME`\n   - All repositories use personal account\n\n2. **Organization repositories with choice**\n   - Set both `GITHUB_USERNAME` and `GITHUB_ORG`\n   - Web UI shows owner type selection for each repository\n   - Choose \"Personal\" or \"Organization\" when adding repositories\n\n3. **Explicit path format**\n   - Add repositories as `owner/repo` (e.g., `myorg/project` or `someuser/repo`)\n   - Bypasses automatic owner resolution\n\n#### Examples:\n\n**Personal only:**\n```bash\nGITHUB_USERNAME=johndoe\n# Add \"myproject\" → uses johndoe/myproject\n```\n\n**Mixed personal and organization:**\n```bash\nGITHUB_USERNAME=johndoe\nGITHUB_ORG=mycompany\n# Add \"myproject\" as Personal → uses johndoe/myproject\n# Add \"web-app\" as Organization → uses mycompany/web-app\n```\n\n**Explicit paths:**\n```bash\n# Add \"otherorg/special-project\" → uses otherorg/special-project\n# Add \"contributor/fork\" → uses contributor/fork\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 clone records for a specific repository:**\n```sql\nSELECT * FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**3. View all view/traffic records for a specific repository:**\n```sql\nSELECT * FROM view_history WHERE repo = 'reclaimed';\n```\n\n**4. Get the total clone count for a repository:**\n```sql\nSELECT SUM(count) FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**5. Get the total unique cloners for a repository:**\n```sql\nSELECT SUM(uniques) FROM clone_history WHERE repo = 'reclaimed';\n```\n\n**6. View all data, ordered by repository and date:**\n```sql\nSELECT * FROM clone_history ORDER BY repo, timestamp;\nSELECT * FROM view_history ORDER BY repo, timestamp;\n```\n\n## Web Server \u0026 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\u003cdiv align=\"center\"\u003e\n\u003cimg width=\"70%\" height=\"70%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/f16b879d-f629-49a0-9fec-c17e827156b2\" /\u003e\n\u003c/div\u003e\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\u003cdiv align=\"center\"\u003e\n\u003cimg width=\"70%\" height=\"70%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4d6248ee-292b-41a6-b79d-179c53c8baf7\"  /\u003e\n\u003c/div\u003e\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 /api/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 /api/chart-data?days=\u003cnumber\u003e\u0026repo=\u003crepo-name\u003e`**\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/api/chart-data?days=30\u0026repo=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 /api/badge/\u003crepo-name\u003e`**\n\n  Returns a shields.io-style SVG badge displaying the total clone count for the specified repository.\n\n  **Example:**\n  `http://localhost:8000/api/badge/reclaimed` returns an SVG badge showing the clone count\n\n## Deployment Options\n\n### Docker Deployment\n\nFor production deployments, Docker provides the most flexible and portable solution:\n\n```bash\n# Quick start with docker-compose\ndocker-compose up -d\n\n# Access the dashboard at http://localhost:8080\n```\n\nConfigure environment variables in a `.env` file:\n```bash\nGITHUB_TOKEN=your_github_token\nGITHUB_USERNAME=your_username\nGITHUB_ORG=your_organization_name  # Optional: for organization repositories\nUSE_FIRESTORE=false\nPORT=8080\n```\n\n### Google Cloud 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylorwilsdon%2Fgit-clone-stats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaylorwilsdon%2Fgit-clone-stats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylorwilsdon%2Fgit-clone-stats/lists"}