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:

pi install npm:pi-git-diff

View it in the Pi package gallery or on npm.

Install directly from GitHub:

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

Try a checkout without installing it:

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

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

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

Install the locked dependencies and run every release check:

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

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

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:

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

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

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