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.