git-year 0.5.0

A compact terminal heatmap showing one year of Git commits (like GitHub contributions, but with compact bars instead of squares, to fit into a smaller terminal window)

git-year

A compact terminal heatmap showing one year of Git commits — similar to GitHub’s contribution graph, but optimized for small terminal windows using minimal vertical bars instead of squares.

Perfect for developers who want a clean, unobtrusive activity overview directly inside the terminal.

---

Features

• Shows the past year of commit activity (today back to the same date last year) for the current Git repo
• Jump to any calendar year with --year 2024 (auto-stops at today if the year is still in progress)
• Choose Monday or Sunday as the calendar week start (default: Monday) and keep the preference across reboots
• Green intensity gradient based on commit volume
• Compact vertical bars (|) instead of large squares — fits even tiny terminals
• Zero dependencies (pure Python + Git)
• 256-color ANSI output with dark-mode-friendly palette
• Highlights the current weekday
• Works in macOS, Linux, Windows Terminal, VS Code terminal, Git Bash
• Graceful message if run outside a Git repo
• Ready for PyPI (pip install git-year)

---

Installation

bash
pip install git-year

---

Usage

Simply run from inside a Git repository:

git-year

You’ll see a compact 7×52 bar heatmap covering the past year up to today:

M ||||||||||||||||||||||||||||||
T ||||||||||||||||||||||||||||||
W ||||||||||||||||||||||||||||||
T ||||||||||||||||||||||||||||||
F ||||||||||||||||||||||||||||||
S ||||||||||||||||||||||||||||||
S ||||||||||||||||||||||||||||||

• Rows = weekdays (Mon–Sun)
• Columns = weeks (52 total) covering the trailing year’s timeline (same date last year → today)
• Color intensity = commit count
• The current day label is highlighted in yellow

Show the installed version:

git-year --version

Need a refresher on the available options?

git-year --help

Focus on a specific calendar year (Jan 1 → Dec 31, or today if it’s still the current year):

git-year --year 2024

Choose the start of the week (case-insensitive, saved to ~/.config/git-year/config.toml on Linux/macOS or %APPDATA%\git-year\config.toml on Windows):

git-year --week-start sunday
git-year --week-start Mon

When you try to peek into a future year you’ll get a playful reminder:

Trying to look into the future? ;)

---

Requirements

• Python 3.8+
• Git available in PATH
• A terminal with ANSI color support (all modern terminals)
• On legacy cmd.exe ANSI colors may fall back to monochrome

---

Contributing

Contributions are welcome! Ideas, issues, and pull requests are appreciated.

---

License

MIT License Copyright (c) 2025 Serge Velbovets

---

Enjoy your terminal-native Git activity graph without leaving the shell — git-year keeps your development rhythm visible, simple, and elegant.