Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/git-quick-stats/git-py-stats
🐍📊 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.
https://github.com/git-quick-stats/git-py-stats
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
Last synced: 19 days ago
JSON representation
🐍📊 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.
- Host: GitHub
- URL: https://github.com/git-quick-stats/git-py-stats
- Owner: git-quick-stats
- License: mit
- Created: 2024-09-22T00:19:11.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-09-29T03:29:41.000Z (3 months ago)
- Last Synced: 2024-11-09T02:09:37.212Z (about 2 months ago)
- 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
- Language: Python
- Homepage:
- Size: 204 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Git Py Stats
[](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/)
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