# git-quick-stats: git repository statistics without memorising git log flags

> git-quick-stats is a shell script that turns git log output into contributor lists, commit heatmaps, changelogs and reviewer suggestions. It suits small teams who want stats on a laptop or in CI, and it is the wrong tool if you need a hosted dashboard.

**git-quick-stats/git-quick-stats** — ▁▅▆▃▅ Git quick statistics is a simple and efficient way to access various statistics in git repository.

- Repository: https://github.com/git-quick-stats/git-quick-stats
- Website: https://git-quick-stats.sh
- Stars: 7,007 · Forks: 280
- Language: Shell
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/git-quick-stats-git-quick-stats

## What git-quick-stats answers that plain git log does not

The README opens with the problem in its own words: a repository holds "tons of information about commits, contributors, and files", and extracting it is not trivial "mostly because there are a gadzillion options to a gadzillion git commands". That is the gap this project fills. Instead of composing a long git log pipeline with --since, --until, --author and format strings, you pick a named report.

The audience is anyone who periodically needs history facts: a maintainer preparing release notes, a team lead checking who has been committing on which weekday, a reviewer trying to work out who knows a subsystem. The tool is a single shell script, so it runs wherever git and bash run, including inside a container. It is not a service, it stores nothing, and it has no database. Every number it prints is derived from the local clone at the moment you run it.

## The mechanism: git log parsing behind a menu and a flag set

The repository is small and readable. Top-level entries include the script itself, git-quick-stats, its man page git-quick-stats.1, a Makefile, a Dockerfile, a tests directory and a .mailmap. There is no compiled component and no runtime dependency beyond git and standard Unix tools.

Two entry points exist. Running the script with no argument opens an interactive menu; running it with a flag executes that report directly. The flags are grouped in the help text as GENERATE OPTIONS, LIST OPTIONS, CALENDAR OPTIONS and SUGGEST OPTIONS. Long and short forms are both accepted, so --commits-by-hour and -o are the same report.

Configuration is done through environment variables rather than a config file. _GIT_SINCE and _GIT_UNTIL bound the log, mirroring git's own --since and --until. _GIT_LIMIT caps output for the changelogs and branch tree options, and the README states the default is 10. _GIT_TAG sets the tag used by the new-contributors-since-tag report. _GIT_LOG_OPTIONS passes extra git log options through, and _GIT_PATHSPEC excludes paths using git pathspec syntax, for example a lockfile. _GIT_MERGE_VIEW controls merge commits: enable includes them, exclusive shows only them. The Dockerfile declares these same variables in an ENV block, which tells you the container path respects them too.

## Installing git-quick-stats and running a first report

The README documents four installation routes: UNIX and Linux, macOS via Homebrew, Windows, and Docker. On a machine with make, the Makefile installs the script into a bin directory and the man page into the man tree. PREFIX defaults to /usr/local, so the command below places the script at /usr/local/bin/git-quick-stats.

```bash
make install
```

After that, git quick-stats works as a git subcommand. The README shows both spellings: the first opens the interactive menu, the second runs a single report and exits.

```bash
git-quick-stats
git quick-stats --commits-per-author
```

The Makefile also defines make uninstall, which removes both the script and git-quick-stats.1, and make reinstall, which curls the script and man page from the master branch of the GitHub repository before installing. There is also a make test target that runs tests/commands_test.sh.

For a container, the Dockerfile builds from alpine, installs bash, git, make, ncurses, coreutils and util-linux, runs make install, then removes make. It sets the working directory to /git, marks that path as a safe directory, and uses an entrypoint that forwards any argument starting with a hyphen to git quick-stats.

A useful first real use is scoping a report to a release window. The README gives this example, and warns that it affects all stats that parse the git log history until you unset the variables:

```bash
export _GIT_SINCE="2017-01-20"
export _GIT_UNTIL="2017-01-22"
git quick-stats --changelogs
```

A later report in the same shell session inherits that window, so unset both variables when you want the full history again.

## Where git-quick-stats gets in the way

The tool is a shell script, and that shapes its limits. It requires bash specifically: the Makefile sets SHELL to the result of which bash, and the Dockerfile installs bash explicitly on an Alpine base that does not ship it by default. On a system where /bin/sh is dash or busybox ash, running the script directly is not the supported path.

Environment variables are global to the shell session. The README is explicit that _GIT_SINCE and _GIT_UNTIL affect every stat that parses the log until you unset them. There is no per-invocation flag for the window, so scripting several different periods in one shell means exporting and unsetting between calls, or running each in a subshell.

