Metadata-Version: 2.4
Name: git-ember
Version: 1.2.1
Summary: A GitHub-style heatmap of commits for your terminal
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: ruff>=0.15.9

# 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 top contributors.

## Prerequisites

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

## Installation

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

### Running without installation

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

```bash
PYTHONPATH=src python3 main.py .
```

To verify the installation:

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

To uninstall:

```bash
pip uninstall git-ember
```

## Configuration

git-ember reads configuration from `~/.config/git-ember/config.toml`. CLI arguments take precedence over config values.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `color` | No | `green` | Color scheme name |
| `border` | No | `=` | Border character |

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

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

Show repository statistics:

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

## Development

Run the linter:

```bash
make lint
```

> ⚠️ Note: No test suite exists currently.

## License

No LICENSE file exists in this repository.
