https://github.com/yl0711-coder/git-commit-fortune
Read Git history and generate a playful repository fortune in your terminal.
https://github.com/yl0711-coder/git-commit-fortune
cli developer-tooling fun git python terminal
Last synced: 14 days ago
JSON representation
Read Git history and generate a playful repository fortune in your terminal.
- Host: GitHub
- URL: https://github.com/yl0711-coder/git-commit-fortune
- Owner: yl0711-coder
- License: mit
- Created: 2026-04-22T13:26:20.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-18T10:10:01.000Z (about 1 month ago)
- Last Synced: 2026-05-18T12:14:36.871Z (about 1 month ago)
- Topics: cli, developer-tooling, fun, git, python, terminal
- Language: Python
- Size: 29.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Git Commit Fortune
Read a repository's Git history and generate a playful fortune about the codebase.
It is not a serious analytics tool. It is a small local CLI that turns commit patterns into a screenshot-friendly repository reading.
## Why It Exists
Git history contains patterns:
- too many midnight commits
- too many commits containing `fix`
- too many `final`, `temporary`, or `wip` messages
- weekend commits that should probably have waited
- short commit messages that hide motive
`git-commit-fortune` reads those signals and turns them into a small fortune report.
## Installation
From a source checkout:
```bash
bin/git-commit-fortune
```
Or install locally in editable mode:
```bash
python3 -m pip install -e .
git-commit-fortune
```
## Usage
Analyze the current repository:
```bash
git-commit-fortune
```
Analyze another repository:
```bash
git-commit-fortune /path/to/repo
```
Use fewer commits:
```bash
git-commit-fortune --limit 30
```
Only consult recent commits:
```bash
git-commit-fortune --since "2 weeks ago"
git-commit-fortune --since 2026-01-01
```
Print JSON:
```bash
git-commit-fortune --json
```
Print a compact one-line fortune:
```bash
git-commit-fortune --one-line
```
Fail when risky patterns are found:
```bash
git-commit-fortune --strict
git-commit-fortune --strict --json
```
## Example Output
```text
Git Commit Fortune
Repository: /path/to/repo
Omen: The Final That Was Not Final
Fortune level: cursed but deployable
Repository mood: functional but emotionally unavailable
Spirit animal: a caffeinated octopus holding a rollback plan
Signs:
- 80 recent commits were consulted
- 2 author(s) left fingerprints in the history
- 26 commit(s) mention fix, bug, or hotfix
- 7 commit(s) happened after 10 PM or before 6 AM
- "final" appeared 2 time(s), which is rarely final
Prediction:
A commit called 'final final' will appear before anyone admits defeat.
Advice:
Before the next fix, ask whether the bug is a symptom or a tradition.
Lucky command:
git log --oneline --grep=final
```
## One-Line Output
```bash
git-commit-fortune --one-line
```
```text
Git Commit Fortune: The Calm Before Refactor | mostly harmless | a calm capybara sitting on green CI
```
## JSON Output
```bash
git-commit-fortune --json
```
JSON output includes:
- repository path
- generated fortune
- statistics used by the fortune generator
- lucky command suggestion
This is useful if you want to build a badge, dashboard, or another wrapper around the output.
## Strict Mode
`--strict` keeps the normal report output, then exits with code `1` when recent commits contain high-risk patterns.
It currently fails on signals such as:
- repeated `final` commits
- unusually common `wip`, `temporary`, or `hack` commits
- unusually common `fix`, `bug`, or `hotfix` commits
- unusually common after-hours commits
- very short commit subjects across a non-trivial history
This is useful for a lightweight CI check before a release. It is still a playful heuristic, not a quality gate for team performance.
## What It Checks
The first version looks at recent commit history and detects:
- author count
- commit count
- optional Git-native `--since` time window
- after-hours commits
- weekend commits
- average subject length
- keywords such as `fix`, `bug`, `hotfix`, `wip`, `temporary`, `final`, `hack`, and `release`
- optional strict-mode findings for CI-friendly exit codes
## Non-Goals
This project is intentionally small.
It does not try to be:
- a serious Git analytics platform
- a productivity tracker
- a team performance measurement tool
- a dashboard
- a remote service
It should stay local, lightweight, and fun.
## Documentation Maintenance
This project keeps English and Chinese README files in sync. When updating usage, examples, options, or project positioning in `README.md`, update `README.zh-CN.md` in the same change.
## Development
Run tests:
```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```
Compile source:
```bash
python3 -m compileall src tests
```
Run the CLI from source:
```bash
bin/git-commit-fortune --limit 20
```
## License
MIT