Metadata-Version: 2.4
Name: git-ember
Version: 1.4.2
Summary: A GitHub-style heatmap of commits and local repo statistics for your terminal
Author-email: Luka van Rooyen <lukavrooyen@proton.me>
License-Expression: MIT
Project-URL: repository, https://codeberg.org/lukavr05/git-ember
Keywords: git,cli,tui
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# git-ember

[![PyPI](https://img.shields.io/pypi/v/git-ember)](https://pypi.org/project/git-ember/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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)

```bash
pip install git-ember
```

### From source

1. Clone the repository:

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

2. Install the package:

   ```bash
   pip install -e .
   ```

3. Verify the installation:

   ```bash
   git-ember --version
   ```

### Using uv

If you use [uv](https://github.com/astral-sh/uv) as your package manager:

```bash
uv pip install git-ember
```

### Running without installation

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

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

### Uninstall

```bash
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

```toml
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:

```bash
git-ember
```

Show heatmap for a specific repository:

```bash
git-ember /path/to/repo
```

Show multiple years:

```bash
git-ember --years 2
git-ember -y 3
```

Use different color schemes:

```bash
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:

```bash
git-ember --branch feature-x
```

Display branch tree visualization:

```bash
git-ember --tree
git-ember --branch feature-x --tree
```

Show custom date range:

```bash
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:

```bash
git-ember --extended
git-ember -e
```

Filter commits by author:

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

Exclude or include only merge commits:

```bash
git-ember --no-merges
git-ember --merges-only
```

Filter commits by message content:

```bash
git-ember --grep "bugfix"
git-ember --grep "feat"
```

Show hour-of-day activity heatmap:

```bash
git-ember --hourly
```

Strip ANSI color codes for piping or file export:

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

Reset configuration to defaults:

```bash
git-ember --reset-default
```

Show debug information:

```bash
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:

```bash
make lint
```

Run tests:

```bash
pytest
```

Run tests with coverage:

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

## License

MIT License — see [LICENSE](LICENSE) file.
