# gmap

Git activity maps you can use: heatmaps, churn, exports, and a no‑nonsense TUI.

No dashboards. No hype. Just answers to: what changed, when, and by whom.

## Install

```sh
cargo install gmap
```

Requires a Git repo. Data is read locally; nothing leaves your machine.

## Quick start

- TUI heatmap for the current repo
  ```sh
  gmap heat --tui
  ```

- JSON heatmap, monthly buckets, filter by author
  ```sh
  gmap --repo /path/to/repo heat --json --monthly --author "alice"
  ```

- Top churn (aggregate file changes)
  ```sh
  gmap churn --json --since 3 months ago
  ```

- Full export (per‑commit, per‑file), newline‑delimited
  ```sh
  gmap export --ndjson
  ```

## Flags you’ll actually use

- Global
  - `--repo <path>`: analyze this repo (default: `.`)
  - `--cache <dir>`: where to place/read the `.db` cache
  - `--since/--until <date>`: time bounds (supports `YYYY-MM-DD`, RFC3339, `X days/weeks/months ago`, `yesterday`, `today`, `now`, `last week`, `last month`, or any Git ref)
  - `--include-merges`: count merge commits (off by default)
  - `--author <text>` / `--author-email <text>`: substring match, case‑insensitive

- Heat
  - `--json` / `--ndjson`
  - `--monthly`: group by month instead of week

- Churn
  - `--json` / `--ndjson`
  - `--depth <n>`: aggregate by directory depth

- Export
  - `--json` / `--ndjson`

## TUI

- Tabs: Heatmap • Stats • Files • Timeline • Commits
- Keys
  - `Tab` / `Shift+Tab`: switch views
  - `←/→` or `j/k`: move selection
  - `/`: search weeks/authors (filter)
  - `Enter`: open commit list for selected period
  - `c`: copy commit hash
  - `h` or `F1`: help; `q`: quit

Tip: The Files view shows file‑type breakdowns for the selected period and overall, so you can spot what kinds of files are being touched.

## What gmap gives you

- A timeline of change: commits and line deltas by week/month
- Churn hotspots: where change concentrates (by file or directory)
- Contributors and patterns: filter by author/email to slice activity
- Portable data: JSON/NDJSON outputs for your own scripts

What it’s not: a general Git UI, blame replacement, or a web app.

## Performance notes

- Uses a local SQLite cache under `.gmap/` to avoid recomputing diffs
- Line diffs use a robust algorithm; binary files are ignored unless `--binary`
- Merge commits are excluded by default to reduce noise

## Contributing

Bug reports, ideas, and small PRs welcome. Keep changes focused. If you add a feature, add a flag and a short example to this README.

## License

MIT. See `LICENSE`.