{"id":17463853,"url":"https://github.com/git-quick-stats/git-py-stats","last_synced_at":"2025-11-03T17:31:20.463Z","repository":{"id":257804223,"uuid":"861080808","full_name":"git-quick-stats/git-py-stats","owner":"git-quick-stats","description":"🐍📊 Git Py Stats is a Python-powered version of Git Quick Stats that provides a streamlined and cross-platform way to access various statistics in your git repository.","archived":false,"fork":false,"pushed_at":"2024-09-29T03:29:41.000Z","size":209,"stargazers_count":10,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T23:34:58.579Z","etag":null,"topics":["cli-tool","command-line-tool","cross-platform","developer-tools","git","git-analysis","git-metrics","git-statistics","no-dependencies","open-source","python","python3","statistics","version-control"],"latest_commit_sha":null,"homepage":"","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/git-quick-stats.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2024-09-22T00:19:11.000Z","updated_at":"2025-02-15T00:29:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"e1a13895-c3f4-467e-b5a0-c3a820291380","html_url":"https://github.com/git-quick-stats/git-py-stats","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":0.1333333333333333,"last_synced_commit":"0bf3845230573ea6e632f089a18b1b810f34ab5f"},"previous_names":["tomice/git-py-stats","git-quick-stats/git-py-stats"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-quick-stats%2Fgit-py-stats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-quick-stats%2Fgit-py-stats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-quick-stats%2Fgit-py-stats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-quick-stats%2Fgit-py-stats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-quick-stats","download_url":"https://codeload.github.com/git-quick-stats/git-py-stats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119248,"owners_count":21050751,"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","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":["cli-tool","command-line-tool","cross-platform","developer-tools","git","git-analysis","git-metrics","git-statistics","no-dependencies","open-source","python","python3","statistics","version-control"],"created_at":"2024-10-18T10:43:25.962Z","updated_at":"2025-11-03T17:31:20.457Z","avatar_url":"https://github.com/git-quick-stats.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git Py Stats\n\n\u003cdiv align=\"center\"\u003e\n  \n[![CI](https://github.com/tomice/git-py-stats/workflows/CI/badge.svg)](https://github.com/tomice/git-py-stats/actions)\n[![codecov](https://codecov.io/gh/tomice/git-py-stats/branch/main/graph/badge.svg)](https://codecov.io/gh/tomice/git-py-stats)\n[![Ruff](https://img.shields.io/badge/linting-Ruff-green?logo=ruff)](https://docs.astral.sh/ruff/)\n[![Black](https://img.shields.io/badge/code%20style-Black-000000.svg?logo=black)](https://black.readthedocs.io/en/stable/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![GitHub issues](https://img.shields.io/github/issues/tomice/git-py-stats)](https://github.com/tomice/git-py-stats/issues)\n[![GitHub stars](https://img.shields.io/github/stars/tomice/git-py-stats?style=social)](https://github.com/tomice/git-py-stats/stargazers)\n[![Contributors](https://img.shields.io/github/contributors/tomice/git-py-stats)](https://github.com/tomice/git-py-stats/graphs/contributors)\n[![Python Versions](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)\n\n\u003c/div\u003e\n\nGit Py Stats is a Python-based fork inspired by [git-quick-stats](https://github.com/arzzen/git-quick-stats).\nIt offers a similar set of git statistics and reports, but it's built entirely\nusing Python 3, providing improved cross-platform compatibility\nand ease of maintenance.\n\n![mainMenuScreenshot](https://github.com/user-attachments/assets/db99d110-c43b-4ba7-baa9-b7d0167475cf)\n\n## Table of Contents\n\n- [Why Git Py Stats?](#why-git-py-stats)\n- [Features](#features)\n  - [Changes from Original](#changes-from-original)\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Using PyPI](#using-pypi)\n  - [Using `setup.py`](#using-setuppy)\n  - [From Source](#from-source)\n- [Usage](#usage)\n  - [Interactive Mode](#interactive-mode)\n  - [Non-Interactive Mode](#non-interactive-mode)\n- [Advanced Usage](#advanced-usage)\n  - [Git Log Since and Until](#git-log-since-and-until)\n  - [Git Log Limit](#git-log-limit)\n  - [Git Log Options](#git-log-options)\n  - [Git Pathspec](#git-pathspec)\n  - [Git Merge View Strategy](#git-merge-view-strategy)\n  - [Git Branch](#git-branch)\n  - [Sorting Contribution Stats](#sorting-contribution-stats)\n  - [Commit Days](#commit-days)\n  - [Color Themes](#color-themes)\n- [Contributing](#contributing)\n- [Code of Conduct](#code-of-conduct)\n- [License](#license)\n- [Author](#author)\n\n## Why Git Py Stats?\n\nWhile `git-quick-stats` is a fantastic tool, it has some limitations due to its\nreliance on Bash and external utilities:\n\n- **Cross-Platform Compatibility**: `git-quick-stats` can have issues running\n  on different platforms. For example, macOS requires GNU versions of certain\n  utilities for proper functionality, and the Windows version either requires\n  WSL or Cygwin to run.\n- **Dependency on External Tools**: Although it is written in Bash, it depends\n  heavily on external tools like `tput`, `column`, and `grep`, which may not be\n  installed depending on how the user's system is configured, especially if you\n  happen to be running this on a minimal Linux distro targeted for embedded\n  devices with a sparse dev environment.\n- **Robust File Generation**: `git-quick-stats` has the ability to export\n  stats in JSON and CSV format, but they are home-grown implementations that\n  are currently in experimental mode.\n- **Difficult to Test and Extend**: Bash scripts are inherently harder to test\n  and extend compared to a Python-based solution that can leverage\n  [unittest](https://docs.python.org/3/library/unittest.html).\n\nGit Py Stats tackles these challenges by leveraging Python's standard library,\nguaranteeing that it incorporates code vetted by the Python team and operates\nsmoothly on any platform with Python 3 installed. It stays true to the essence\nof `git-quick-stats` by ensuring that no dependencies beyond Python 3 and `git`\nare ever required.\n\n## Features\n\nGit Py Stats aims to maintain feature parity with `git-quick-stats` with\nfeatures such as:\n\n- Contribution stats by author\n- Git changelogs and stats by branch or author\n- Commits analysis by date, month, year, weekday, and hour\n- Branch history and contributor analysis\n- Suggested code reviewers based on commit history\n- CSV and JSON output for various statistics\n\nand more in both interactive and non-interactive modes.\n\n### Changes from Original\n\nWhile this project aims to be feature-complete and 1:1 with `git-quick-stats`,\nthere may be instances where this version differs from the base project.\nThe following is a list of differences that this project will maintain compared\nto the parent project:\n\n- Author, dates, and branch names can be passed via cmdline without interaction\n  by the user. This means you can now do `git-py-stats -L \"John Doe\"` instead\n  of being prompted to enter the name after executing the non-interactive cmd.\n- CSV output is now saved to a file instead of printing out to the terminal.\n  This file will be saved to wherever the process was executed. The name will\n  be `git_daily_stats.csv`\n- JSON output is saved to a file wherever the process was executed instead of\n  one that is provided by the user. The name will be `git_log.json`\n- JSON and CSV formatting has changed slightly from the original.\n- The New Contributors function shows the user's name next to the email in case\n  no known mailmap has been implemented for that user.\n\n## Requirements\n\n- **Python 3.8+**:\n  Git Py Stats requires Python 3.8 or higher installed on your system.\n  While it may work with older versions, there is no guarantee as it is\n  currently untested with versions below 3.8.\n  You can check your Python version with:\n\n    ```bash\n    python --version\n    ```\n\n  If your `python` is symlinked to Python 2, you can use\n  [`pyenv`](https://github.com/pyenv/pyenv) to switch between Python versions.\n  Alternatively, as long as Python 3 is installed, you should be able to replace\n  any of the `python` commands with `python3`.\n\n- **Git**:\n  Git should be installed and available in your system's `PATH`.\n\n## Installation\n\n### Using PyPI\n\n1. **Install Using pip**:\n\n    ```bash\n    pip install git-py-stats\n    ```\n\n    That's it! You can now use `git-py-stats` anywhere on your system\n    while inside of a git repo!\n\n    If you experience conflicts with other packages,\n    try using [`venv`](https://docs.python.org/3/library/venv.html)\n\n### Using `setup.py`\n\nIf you prefer using `setup.py` directly:\n\n1. **Clone the Repository**:\n\n    ```bash\n    git clone https://github.com/tomice/git-py-stats.git\n    cd git-py-stats\n    ```\n\n2. **Install the Package**:\n\n    ```bash\n    python setup.py install\n    ```\n\n    That's it! You can now use `git-py-stats` anywhere on your system\n    while inside of a git repo! If you don't have admin permissions,\n    you can use the `--user` flag at the end of the command to install\n    this locally.\n\n### From Source\n\n1. **Clone the Repository**:\n\n    ```bash\n    git clone https://github.com/tomice/git-py-stats.git\n    cd git-py-stats\n    ```\n\n2. **Set PYTHONPATH**:\n\n    Set the root of `git-py-stats` to be prefixed to your `PYTHONPATH`:\n\n    ```bash\n    export PYTHONPATH=$(pwd):$PYTHONPATH\n    ```\n\n    That's it! You can now use `git-py-stats` anywhere on your system\n    while inside of a git repo, albeit with a slight modification.\n    Commands will need to be done in the following manner:\n\n    ```bash\n    python -m git_py_stats.main --help\n    ```\n\n    This will tell Python to run the `git_py_stats.main` module directly.\n    This method is usually best for devs who want to help contribute to the\n    project without going through the install process a normal end user would.\n\n## Usage\n\nYou can run Git Py Stats in both interactive and non-interactive modes:\n\n### Interactive Mode\n\nSimply run the tool without any arguments to enter the interactive menu:\n\n```bash\ngit-py-stats\n```\n\n### Non-Interactive Mode\n\nRun the tool with specific command-line options for direct output. For example:\n\n- **Detailed Git Stats**:\n\n    ```bash\n    git-py-stats -T\n    ```\n\n- **Git Stats by Branch**:\n\n    ```bash\n    git-py-stats -R master\n    ```\n\n- **List Contributors**:\n\n    ```bash\n    git-py-stats -C\n    ```\n\nFor a full list of available options, run:\n\n```bash\ngit-py-stats --help\n```\n\n## Advanced Usage\n\nIt is possible for `git-py-stats` to read shell environment variables just like\n`git-quick-stats` does. As it aims to maintain 1:1 compatibility, all of the\nsame arguments work the same as the parent project.\n\n### Git Log Since and Until\n\nYou can set the variables `_GIT_SINCE` and/or `_GIT_UNTIL` before running\n`git-py-stats` to limit the git log.\nThese work similar to git's built-in `--since` and `--until` log options.\n\n```bash\nexport _GIT_SINCE=\"2017-01-20\"\nexport _GIT_UNTIL=\"2017-01-22\"\n```\n\nOnce set, run `git-py-stats` as normal. Note that this affects all stats that\nparse the git log history until unset.\n\n### Git Log Limit\n\nYou can set variable `_GIT_LIMIT` for limited output.\nIt will affect the \"changelogs\" and \"branch tree\" options.\nThe default limit is `10`.\n\n```bash\nexport _GIT_LIMIT=20\n```\n\n### Git Log Options\n\nYou can set `_GIT_LOG_OPTIONS` for\n[git log options](https://git-scm.com/docs/git-log#_options):\n\n```bash\nexport _GIT_LOG_OPTIONS=\"--ignore-all-space --ignore-blank-lines\"\n```\n\n### Git Pathspec\n\nYou can exclude a directory from the stats by using\n[pathspec](https://git-scm.com/docs/gitglossary#gitglossary-aiddefpathspecapathspec).\n\n```bash\nexport _GIT_PATHSPEC=':!directory'\n```\n\nYou can also exclude files from the stats.\nNote that it works with any alphanumeric, glob, or regex that git respects.\n\n```bash\nexport _GIT_PATHSPEC=':!package-lock.json'\n```\n\n### Git Merge View Strategy\n\nYou can set the variable `_GIT_MERGE_VIEW` to enable merge commits to be part\nof the stats by setting `_GIT_MERGE_VIEW` to `enable`. You can also choose to\nonly show merge commits by setting `_GIT_MERGE_VIEW` to `exclusive`.\nDefault is to not show merge commits.\nThese work similar to git's built-in `--merges` and `--no-merges` log options.\n\n```bash\nexport _GIT_MERGE_VIEW=\"enable\"\nexport _GIT_MERGE_VIEW=\"exclusive\"\n```\n\n### Git Branch\n\nYou can set the variable `_GIT_BRANCH` to set the branch of the stats.\nWorks with command `--csv-output-by-branch` only currently.\n\n```bash\nexport _GIT_BRANCH=\"master\"\n```\n\n### Ignore Authors\n\nYou can set the variable `_GIT_IGNORE_AUTHORS` to filter out specific\nauthors. It will currently work with the \"Code reviewers\", \"New contributors\",\n\"All branches\", and \"Output daily stats by branch in CSV format\" options.\n\n```bash\nexport _GIT_IGNORE_AUTHORS=\"(author@examle.com|username)\"\n```\n\n### Sorting Contribution Stats\n\nYou can sort contribution stats by field `name`, `commits`, `insertions`,\n`deletions`, or `lines` (total lines changed), followed by a hyphen and\na direction (`asc`, `desc`).\n\n```bash\nexport _GIT_SORT_BY=\"name-asc\"\nor\nexport _GIT_SORT_BY=\"lines-desc\"\nor\nexport _GIT_SORT_BY=\"deletions-asc\"\n```\n\n### Commit Days\n\nYou can set the variable `_GIT_DAYS` to set the number of days for the heatmap.\n\n```bash\nexport _GIT_DAYS=30\n```\n\n### Color Themes\n\nYou can change to the legacy color scheme by toggling the variable `_MENU_THEME`\nbetween `default` and `legacy`. You can completely disable the color theme by\nsetting the `_MENU_THEME` variable to `none`.\n\n```bash\nexport _MENU_THEME=\"legacy\"\n# or\nexport _MENU_THEME=\"none\"\n```\n\n## Contributing\n\nWe welcome contributions of all kinds! Please read our\n[CONTRIBUTING.md](https://github.com/tomice/git-py-stats/blob/main/CONTRIBUTING.md)\nguide to learn how to get involved. It contains more detailed information to\nhelp walk you through how to contribute. If there are any questions, feel free\nto ask when submitting your issue or PR, and one of the maintainers will help!\n\nTo sum it up, please do the following:\n\n1. Create an [issue](https://github.com/git-quick-stats/git-py-stats/issues/new) on GitHub.\n2. Clone the [repo](https://github.com/git-quick-stats/git-py-stats) and make your changes.\n3. Write the accompanying [tests](https://docs.python.org/3/library/unittest.html).\n4. Auto lint with [`ruff`](https://github.com/astral-sh/ruff).\n5. Auto format with [`black`](https://github.com/psf/black).\n6. Submit the [PR](https://github.com/git-quick-stats/git-py-stats/compare).\n\n## Code of Conduct\n\nTo ensure a positive and inclusive community, please follow our\n[Code of Conduct](https://github.com/tomice/git-py-stats/blob/main/CODE_OF_CONDUCT.md)\nduring your interactions.\n\n## License\n\nThis project is licensed under the MIT License.\nSee the [LICENSE](https://github.com/tomice/git-py-stats/blob/main/LICENSE)\nfile for more details.\n\n## Author\n\nTom Ice\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-quick-stats%2Fgit-py-stats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-quick-stats%2Fgit-py-stats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-quick-stats%2Fgit-py-stats/lists"}