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:

bin/git-commit-fortune

Or install locally in editable mode:

python3 -m pip install -e .
git-commit-fortune

Usage

Analyze the current repository:

git-commit-fortune

Analyze another repository:

git-commit-fortune /path/to/repo

Use fewer commits:

git-commit-fortune --limit 30

Only consult recent commits:

git-commit-fortune --since "2 weeks ago"
git-commit-fortune --since 2026-01-01

Print JSON:

git-commit-fortune --json

Print a compact one-line fortune:

git-commit-fortune --one-line

Fail when risky patterns are found:

git-commit-fortune --strict
git-commit-fortune --strict --json

Example Output

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

git-commit-fortune --one-line

Git Commit Fortune: The Calm Before Refactor | mostly harmless | a calm capybara sitting on green CI

JSON Output

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:

PYTHONPATH=src python3 -m unittest discover -s tests

Compile source:

python3 -m compileall src tests

Run the CLI from source:

bin/git-commit-fortune --limit 20

License

MIT