# Git Py Stats
<div align="center">
[](https://github.com/tomice/git-py-stats/actions)
[](https://codecov.io/gh/tomice/git-py-stats)
[](https://docs.astral.sh/ruff/)
[](https://black.readthedocs.io/en/stable/)
[](LICENSE)
[](https://github.com/tomice/git-py-stats/issues)
[](https://github.com/tomice/git-py-stats/stargazers)
[](https://github.com/tomice/git-py-stats/graphs/contributors)
[](https://www.python.org/downloads/release/python-380/)
</div>
Git Py Stats is a Python-based fork inspired by [git-quick-stats](https://github.com/arzzen/git-quick-stats).
It offers a similar set of git statistics and reports, but it's built entirely
using Python 3, providing improved cross-platform compatibility
and ease of maintenance.
## Table of Contents
- [Why Git Py Stats?](#why-git-py-stats)
- [Features](#features)
- [Changes from Original](#changes-from-original)
- [Requirements](#requirements)
- [Installation](#installation)
- [Using PyPI](#using-pypi)
- [Using `setup.py`](#using-setuppy)
- [From Source](#from-source)
- [Usage](#usage)
- [Interactive Mode](#interactive-mode)
- [Non-Interactive Mode](#non-interactive-mode)
- [Advanced Usage](#advanced-usage)
- [Git Log Since and Until](#git-log-since-and-until)
- [Git Log Limit](#git-log-limit)
- [Git Log Options](#git-log-options)
- [Git Pathspec](#git-pathspec)
- [Git Merge View Strategy](#git-merge-view-strategy)
- [Git Branch](#git-branch)
- [Color Themes](#color-themes)
- [Contributing](#contributing)
- [Code of Conduct](#code-of-conduct)
- [License](#license)
- [Author](#author)
## Why Git Py Stats?
While `git-quick-stats` is a fantastic tool, it has some limitations due to its
reliance on Bash and external utilities:
- **Cross-Platform Compatibility**: `git-quick-stats` can have issues running
on different platforms. For example, macOS requires GNU versions of certain
utilities for proper functionality, and the Windows version either requires
WSL or Cygwin to run.
- **Dependency on External Tools**: Although it is written in Bash, it depends
heavily on external tools like `tput`, `column`, and `grep`, which may not be
installed depending on how the user's system is configured.
- **Robust File Generation**: `git-quick-stats` has the ability to export
stats in JSON and CSV format, but they are home-grown implementations that
are currently in experimental mode.
- **Difficult to Test and Extend**: Bash scripts are inherently harder to test
and extend compared to a Python-based solution that can leverage
[unittest](https://docs.python.org/3/library/unittest.html).
Git Py Stats tackles these challenges by leveraging Python's standard library,
guaranteeing that it incorporates code vetted by the Python team and operates
smoothly on any platform with Python 3 installed. It stays true to the essence
of `git-quick-stats` by ensuring that no dependencies beyond Python 3 and `git`
are ever required.
## Features
Git Py Stats aims to maintain feature parity with `git-quick-stats` with
features such as:
- Contribution stats by author
- Git changelogs and stats by branch or author
- Commits analysis by date, month, year, weekday, and hour
- Branch history and contributor analysis
- Suggested code reviewers based on commit history
- CSV and JSON output for various statistics
and more in both interactive and non-interactive modes.
### Changes from Original
While this project aims to be feature-complete and 1:1 with `git-quick-stats`,
there may be instances where this version differs from the base project.
The following is a list of differences that this project will maintain compared
to the parent project:
- Author, dates, and branch names can be passed via cmdline without interaction
by the user. This means you can now do `git-py-stats -L "John Doe"` instead
of being prompted to enter the name after executing the non-interactive cmd.
- CSV output is now saved to a file instead of printing out to the terminal.
This file will be saved to wherever the process was executed. The name will
be `git_daily_stats.csv`
- JSON output is saved to a file wherever the process was executed instead of
one that is provided by the user. The name will be `git_log.json`
- JSON and CSV formatting has changed slightly from the original.
- The New Contributors function shows the user's name next to the email in case
no known mailmap has been implemented for that user.
## Requirements
- **Python 3.8+**:
Git Py Stats requires Python 3.8 or higher installed on your system.
While it may work with older versions, there is no guarantee as it is
currently untested with versions below 3.8.
You can check your Python version with:
```bash
python --version
```
If your `python` is symlinked to Python 2, you can use
[`pyenv`](https://github.com/pyenv/pyenv) to switch between Python versions.
- **Git**:
Git should be installed and available in your system's `PATH`.
## Installation
### Using PyPI
1. **Install Using pip**:
```bash
pip install git-py-stats
```
That's it! You can now use `git-py-stats` anywhere on your system
while inside of a git repo!
If you experience conflicts with other packages,
try using [`venv`](https://docs.python.org/3/library/venv.html)
### Using `setup.py`
If you prefer using `setup.py` directly:
1. **Clone the Repository**:
```bash
git clone https://github.com/tomice/git-py-stats.git
cd git-py-stats
```
2. **Install the Package**:
```bash
python setup.py install
```
That's it! You can now use `git-py-stats` anywhere on your system
while inside of a git repo! If you don't have admin permissions,
you can use the `--user` flag at the end of the command to install
this locally.
### From Source
1. **Clone the Repository**:
```bash
git clone https://github.com/tomice/git-py-stats.git
cd git-py-stats
```
2. **Set PYTHONPATH**:
Set the root of `git-py-stats` to be prefixed to your `PYTHONPATH`:
```bash
export PYTHONPATH=$(pwd):$PYTHONPATH
```
That's it! You can now use `git-py-stats` anywhere on your system
while inside of a git repo, albeit with a slight modification.
Commands will need to be done in the following manner:
```bash
python -m git_py_stats.main --help
```
This will tell Python to run the `git_py_stats.main` module directly.
This method is usually best for devs who want to help contribute to the
project without going through the install process a normal end user would.
## Usage
You can run Git Py Stats in both interactive and non-interactive modes:
### Interactive Mode
Simply run the tool without any arguments to enter the interactive menu:
```bash
git-py-stats
```
### Non-Interactive Mode
Run the tool with specific command-line options for direct output. For example:
- **Detailed Git Stats**:
```bash
git-py-stats -T
```
- **Git Stats by Branch**:
```bash
git-py-stats -R master
```
- **List Contributors**:
```bash
git-py-stats -C
```
For a full list of available options, run:
```bash
git-py-stats --help
```
## Advanced Usage
It is possible for `git-py-stats` to read shell environment variables just like
`git-quick-stats` does. As it aims to maintain 1:1 compatibility, all of the
same arguments work the same as the parent project.
### Git Log Since and Until
You can set the variables `_GIT_SINCE` and/or `_GIT_UNTIL` before running
`git-py-stats` to limit the git log.
These work similar to git's built-in `--since` and `--until` log options.
```bash
export _GIT_SINCE="2017-01-20"
export _GIT_UNTIL="2017-01-22"
```
Once set, run `git-py-stats` as normal. Note that this affects all stats that
parse the git log history until unset.
### Git Log Limit
You can set variable `_GIT_LIMIT` for limited output.
It will affect the "changelogs" and "branch tree" options.
The default limit is `10`.
```bash
export _GIT_LIMIT=20
```
### Git Log Options
You can set `_GIT_LOG_OPTIONS` for
[git log options](https://git-scm.com/docs/git-log#_options):
```bash
export _GIT_LOG_OPTIONS="--ignore-all-space --ignore-blank-lines"
```
### Git Pathspec
You can exclude a directory from the stats by using
[pathspec](https://git-scm.com/docs/gitglossary#gitglossary-aiddefpathspecapathspec).
```bash
export _GIT_PATHSPEC=':!directory'
```
You can also exclude files from the stats.
Note that it works with any alphanumeric, glob, or regex that git respects.
```bash
export _GIT_PATHSPEC=':!package-lock.json'
```
### Git Merge View Strategy
You can set the variable `_GIT_MERGE_VIEW` to enable merge commits to be part
of the stats by setting `_GIT_MERGE_VIEW` to `enable`. You can also choose to
only show merge commits by setting `_GIT_MERGE_VIEW` to `exclusive`.
Default is to not show merge commits.
These work similar to git's built-in `--merges` and `--no-merges` log options.
```bash
export _GIT_MERGE_VIEW="enable"
export _GIT_MERGE_VIEW="exclusive"
```
### Git Branch
You can set the variable `_GIT_BRANCH` to set the branch of the stats.
Works with commands `--git-stats-by-branch` and `--csv-output-by-branch`.
```bash
export _GIT_BRANCH="master"
```
### Color Themes
You can change to the legacy color scheme by toggling the variable
`_MENU_THEME` between `default` and `legacy`
```bash
export _MENU_THEME="legacy"
```
## Contributing
We welcome contributions of all kinds! Please read our
[CONTRIBUTING.md](https://github.com/tomice/git-py-stats/blob/main/CONTRIBUTING.md)
guide to learn how to get involved.
## Code of Conduct
To ensure a positive and inclusive community, please follow our
[Code of Conduct](https://github.com/tomice/git-py-stats/blob/main/CODE_OF_CONDUCT.md)
during your interactions.
## License
This project is licensed under the MIT License.
See the [LICENSE](https://github.com/tomice/git-py-stats/blob/main/LICENSE)
file for more details.
## Author
Tom Ice
Raw data
{
"_id": null,
"home_page": "https://github.com/tomice/git-py-stats",
"name": "git-py-stats",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git stats statistics command-line",
"author": "Tom Ice",
"author_email": "contact@thomasice.com",
"download_url": "https://files.pythonhosted.org/packages/7a/e7/e54eaad5daa7937e600838a1b56367523f383b8526cded009ba5d92f4a50/git-py-stats-0.1.0.tar.gz",
"platform": null,
"description": "# Git Py Stats\n\n<div align=\"center\">\n\n[](https://github.com/tomice/git-py-stats/actions)\n[](https://codecov.io/gh/tomice/git-py-stats)\n[](https://docs.astral.sh/ruff/)\n[](https://black.readthedocs.io/en/stable/)\n[](LICENSE)\n[](https://github.com/tomice/git-py-stats/issues)\n[](https://github.com/tomice/git-py-stats/stargazers)\n[](https://github.com/tomice/git-py-stats/graphs/contributors)\n[](https://www.python.org/downloads/release/python-380/)\n\n</div>\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\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 - [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.\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\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 commands `--git-stats-by-branch` and `--csv-output-by-branch`.\n\n```bash\nexport _GIT_BRANCH=\"master\"\n```\n\n### Color Themes\n\nYou can change to the legacy color scheme by toggling the variable\n`_MENU_THEME` between `default` and `legacy`\n\n```bash\nexport _MENU_THEME=\"legacy\"\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.\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\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python Implementation of git-quick-stats",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/tomice/git-py-stats"
},
"split_keywords": [
"git",
"stats",
"statistics",
"command-line"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76bfbc7b29bbe918630f6404cde8347b81ecfc0a919b78c9b1b38314c48cd48b",
"md5": "0ed3325c3ea5bade294561db98635f6e",
"sha256": "e0102195d209050c54b24e00c84eea316883e7a87297e629b5e2595c60c2aaae"
},
"downloads": -1,
"filename": "git_py_stats-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ed3325c3ea5bade294561db98635f6e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41165,
"upload_time": "2024-09-29T03:15:28",
"upload_time_iso_8601": "2024-09-29T03:15:28.700461Z",
"url": "https://files.pythonhosted.org/packages/76/bf/bc7b29bbe918630f6404cde8347b81ecfc0a919b78c9b1b38314c48cd48b/git_py_stats-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7ae7e54eaad5daa7937e600838a1b56367523f383b8526cded009ba5d92f4a50",
"md5": "9a36459420abfcb42867325dc87948c8",
"sha256": "d4079a0a75b6386a7d8429b309c39faa464536dbfd4dd927e9cb65409c1a2d7f"
},
"downloads": -1,
"filename": "git-py-stats-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9a36459420abfcb42867325dc87948c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29138,
"upload_time": "2024-09-29T03:15:30",
"upload_time_iso_8601": "2024-09-29T03:15:30.163455Z",
"url": "https://files.pythonhosted.org/packages/7a/e7/e54eaad5daa7937e600838a1b56367523f383b8526cded009ba5d92f4a50/git-py-stats-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-29 03:15:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tomice",
"github_project": "git-py-stats",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "git-py-stats"
}
JSON
