From 40e6cd1784b74a937f90595fc6fbeba8ff281afa Mon Sep 17 00:00:00 2001 From: Gustavo Ocanto Date: Tue, 2 Jun 2026 14:57:32 +0800 Subject: [PATCH 1/3] docs: rewrite README as a product pitch, extract dev guide Reframe the README around end users who download and use the app rather than developers building from source. Lead with the value proposition, hero screenshot, benefit-led feature list, install path (with the unsigned-app first-launch note), and a privacy/local-first section. Move all setup, run, CLI, and release commands into docs/development.md, and add docs/images/README.md documenting the expected screenshots. --- README.md | 178 ++++++++++++++++++++---------------------- docs/development.md | 112 ++++++++++++++++++++++++++ docs/images/README.md | 17 ++++ 3 files changed, 214 insertions(+), 93 deletions(-) create mode 100644 docs/development.md create mode 100644 docs/images/README.md diff --git a/README.md b/README.md index 18e05872..c8e5e180 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,123 @@ -# 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 - -From the repository root: - -```sh -pnpm install -pnpm build -pnpm --filter ui 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. -For active development: +## What you get -```sh -pnpm dev -``` +- **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. -The dev command starts the Vite renderer, compiles Electron, starts the Go -backend, waits for the local socket API, and launches Electron. +## See it in action -## Backend CLI +| | | +| --- | --- | +| ![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 Electron app normally starts the backend automatically. To inspect the -backend directly: +> Screenshots live in [`docs/images/`](docs/images/). See that folder's README for +> what each capture should show. -```sh -cd packages/api -go run ./cmd help -go run ./cmd serve-http --socket /tmp/git-diff.sock -``` +## Install -To point the Electron app at an already-running backend, set -`API_BRIDGE_SOCKET` to the socket path before launching it. +> **macOS on Apple Silicon.** The app is currently in beta and distributed +> unsigned, so macOS Gatekeeper needs one extra click on first launch. -## Development Commands +**Download the app** -```sh -pnpm build -pnpm test -pnpm lint -pnpm format:check -pnpm check -``` +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.) -Useful package-level commands: +**Homebrew** _(planned)_ ```sh -pnpm --filter ui build -pnpm --filter ui test -pnpm --filter ui dev -go test ./packages/api/... +brew install --cask oullin/tap/git-diff ``` -## Review Data +## Your code stays yours -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. - -## Release +It **does not** publish comments to GitHub, create pull requests, or modify your +repository contents. It's a review surface, nothing more. -Build an unsigned macOS release artifact with: +## Build from source -```sh -pnpm release:mac:unsigned -``` +Git Diff Review is a pnpm + Turbo monorepo pairing an Electron/Vue/TypeScript +desktop app with a Go backend. -The Electron package is configured 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)**. For 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..21c0395f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,112 @@ +# 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) through go-fmt: + +```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 + +Build an unsigned macOS release artifact with: + +```sh +pnpm release:mac:unsigned +``` + +The Electron package is configured 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. From 411daaa0b8f279c4a996f6187061845693a010b4 Mon Sep 17 00:00:00 2001 From: Gustavo Ocanto Date: Tue, 2 Jun 2026 14:58:10 +0800 Subject: [PATCH 2/3] chore: ignore packages/ui build artifacts (out/, .cache/) --- packages/ui/.gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/ui/.gitignore b/packages/ui/.gitignore index fc0162e9..f793d082 100644 --- a/packages/ui/.gitignore +++ b/packages/ui/.gitignore @@ -1,3 +1,5 @@ dist/ dist-electron/ release/ +out/ +.cache/ From 95727b90d79c632404b2ce7c3cf3a43c61b1f2a5 Mon Sep 17 00:00:00 2001 From: Gustavo Ocanto Date: Tue, 2 Jun 2026 14:59:57 +0800 Subject: [PATCH 3/3] docs: address review feedback - Use lowercase keyboard shortcuts in README (j/k/v/c) per convention - Drop misleading 'through go-fmt' in formatting note (it can't format TS/Vue) --- README.md | 2 +- docs/development.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c8e5e180..17ce467f 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ Git Diff Review gives you the **pull-request review experience, locally**: 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, +- **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. diff --git a/docs/development.md b/docs/development.md index 21c0395f..e5d5a513 100644 --- a/docs/development.md +++ b/docs/development.md @@ -74,7 +74,7 @@ go test ./packages/api/... ## Formatting -Format changed sources (Go + TS/Vue) through go-fmt: +Format changed sources (Go + TS/Vue): ```sh pnpm format # or: make format