A minimal and compact terminal heatmap that shows one full year of Git commits in a GitHub-style layout, using vertical bars instead of squares to fit comfortably in small terminal windows.
A clean and lightweight CLI contribution calendar for developers who want a quick visual overview of their Git activity directly from the command line.
- Shows the past year of commit activity for the current Git repo
- Similar to GitHub’s contribution graph, but runs directly in your terminal
- Jump to any calendar year
- Choose Sunday or Monday as the calendar week start 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
- PyPI ready (
pipx install git-year)
pipx install git-year
or
pip install --user git-year
or
uv tool install git-year
How to install pipx? (Python cli tool installer)
How to install pip? (Python package manager)
How to install uv? (modern Python package manager)
Run git-year inside any Git repository to display a one-year contribution heatmap in your terminal.
git-year
# outputs a GitHub-style
# contribution heatmap
# (shown as vertical bars)You’ll see a compact 7×52 bar heatmap representing your activity for the past year up to today, displayed in dark mode with retro-style green bars highlighting your commit days:
- Columns = weeks (52 total)
- Rows = weekdays (with the current day highlighted)
- Week can start on Sun or Mon
- Color intensity = commit count
Choose the start of the week:
git-year --week-start Sunday
# also can be S, Su, Sun
git-year --week-start Monday
# also can be M, Mo, Mon
# saved to `~/.config/git-year/config.toml` on Linux/macOS or `%APPDATA%\git-year\config.toml` on Windows
Focus on a specific calendar year:
git-year --year 2024
Show the installed version:
git-year -V
git-year --version
See the available options:
git-year -h
git-year --help
- Python 3.8+
- Git installed
Contributions are welcome! Ideas, issues, and pull requests are appreciated.
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.