# pi-git-diff

[![npm version](https://img.shields.io/npm/v/pi-git-diff.svg)](https://www.npmjs.com/package/pi-git-diff)
[![CI](https://github.com/max-miller1204/pi-git-diff/actions/workflows/ci.yml/badge.svg)](https://github.com/max-miller1204/pi-git-diff/actions/workflows/ci.yml)
[![Pi package](https://img.shields.io/badge/Pi-package-8a76b5)](https://pi.dev/packages/pi-git-diff)

`pi-git-diff` adds a fast, keyboard-driven Git diff viewer to Pi.
It opens directly inside Pi's terminal UI and shows every staged, unstaged, and untracked working tree change in one review surface.

## Features

- `/diff` opens an interactive full-screen working tree review.
- A file sidebar and unified patch pane make large changes easy to navigate.
- Vim-style movement and dedicated file and hunk shortcuts keep review fast.
- Staged and unstaged changes are compared together against `HEAD`.
- Untracked files and repositories without an initial commit are supported.
- Binary changes, unusual filenames, and deleted files are handled safely.
- Per-file and total patch limits keep very large diffs responsive.
- Files can be marked as reviewed for the current viewer session.
- The layout automatically hides the sidebar in narrow terminals.

## Install

Install the published package from npm:

```sh
pi install npm:pi-git-diff
```

View it in the [Pi package gallery](https://pi.dev/packages/pi-git-diff) or on [npm](https://www.npmjs.com/package/pi-git-diff).

Install directly from GitHub:

```sh
pi install git:github.com/max-miller1204/pi-git-diff
```

Try a checkout without installing it:

```sh
git clone https://github.com/max-miller1204/pi-git-diff.git
cd pi-git-diff
pi -e .
```

## Usage

Run `/diff` from an interactive Pi session inside a Git worktree.
The viewer requires Pi's TUI mode and the `git` executable.

| Key | Action |
| --- | --- |
| `j` / `k` or `Up` / `Down` | Move in the focused pane |
| `Page Up` / `Page Down` | Scroll one page |
| `Tab` | Switch between the file list and patch |
| `n` / `p` | Jump to the next or previous file |
| `]` / `[` | Jump to the next or previous hunk |
| `h` / `l` or `Left` / `Right` | Scroll long lines horizontally |
| `g` / `G` | Jump to the first or last row |
| `m` | Mark the current file reviewed |
| `b` | Toggle the file sidebar |
| `r` | Reload changes from disk |
| `?` | Toggle shortcut help |
| `q` or `Escape` | Close the viewer |

Reviewed marks are intentionally temporary and reset when Pi exits or the viewer is reopened.

## Diff semantics and limits

Tracked files are rendered from `git diff HEAD`, so staged and unstaged changes appear as one combined working tree diff.
Untracked files are rendered as additions through `git diff --no-index`.
Repositories with an unborn `HEAD` use the same no-index path for their initial files.

Each file patch is capped at 2 MB, and the complete review is capped at 10 MB.
The viewer labels truncated files instead of silently presenting partial output as complete.
Git commands time out after 30 seconds, and at most six file patches are loaded concurrently.

## Development

```sh
git clone https://github.com/max-miller1204/pi-git-diff.git
cd pi-git-diff
npm install
npm run check
npm run pack:check
```

The test suite includes pure model and rendering tests, real temporary-repository Git tests, and a real Pi RPC package-load test.
The package ships TypeScript source directly because Pi loads extensions through jiti.

## Publishing and the Pi gallery

The package is published to npm and listed in the [Pi package gallery](https://pi.dev/packages/pi-git-diff).
The `pi-package` npm keyword and `pi.extensions` manifest let the gallery discover releases automatically without a separate submission process.

### Future releases

Start from a clean, current `main` branch and authenticate with npm:

```sh
git switch main
git pull --ff-only
npm login --auth-type=web
npm whoami
```

Install the locked dependencies and run every release check:

```sh
npm ci
npm run verify
npm audit --audit-level=high
```

Create the release commit and tag with the appropriate semantic version bump:

```sh
npm version patch
# Use `npm version minor` or `npm version major` when appropriate.
```

Publish the new public package, then push the version commit and tag:

```sh
npm publish --access public
git push origin main --follow-tags
```

Verify npm, Pi installation, and the gallery after publication:

```sh
npm view pi-git-diff version
pi update npm:pi-git-diff
```

Each npm version is immutable, so bump the version before every subsequent publication.
If publication succeeds but the Git push fails, fix the Git problem and retry only the push rather than publishing the same version again.
The Pi gallery may take a short time to refresh after npm accepts a release.

## License

MIT