git-ember 1.3.1

A GitHub-style heatmap of commits for your terminal

git-ember

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

Overview

git-ember displays a colored grid representing commit activity over time, similar to the contribution graph shown on GitHub profiles. It reads directly from your local Git history—no external APIs or network requests required.

The tool supports multiple color schemes, branch filtering, custom date ranges, and can display repository statistics, recent commits, and branch tree visualizations.

Prerequisites

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

Installation

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
   

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 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)

Example config file

color = "blue"
border = "-"
week_start = "Monday"

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 and top contributors:

git-ember --extended
git-ember -e

Show repository statistics:

git-ember --stats
git-ember -S

Command-line options

Flag	Alias	Description	Default
--color	-c	Color scheme	green
--years	-y	Number of years to show	1
--border	-b	Border character	=
--extended	-e	Show recent commits and top contributors	false
--stats	-S	Show repository statistics	false
--ascii	-a	Use ASCII characters instead of Unicode	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)	-
--version	-V	Show version	-
--help	-h	Show help	-

Project Structure

git-ember/
├── main.py                 # Entry point
├── pyproject.toml         # Package configuration
├── Makefile              # Build targets
├── .python-version       # Python version (3.11)
├── README.md            # This file
├── docs/
│   ├── CHANGELOG.md    # Version history
│   └── PLAN.md        # Feature planning
├── src/
│   └── gitember/
│       ├── __init__.py   # Package version
│       ├── cli.py        # CLI argument parsing and config
│       ├── git.py       # Git command execution and parsing
│       ├── render.py   # Grid and branch tree rendering
│       └── colors.py   # ANSI color scheme definitions
└── tests/
    ├── conftest.py      # Pytest fixtures
    ├── 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

⚠️ Note: Code coverage is not configured.

License

MIT License — see LICENSE for details.