diff --git a/README.md b/README.md index 04418161..661a6ac4 100644 --- a/README.md +++ b/README.md @@ -1,142 +1,124 @@ -# Git Diff Review - -Git Diff Review is a native macOS app for reviewing local Git changes before -they are committed. It gives a GitHub-style review surface for a working tree: -file navigation, staged/unstaged/untracked diffs, split or unified views, -viewed-file tracking, review notes, and inline comments stored locally. +
-The desktop app is built with Electron, Vue, and TypeScript. A Go backend reads -repository state through Git, serves a local HTTP API over a Unix socket, and -persists review sessions in SQLite. +Git Diff Review -## What It Does +# Git Diff Review -- opens any local Git repository; -- shows changed files with additions, deletions, status, and rename metadata; -- renders staged, unstaged, and untracked patches; -- supports split and unified diff modes; -- can hide whitespace-only diff noise; -- tracks viewed files per repository in local storage; -- creates local review sessions with rich-text summaries; -- stores inline review comments and timeline events in SQLite; -- runs as a packaged macOS app or as a local development stack. +**Review your local Git changes like a pull request — before you commit.** +**On your machine. Nothing leaves it.** -This is a local review tool. It does not publish comments to GitHub, create pull -requests, or modify the repository contents. +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +![Platform: macOS (Apple Silicon)](https://img.shields.io/badge/platform-macOS%20(Apple%20Silicon)-black) +[![Latest release](https://img.shields.io/github/v/release/oullin/git-diff?label=download)](https://github.com/oullin/git-diff/releases) -## Workspace Layout +![Git Diff Review reviewing a working tree](docs/images/hero.png) -| Path | Role | -| --------------------- | ------------------------------------------------------------ | -| `packages/ui` | Electron/Vue desktop app and renderer UI. | -| `packages/bridge` | TypeScript HTTP client used by Electron. | -| `packages/domain` | Shared DTOs + framework-agnostic diff logic, consumed by `ui` and `bridge`. | -| `packages/api` | Go backend that reads Git diffs and stores reviews. | -| `packages/tools` | Turbo cache wrapper and unsigned macOS release helper. | +
-## Requirements +Git Diff Review is a native macOS app that gives you a full GitHub-style review +surface for your **local working tree**. Open any repository, walk every changed +file, read the diff in split or unified view, mark files as you review them, leave +yourself notes and inline comments — then commit with confidence. It never pushes +your code anywhere. -- macOS -- Git -- Go -- Node.js with Corepack -- pnpm `10.33.0` +## Why you need it -Enable pnpm through Corepack if needed: +You commit changes you never actually re-read. `git diff` in the terminal is +cramped and easy to skim past. Opening a real pull request just to review your own +work is heavyweight — and it forces your code onto a server before it's ready. -```sh -corepack enable -corepack prepare pnpm@10.33.0 --activate -``` +Git Diff Review gives you the **pull-request review experience, locally**: -## Quick Start +- Catch the debug log, the stray `TODO`, the half-finished refactor *before* it + lands in history. +- Review with the same muscle memory you already have from GitHub — file list, + viewed checkboxes, split diffs, inline comments. +- Keep everything on your machine. No cloud, no sign-up, no telemetry. -From the repository root: +## What you get -```sh -pnpm install -pnpm build -pnpm --filter ui start -``` +- **A real review surface.** Navigate changed files with status badges and + addition/deletion counts, jump between hunks, and search files across all your + repos at once. +- **Staged, unstaged, and untracked** — see every kind of change, with rename + detection and whitespace noise you can hide. +- **Split or unified diffs** with syntax highlighting, your choice per session. +- **Viewed-file tracking.** Tick files off as you go (`0/14 viewed`) so you never + lose your place in a large change. +- **Notes and inline comments.** Write a rich-text review summary and drop inline + comments on specific lines — stored locally and kept across sessions. +- **Branch, commit, and PR context.** Switch branches, pin a commit to review + against, and browse pull requests and history without leaving the app. +- **AI walkthroughs (optional).** Generate a guided walkthrough of a change to get + oriented fast. +- **Keyboard-driven.** `j`/`k` to navigate, `v` to mark viewed, `c` to comment, + `⌘↵` to submit — review without touching the mouse. +- **Native and local.** A fast Electron + Vue interface backed by a Go engine that + reads Git directly and stores your reviews in local SQLite. -For active development: +## See it in action -```sh -pnpm dev -``` +| | | +| --- | --- | +| ![File navigation and status badges](docs/images/file-navigation.png) | ![Split diff view](docs/images/split-view.png) | +| **Walk every changed file** with status, counts, and viewed tracking. | **Read split or unified diffs** with syntax highlighting. | +| ![Review notes and inline comments](docs/images/review-notes.png) | ![AI walkthrough](docs/images/walkthrough.png) | +| **Leave notes and inline comments** as you review. | **Generate an AI walkthrough** to get oriented fast. | -The dev command starts the Vite renderer, compiles Electron, starts the Go -backend, waits for the local socket API, and launches Electron. +> Screenshots live in [`docs/images/`](docs/images/). See that folder's README for +> what each capture should show. -## Backend CLI +## Install -The Electron app normally starts the backend automatically. To inspect the -backend directly: +> **macOS on Apple Silicon.** The app is currently in beta and distributed +> unsigned, so macOS Gatekeeper needs one extra click on first launch. -```sh -cd packages/api -go run ./cmd help -go run ./cmd serve-http --socket /tmp/git-diff.sock -``` +**Download the app** -To point the Electron app at an already-running backend, set -`API_BRIDGE_SOCKET` to the socket path before launching it. +1. Grab the latest `.dmg` from the + [Releases page](https://github.com/oullin/git-diff/releases). +2. Open it and drag **Git Diff Review** to Applications. +3. On first launch, **right-click the app → Open**, then confirm. (macOS blocks + unsigned apps on a normal double-click; right-click → Open only needs doing + once.) -## Development Commands +**Homebrew** _(planned)_ ```sh -pnpm build -pnpm test -pnpm lint -pnpm format:check -pnpm check +brew install --cask oullin/tap/git-diff ``` -Useful package-level commands: +## Your code stays yours -```sh -pnpm --filter ui build -pnpm --filter ui test -pnpm --filter ui dev -go test ./packages/api/... -``` - -## Review Data - -Review sessions, comments, events, and preferences are local. By default the Go -backend stores the review database under: +Git Diff Review reads your repository state through Git and serves a local API over +a Unix socket — it talks only to your machine. Review sessions, comments, events, +and preferences are stored in a local SQLite database at: ```text ~/Library/Application Support/git-diff/reviews.sqlite3 ``` -Viewed-file state is stored by the renderer per repository root. +It **does not** publish comments to GitHub, create pull requests, or modify your +repository contents. It's a review surface, nothing more. -## Release +## Build from source -Releases are built with [Electron Forge](https://www.electronforge.io/). Tag a -version to cut a release in CI: - -```sh -git tag v0.1.1 && git push origin v0.1.1 -``` - -The `Release` workflow builds the unsigned macOS arm64 `.dmg` + `.zip`, publishes -a GitHub Release, and opens a Homebrew cask bump PR against `oullin/homebrew-tap` -on final (non-prerelease) tags. See [docs/distribution.md](docs/distribution.md). - -To build the same artifacts locally: - -```sh -pnpm release:mac:unsigned # builds the Go API + renderer, then `electron-forge make` -``` +Git Diff Review is a pnpm + Turbo monorepo pairing an Electron/Vue/TypeScript +desktop app with a Go backend. -The Electron package is configured (in `packages/ui/forge.config.ts`) with: +| Path | Role | +| ----------------- | --------------------------------------------------------------------------- | +| `packages/ui` | Electron/Vue desktop app and renderer UI. | +| `packages/bridge` | TypeScript HTTP client used by Electron. | +| `packages/domain` | Shared DTOs + framework-agnostic diff logic, consumed by `ui` and `bridge`. | +| `packages/api` | Go backend that reads Git diffs and stores reviews. | +| `packages/tools` | Turbo cache wrapper and unsigned macOS release helper. | -- app id: `io.gocanto.git-diff` -- product name: `Git Diff Review` -- GitHub release target: `oullin/git-diff` +To set up the toolchain, run it locally, and learn the development commands, see +**[docs/development.md](docs/development.md)**. Releases are built with +[Electron Forge](https://www.electronforge.io/) — for tagging, packaging, signing, +and the release pipeline, see **[docs/distribution.md](docs/distribution.md)**. ## License -See [LICENSE](LICENSE). +[MIT](LICENSE) © Gus Canto diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..2e1eb780 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,123 @@ +# Development + +How to set up the toolchain, run Git Diff Review locally, and work in the +monorepo. For the product overview and install instructions, see the +[README](../README.md). For packaging and releases, see +[distribution.md](distribution.md). + +## Requirements + +- macOS +- Git +- Go +- Node.js with Corepack +- pnpm `10.33.0` + +Enable pnpm through Corepack if needed: + +```sh +corepack enable +corepack prepare pnpm@10.33.0 --activate +``` + +## Quick start + +From the repository root: + +```sh +pnpm install +pnpm build +pnpm --filter ui start +``` + +## Active development + +```sh +pnpm dev +``` + +The dev command starts the Vite renderer, compiles Electron, starts the Go +backend, waits for the local socket API, and launches Electron. + +## Backend CLI + +The Electron app normally starts the backend automatically. To inspect the +backend directly: + +```sh +cd packages/api +go run ./cmd help +go run ./cmd serve-http --socket /tmp/git-diff.sock +``` + +To point the Electron app at an already-running backend, set `API_BRIDGE_SOCKET` +to the socket path before launching it. + +## Development commands + +```sh +pnpm build +pnpm test +pnpm lint +pnpm format:check +pnpm check +``` + +Useful package-level commands: + +```sh +pnpm --filter ui build +pnpm --filter ui test +pnpm --filter ui dev +go test ./packages/api/... +``` + +## Formatting + +Format changed sources (Go + TS/Vue): + +```sh +pnpm format # or: make format +``` + +To format the entire repo, use `pnpm format-all` (`make format-all`). Run the +formatter after each change so commits stay clean. + +## Review data + +Review sessions, comments, events, and preferences are local. By default the Go +backend stores the review database under: + +```text +~/Library/Application Support/git-diff/reviews.sqlite3 +``` + +Viewed-file state is stored by the renderer per repository root. + +## Release + +Releases are built with [Electron Forge](https://www.electronforge.io/). Tag a +version to cut a release in CI: + +```sh +git tag v0.1.1 && git push origin v0.1.1 +``` + +The `Release` workflow builds the unsigned macOS arm64 `.dmg` + `.zip`, publishes +a GitHub Release, and opens a Homebrew cask bump PR against `oullin/homebrew-tap` +on final (non-prerelease) tags. + +To build the same artifacts locally: + +```sh +pnpm release:mac:unsigned # builds the Go API + renderer, then `electron-forge make` +``` + +The Electron package is configured (in `packages/ui/forge.config.ts`) with: + +- app id: `io.gocanto.git-diff` +- product name: `Git Diff Review` +- GitHub release target: `oullin/git-diff` + +See [distribution.md](distribution.md) for the full signing, notarization, and +Homebrew release flow. diff --git a/docs/images/README.md b/docs/images/README.md new file mode 100644 index 00000000..1311eaed --- /dev/null +++ b/docs/images/README.md @@ -0,0 +1,17 @@ +# Screenshots + +Images referenced by the [project README](../../README.md). Drop the real +captures here using the exact filenames below so the README renders them +automatically. Use PNG, retina resolution (capture at 2x), and a light UI theme +for consistency. + +| File | What it should show | +| --------------------- | ------------------------------------------------------------------------------ | +| `hero.png` | The main review window: file list, a split diff, branch/commit bar, toolbar. | +| `file-navigation.png` | The changed-files sidebar with status badges, +/- counts, and viewed checkboxes. | +| `split-view.png` | A diff in split (or unified) view with syntax highlighting. | +| `review-notes.png` | A review summary and/or an inline comment on a line. | +| `walkthrough.png` | The "Generate walkthrough" AI feature in use. | + +Until a file is added, its link in the README will show as a broken image — that +is expected and resolves the moment the PNG lands here.