Output formats are uneven. The flag list shows CSV output for daily stats by branch (--csv-output-by-branch) and JSON output that the README describes as saving the git log as a JSON formatted file to a specified area. The other reports are terminal-oriented, with colour themes and a menu. If you need a documented JSON schema for commits-per-author or timezone breakdowns, the README does not offer one, and you would be parsing human-facing text.

Scale is the other boundary. Every report walks the local git log. On a very large monorepo with a long history, the pathspec variable is the documented mitigation, and it is worth using it to drop vendored directories or lockfiles before you run a report that would otherwise scan everything.

## How it differs from git shortlog and git fame

git shortlog, which ships with git, already summarises commits per author, and git log --format can produce most of the raw material. The difference is packaging. git-quick-stats adds the questions shortlog does not answer in one step: commits by hour, by weekday, by timezone, by author within each of those, a calendar heatmap per author, an ASCII branch tree, changelogs by author, and a reviewer suggestion report.

git-fame is the closer comparison, because it targets the same question of who wrote what. git-fame counts lines of code per author by walking blame or history; git-quick-stats counts commits and commit metadata. Those are different measurements and they can disagree sharply, since one large generated file can dominate a line count while contributing a single commit. If your question is about code ownership by volume, a line-counting tool answers it; if it is about activity patterns over time, this one does.

Hosted dashboards are the other alternative, and they solve a problem this project does not attempt: aggregation across many repositories, retention over time, and a URL you can share with people who do not have a clone. git-quick-stats is local and stateless by design. That is a feature when you want a quick answer without sending history anywhere, and a limitation when you want a trend line that survives the next clone.

## Maintenance, licensing and the cost of keeping it current

The project is not archived. Its last push was on 2026-04-18, and release 2.11.0 carries the same timestamp. Releases 2.10.0 and 2.9.0 arrived earlier in April 2026, so the recent cadence has been a few releases close together rather than a steady drip.

Upgrading is cheap in the sense that there is nothing to compile and no data migration: the artifact is the script and the man page. The Makefile's reinstall target downloads both from the master branch, which means it tracks the branch rather than a tagged release. If you want the version pinned, install from a specific release instead of running make reinstall. For containers, the Dockerfile builds from alpine with no version pin on the base image, so a rebuild can pick up a newer Alpine.

The licence is MIT, stated in the repository and in the README's licensing section. MIT is permissive and places few obligations on how you redistribute or embed the script, but the usual caveat applies: this is a description of the licence text, not legal advice for your situation.

## Conclusion

Adopt git-quick-stats if you want repository history answers from a terminal, on a machine where bash, git and the listed core utilities already exist. Skip it if you need a hosted dashboard, cross-repository aggregation, or a stable machine-readable schema for every report. Before relying on it, verify that your shell is bash rather than a minimal sh, check the _GIT_PATHSPEC and _GIT_MERGE_VIEW values you intend to export, and confirm the CSV and JSON outputs cover the fields you actually need.

## FAQ

### How do I generate GitHub stats with git-quick-stats?

The tool reads a local git repository, not the GitHub API, so you clone the repository first and then run git quick-stats inside it. Reports such as --commits-per-author and --contributors are produced from that local history.

### Does git-quick-stats have a Windows build?

The README lists Windows among the installation routes alongside UNIX and Linux, macOS via Homebrew, and Docker. The Dockerfile installs bash on an Alpine base, which is one way to run it where bash is not the default shell.

### Can I limit git-quick-stats to a date range?

Yes. Export _GIT_SINCE and _GIT_UNTIL before running the command, and the README notes this affects all stats that parse the git log history until the variables are unset.

### What does _GIT_LIMIT change in git-quick-stats?

It limits output for the changelogs and branch tree options, and the README states the default is 10. Set it with export _GIT_LIMIT=20 before running the report.

### How does git-quick-stats handle merge commits?

The _GIT_MERGE_VIEW variable controls this. Setting it to enable includes merge commits in the stats, while exclusive shows only merge commits.

## Sources

- [git-quick-stats/git-quick-stats on GitHub](https://github.com/git-quick-stats/git-quick-stats)
- [License: MIT](https://github.com/git-quick-stats/git-quick-stats/blob/master/LICENSE)
- [Project website](https://git-quick-stats.sh)
- [README](https://github.com/git-quick-stats/git-quick-stats/blob/master/README.md)
- [Releases](https://github.com/git-quick-stats/git-quick-stats/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/git-quick-stats-git-quick-stats