git-ember

A GitHub-style heatmap of commit activity for your terminal.

Overview

git-ember reads directly from your local Git repository history—no external APIs or network requests—and displays a colored contribution heatmap similar to what you see on GitHub profiles. It supports multiple color schemes, branch filtering, custom date ranges, repository statistics, branch tree visualizations, and hour-of-day activity heatmaps.

Prerequisites

• Python 3.11 or higher
• Git installed and available in PATH

Installation

From PyPI (recommended)

pip install git-ember

From source

1. Clone the repository:

   git clone https://codeberg.org/lukavr05/git-ember.git
   cd git-ember
   

2. Install the package:

   pip install -e .
   

3. Verify the installation:

   git-ember --version
   

Using uv

If you use uv as your package manager:

uv pip install git-ember

Running without installation

If you prefer not to install the package, run directly:

PYTHONPATH=src python3 main.py /path/to/repo

Uninstall

pip uninstall git-ember

Configuration

git-ember reads configuration from ~/.config/git-ember/config.toml (or the platform-specific config directory). CLI arguments take precedence over config values.

Variable	Required	Default	Description
color	No	green	Color scheme name
border	No	=	Border character
week_start	No	sunday	Week start day (sunday/monday)
ascii	No	false	Use ASCII characters
scale	No	auto	Intensity scaling (auto/adaptive)
extended	No	false	Show extended report by default
compact	No	false	Show last 4 months only
tree	No	false	Show branch tree by default
years	No	1	Number of years to show
recent_count	No	5	Number of recent commits to display

Example config file

color = "blue"
border = "-"
week_start = "monday"
ascii = "true"
scale = "adaptive"
extended = "true"
compact = "true"
tree = "true"
years = 2
recent_count = 10

Usage

Show commit heatmap for the current year:

git-ember

Show heatmap for a specific repository:

git-ember /path/to/repo

Show multiple years:

git-ember --years 2
git-ember -y 3

Use different color schemes:

git-ember --color green    # default
git-ember --color blue
git-ember --color orange
git-ember --color purple
git-ember --color mono

Show heatmap for a specific branch:

git-ember --branch feature-x

Display branch tree visualization:

git-ember --tree
git-ember --branch feature-x --tree

Show custom date range:

git-ember --after 2025-01-01 --before 2025-06-30
git-ember --after 2025-01-01

Show extended report with recent commits, top contributors, and statistics:

git-ember --extended
git-ember -e

Filter commits by author:

git-ember --author "John Doe"
git-ember -A "john@"

Exclude or include only merge commits:

git-ember --no-merges
git-ember --merges-only

Filter commits by message content:

git-ember --grep "bugfix"
git-ember --grep "feat"

Show hour-of-day activity heatmap:

git-ember --hourly

Strip ANSI color codes for piping or file export:

git-ember --plain
git-ember --plain > heatmap.txt

Reset configuration to defaults:

git-ember --reset-default

Show debug information:

git-ember --verbose

Command-line options

Flag	Alias	Description	Default
--color	-c	Color scheme	green
--years	-y	Number of years to show (max 10)	1
--border	-b	Border character	=
--extended	-e	Show commits, contributors, stats	false
--ascii	-a	Use ASCII characters instead of Unicode	false
--plain	-p	Strip all ANSI color codes	false
--compact	-	Show last 4 months only	false
--branch	-	Show heatmap for specific branch	all branches
--tree	-t	Show branch tree under heatmap	false
--scale	-	Intensity scaling: auto or adaptive	auto
--after	-	Show commits after date (YYYY-MM-DD)	-
--before	-	Show commits before date (YYYY-MM-DD)	-
--week-start	-	Week start: sunday or monday	sunday
--author	-A	Filter commits by author	-
--no-merges	-	Exclude merge commits	false
--merges-only	-	Show only merge commits	false
--grep	-	Filter commits by message content	-
--hourly	-	Show hour-of-day x day-of-week heatmap	false
--reset-default	-	Reset config to defaults	-
--version	-V	Show version	-
--verbose	-v	Show debug information	-
--help	-h	Show help	-

Project Structure

git-ember/
├── main.py                 # CLI entry point (when running without install)
├── pyproject.toml          # Package configuration
├── Makefile              # Build targets (install, lint, test)
├── .python-version       # Python version (3.11)
├── README.md             # This file
├── LICENSE              # MIT license
├── docs/
│   └── CHANGELOG.md    # Version history
├── src/
│   └── gitember/
│       ├── __init__.py   # Package version
│       ├── cli.py        # CLI argument parsing and main logic
│       ├── git.py       # Git subprocess calls and data parsing
│       ├── render.py    # Heatmap and branch tree rendering
│       ├── colors.py    # ANSI color scheme definitions
│       └── config.py    # Config file load/save
└── tests/
    ├── conftest.py      # Pytest fixtures for git repos
    ├── test_config.py  # Config tests
    ├── test_git.py   # Git operations tests
    └── test_render.py # Rendering tests

Development

Run the linter:

make lint

Run tests:

pytest

Run tests with coverage:

pytest --cov=gitember --cov-report=term-missing

License

MIT License — see LICENSE file.