git-review-workflow 0.1.0

package/README.md

@@ -0,0 +1,540 @@
+# git-review-workflow
+
+> Review a pull request by **editing and running** it, not just reading it. The
+> whole PR lands in your working tree as one staged diff; your fixes are then
+> extracted onto a clean branch automatically. Re-review only what changed.
+
+[![CI](https://github.com/EzeVillo/git-review-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/EzeVillo/git-review-workflow/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/tag/EzeVillo/git-review-workflow?label=release&sort=semver)](https://github.com/EzeVillo/git-review-workflow/releases)
+
+**English** · [Español](README.es.md)
+
+---
+
+Reviewing in a web UI is fine for leaving comments, but poor for actually
+*running* and *editing* the code. `git review start` puts the entire PR in your
+working tree as **staged, uncommitted changes**: it creates a `review/<branch>`
+branch whose working tree holds the PR tip, but whose `HEAD` sits at the
+merge-base with your base branch. Because it is just your working tree, you open
+the whole PR in any editor — read the diff, edit inline, run the tests — and when
+you are done, `git review finish` pulls *your* edits back out onto a separate
+`review-fixes/<branch>` branch (or onto the PR branch itself), keeping them
+cleanly apart from the author's work. Re-review only the new commits after an
+update with `--delta`.
+
+> **All commands live under `git review <verb>`** — `git review start`,
+> `git review finish`, `git review status`, and so on, the way `git bisect` and
+> `git stash` group their verbs.
+
+## Why not just use my IDE's PR view?
+
+Most tools let you *see* a PR. The gap this fills is *acting* on one — editing
+and running it like ordinary working-tree changes, then handing your fixes back
+without manual stashing or cherry-picking.
+
+|                                 |    View the PR    | Edit & run as working tree | Auto-extract your fixes | Incremental re-review (`--delta`) | Editor-agnostic |
+|---------------------------------|:-----------------:|:--------------------------:|:-----------------------:|:---------------------------------:|:---------------:|
+| **git-review-workflow**         |         ✅         |             ✅              |            ✅            |                 ✅                 |        ✅        |
+| `gh pr checkout` / `glab`       | ⚠️ plain checkout |             ✅              |            ❌            |                 ❌                 |        ✅        |
+| JetBrains *Review Pull Request* |         ✅         |       ⚠️ in-IDE only       |            ❌            |                 ❌                 |        ❌        |
+| VS Code *GitHub PR* extension   |         ✅         |       ⚠️ in-IDE only       |            ❌            |                 ❌                 |        ❌        |
+| GitHub / GitLab web UI          |         ✅         |             ❌              |            ❌            |            ⚠️ partial             |        ✅        |
+
+Because the PR is just staged changes, anything that reads a Git diff sees all
+of it — including AI coding agents like Claude Code or Codex that have no
+PR-review feature of their own. Point one at the staged diff and it can review or
+fix the whole PR in place.
+
+And for the small stuff — a rename, a typo, a clearer variable name — fixing it
+yourself is faster and less bureaucratic than leaving a comment and waiting for a
+round-trip, especially when you are already looking at the PR in your editor.
+Because your edits are extracted automatically, the fix costs about the same as
+the comment would have. Or hand the staged diff to an agent and have it make the
+change for you.
+
+If you mostly *comment*, your IDE's native PR panel is enough. If you review by
+editing and running the code — in any editor or agent — this is the gap it fills.
+
+## Quick start
+
+```sh
+# 1. Install (needs Node.js; see Installation for Homebrew and a no-Node option)
+npm install -g git-review-workflow
+
+# 2. Tell it where PRs are integrated, once per repo
+git config reviewworkflow.base develop
+
+# 3. Stage a PR branch as a single diff, then open the repo in your IDE
+git review start feature/login
+# ...read and edit the staged diff in your editor, run tests...
+git review finish              # extract your edits onto review-fixes/feature/login
+```
+
+Prefer Homebrew, a native Windows (PowerShell) installer, or an install that
+does not need Node? See [Installation](#installation). For the full flow —
+re-reviewing updates, walking a PR commit by commit, cleanup — see
+[Typical workflow](#typical-workflow).
+
+## Installation
+
+These commands plug into `git` as a single subcommand — you run them as
+`git review start`, `git review finish`, and so on. Pick whichever method matches
+your setup. The package-manager options are the easiest and **set up your `PATH`
+for you**.
+
+### npm (recommended)
+
+If you have [Node.js](https://nodejs.org), this is the one-command install. It
+puts `git review` on your `PATH` for you and works on Linux, macOS and Windows
+(on Windows the commands still run under Git Bash):
+
+```sh
+npm install -g git-review-workflow
+```
+
+Update with `npm install -g git-review-workflow@latest`; uninstall with
+`npm uninstall -g git-review-workflow`. Tab completion is set up the same way as
+the other non-Homebrew installs — see the note below.
+
+### Homebrew (macOS / Linux)
+
+```sh
+brew tap EzeVillo/git-review-workflow https://github.com/EzeVillo/git-review-workflow
+brew install EzeVillo/git-review-workflow/git-review-workflow
+```
+
+Tab completion is configured automatically. To update to the latest release:
+`brew upgrade git-review-workflow`.
+
+### Windows (PowerShell)
+
+You still need [Git for Windows](https://gitforwindows.org), which provides the
+shell these commands run in. Open PowerShell and run:
+
+```powershell
+irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.ps1 | iex
+```
+
+This installs the command into `~\.local\bin` and adds that folder to your user
+`PATH` automatically. Open a new terminal after it finishes. Re-run to update; to
+uninstall:
+
+```powershell
+irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.ps1 | iex
+```
+
+(If you have Node, `npm install -g git-review-workflow` works on Windows too —
+the commands still run under Git Bash either way.)
+
+### One-line install (Linux, macOS, WSL, Git Bash)
+
+No package manager? This downloads the command and installs it into
+`~/.local/bin` — you don't need to clone the project first:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.sh | sh
+```
+
+Re-run to update (always installs the latest release). To uninstall (pass the
+same `PREFIX` if you overrode it):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.sh | sh
+```
+
+<details>
+<summary>From a downloaded copy</summary>
+
+If you cloned or downloaded the project, open its folder in a terminal and run:
+
+```sh
+./install.sh
+```
+
+This installs the `git review` dispatcher into `~/.local/bin` (change the
+location with `PREFIX=/usr/local/bin ./install.sh`). The verbs travel beside it
+as private helpers, not as separate commands on your `PATH`. Undo it any time
+with `./uninstall.sh`. To update, just `git pull` inside the repo — the symlink
+picks up changes automatically.
+</details>
+
+<details>
+<summary>"command not found" — adding <code>~/.local/bin</code> to your PATH</summary>
+
+Your `PATH` is the list of folders your terminal searches when you type a
+command. Homebrew, npm and the PowerShell installer add their folder for you. The
+one-line and manual installs use `~/.local/bin`, which is already on the `PATH`
+on most systems. If it isn't, the installer prints a note — add it **once** by
+pasting one line into your shell's config file:
+
+| If your terminal uses…            | Add this line to the file…       | The line to add                        |
+|-----------------------------------|----------------------------------|----------------------------------------|
+| **bash**                          | `~/.bashrc`                      | `export PATH="$HOME/.local/bin:$PATH"` |
+| **zsh** (default on recent macOS) | `~/.zshrc`                       | `export PATH="$HOME/.local/bin:$PATH"` |
+| **fish**                          | *(no file — just run this once)* | `fish_add_path ~/.local/bin`           |
+
+Not sure which one you use? Run `echo $0`. After editing the file, **open a new
+terminal** (or `source` the file). Run `git review -h` to confirm.
+</details>
+
+<details>
+<summary>Tab completion (manual installs)</summary>
+
+Homebrew sets this up for you. Otherwise, tell your shell to load the matching
+file on start. Replace `/path/to/git-review-workflow` with where you downloaded
+the project.
+
+```sh
+# bash — in ~/.bashrc
+source /path/to/git-review-workflow/completions/git-review-workflow.bash
+
+# zsh — in ~/.zshrc
+source /path/to/git-review-workflow/completions/git-review-workflow.zsh
+
+# fish — copy into fish's completions folder (no config line needed)
+cp /path/to/git-review-workflow/completions/git-review-workflow.fish \
+    ~/.config/fish/completions/
+```
+
+Then open a new terminal. Typing `git review ` and pressing **Tab** now offers
+the verbs; `git review start ` offers your branch names.
+</details>
+
+<details>
+<summary>Git Bash on Windows — SSL error during install?</summary>
+
+If you see `schannel: next InitializeSecurityContext failed` or a
+`revocation check` message, your Git for Windows is using the Windows SSL
+backend. Fix it once, then re-run the installer:
+
+```sh
+git config --global http.sslBackend openssl
+```
+
+</details>
+
+## Commands
+
+> **How to read the syntax:** `<x>` is **required**, `[x]` is **optional**, and
+> `a | b` means **pick one, not both**.
+
+Every command is a verb under `git review`. Run `git review -h` for the list, or
+`git review <verb> -h` for one verb's details.
+
+| Command                                                                                                  | What it does                                                                                                                                                                |
+|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `git review [-h \| --version]`                                                                           | List all verbs or print the installed version.                                                                                                                              |
+| `git review start [<branch>] [<base> \| --base <base> \| --delta \| --from <commit>] [--step] [--local]` | Fetch `origin`, then stage the PR diff on a new `review/<branch>` branch (omit `<branch>` to review the current branch; `--local` reviews local branches without fetching). |
+| `git review compare <a> <b> [--step]`                                                                    | Stage the diff between two commit-ish (tags, commits, branches) read-only, to read or walk it. `git review finish` refuses — there is nothing to write back.                |
+| `git review next` / `git review prev`                                                                    | Move a `--step` review to the next / previous commit.                                                                                                                       |
+| `git review status`                                                                                      | Show the state of the review on the current branch.                                                                                                                         |
+| `git review list`                                                                                        | List every review in progress and every saved one (current branch marked `*`).                                                                                              |
+| `git review save`                                                                                        | Pause the current review as `review-saved/<branch>` and return to where you started.                                                                                        |
+| `git review continue [branch]`                                                                           | Resume a review saved with `git review save`.                                                                                                                               |
+| `git review finish [--onto-source] [--resume \| --abort [--force]]`                                      | From a `review/*` branch, extract your edits onto `review-fixes/<branch>` (or the PR branch); `--abort` undoes the last finish.                                             |
+| `git review preview [--stat]`                                                                            | Show the edits you have made so far — the diff `finish` would extract — without committing or switching branch.                                                             |
+| `git review abort`                                                                                       | Cancel the current review and return to where you started.                                                                                                                  |
+| `git review clean [branch]`                                                                              | Delete the `review/*` and `review-fixes/*` branches for `<branch>`, or all of them.                                                                                         |
+| `git review forget --delta (<branch> \| --all \| --stale [--dry-run])`                                   | Discard the `--delta` marker for one branch, all of them, or only stale ones.                                                                                               |
+| `git review forget --saved (<branch> \| --all) [--dry-run]`                                              | Discard a review saved with `git review save`.                                                                                                                              |
+
+### `git review start`
+
+Has two independent axes — **range** (where the review starts) and **layout**
+(`--step` or not), which compose freely.
+
+- `<branch>` — the branch to review. **Omit it to review the branch you currently
+  have checked out** — git's own default (like `push`, `status`, `log`). It only
+  resolves the name; the mode is still chosen by flags, so pair the omitted branch
+  with `--local` to review your local work. Without `--local` it reviews
+  `origin/<branch>` — if that differs from your checked-out branch you get a note,
+  since you would be reviewing a different snapshot than you have. With no branch,
+  fails on a detached HEAD or while on a `review/*` branch.
+- `base` — commit-ish to diff against: a branch, a **tag**, or a commit. Taken
+  from `reviewworkflow.base` (see below); a positional argument overrides it.
+  **Required for a full review** — there is no built-in default, so a full review
+  with no base set fails and asks you to configure one. Not used with `--delta` or
+  `--from`, which carry their own starting point — passing an explicit base
+  alongside them is an error (a base from config is simply ignored).
+- `--base <base>` — the base to diff against, as a flag. Use it to pass a base
+  while letting `<branch>` default to the current branch — e.g.
+  `git review start --base develop` reviews the branch you are on against
+  `develop` (the lone positional is always taken as `<branch>`, so the flag is how
+  you reach the base without naming the branch). Cannot be combined with a
+  positional base.
+- `--delta` — review only the commits added **since your last review** of this
+  branch, instead of the whole PR. Perfect for re-reviewing an updated PR. The
+  recorded tip survives `git review clean`, so this works even after you deleted
+  the review branches; discard it explicitly with `git review forget --delta`.
+- `--from <commit>` — review only the commits **after `<commit>`**. Handy when
+  there is no recorded review to delta from, or to pick an exact starting point.
+  Mutually exclusive with `--delta`.
+- `--step` — review the range **one commit at a time** (combine with `--delta`
+  or `--from` to walk just those commits). You start on the first commit after
+  the merge-base; the command prints its author message. Edit files, then run
+  `git review next` to bank your edits and move to the next commit with a clean
+  tree. When the commits run out, run `git review finish` and all your banked
+  edits are replayed onto the PR tip — exactly as in a whole-PR review.
+- `--local` — review your **local** branches directly, without fetching. The
+  review is built from your local `<branch>` and diffed against your local base,
+  so it works offline and lets you review your own work before pushing. It keeps
+  its own `--delta` marker, separate from the remote one, so local and remote
+  reviews of the same branch name never overwrite each other's progress.
+- Always updates from `origin` first and **fails** if it cannot (unless
+  `--local`). The review is built from `origin/<branch>`, never a stale local
+  copy. If a local branch of the same name points somewhere else, it prints a
+  note: the review reflects the remote, not your checkout, and a later
+  `git review finish --onto-source` would refuse until your local branch matches.
+- Refuses to run if you have local changes — start from a clean branch.
+- **Merges of the base branch are excluded.** If the author merged the base
+  (e.g. `develop`) into the PR, that merged-in content is left out of the review
+  in every mode, so you only see the author's own changes.
+- `--` ends option parsing, the usual git convention: everything after it is
+  treated as a positional argument, so a branch whose name starts with `-` can
+  still be reviewed (e.g. `git review start -- --weird develop`).
+
+### `git review compare`
+
+Stage the diff between two commit-ish — two tags, two commits, two branches — as
+one read-only review, so you can read it inline or walk it commit by commit with
+the same UX as a real review, without `git diff | less`.
+
+```sh
+git review compare v1.0 v2.0          # stage the diff between two releases
+git review compare v1.0 v2.0 --step   # ...and walk it commit by commit
+```
+
+- It diffs `<a>..<b>`: `<a>` is the lower bound (where the review starts), `<b>`
+  the tip whose content fills the working tree. Both are resolved to commits, so
+  tags and raw SHAs work, not only branch names.
+- It is **read-only by design**. The whole edit→finish half of the workflow needs
+  a writable branch to write back to, and a tag or a commit is not one — so
+  `git review finish` on a compare refuses explicitly ("this review is read-only,
+  there is nothing to write back"). Use `git review abort` to end it.
+- `--step` walks it one commit at a time, exactly like `git review start --step`,
+  with `git review next` / `git review prev`.
+
+### `git review next` / `git review prev`
+
+Move a `--step` review forward or backward. Each move banks the current commit's
+edits and restores any edits you had banked on the commit you move to, so you can
+walk back and forth without losing work.
+
+### `git review status`
+
+Shows the current review: source PR, mode, and — in `--step` mode — which commit
+you are on (`[k/N]`) and which steps have banked edits.
+
+### `git review list`
+
+Shows *every* `review/*` branch in progress at once (with its source PR, mode and
+step position). Reviews paused with `git review save` are listed too, under
+`saved`. The branch you are currently on is marked with a `*`.
+
+### `git review save` / `git review continue`
+
+`git review save` lets you put a review aside and pick it up later. It turns the
+current `review/<branch>` into `review-saved/<branch>` and returns you to the
+branch you started from, carrying everything needed to resume exactly where you
+left off:
+
+- In whole-PR mode, the staged PR diff and your uncommitted edits.
+- In `--step` mode, the commit you are on, its edits, and every edit you have
+  banked on the other commits. The banked-edit refs are moved out of
+  `refs/review-edits/` (which `git review clean` prunes) into
+  `refs/review-saved-edits/`, so a `git review clean` never touches a saved review.
+
+`git review continue` turns `review-saved/<branch>` back into the active
+`review/<branch>` and restores that exact state — in `--step` mode it drops you
+back on the same commit, with `git review next` / `git review prev` working as
+before. With no argument it resumes the only saved review, or lists them if there
+is more than one; name a branch to pick a specific one.
+
+Starting a fresh `git review start` on a branch that already has a saved review
+is refused, so you do not silently lose the paused one — resume it or discard it
+with `git review forget --saved` first.
+
+### `git review finish`
+
+- Default — create `review-fixes/<branch>` on top of the PR tip with your edits
+  staged, so you can review and commit them yourself.
+- `--onto-source` — stage your edits on the PR branch itself instead, so you can
+  review and commit them yourself there.
+- Either way the result stays local — review it and push it yourself when ready.
+- `--resume` — in `--step` mode, if banked edits overlap the PR tip, the replay
+  leaves conflict markers and stops. Resolve them in the working tree, then run
+  `git review finish --resume` (with the same flags) to continue.
+- `--abort` — undo the last finish and drop you back on `review/<branch>` exactly
+  where you were editing, the same way `git merge --abort` backs out a merge. It
+  refuses if you have changed the finish branch since, so you do not lose work;
+  add `--force` to discard those changes and abort anyway.
+- Refuses on a read-only `git review compare` — there is no writable branch to
+  write your edits back to.
+
+### `git review preview`
+
+Shows the edits you have made so far — the same diff `git review finish` would
+extract, your review edits on top of the PR tip — but it **never commits, never
+switches branch and never touches your working tree or index**, so you go straight
+back to editing where you left off. Think of it as "what would `finish` give me
+right now?".
+
+- `--stat` — show a diffstat summary instead of the full diff.
+- In `--step` mode it replays the current commit's edits plus every banked edit
+  onto the tip, exactly like `finish`. An edit that genuinely conflicts with the
+  tip is the one case that differs: a read-only preview cannot leave you conflict
+  markers, so it omits that edit and prints a note pointing you at `finish`.
+
+### `git review abort`
+
+Cancels the current review in one step: it returns you to the branch you started
+from, then deletes the `review/<branch>` branch and its banked edits. Because the
+review was cancelled (not completed), it rolls the `--delta` marker back to your
+last actual review, so a later `--delta` does not skip commits you never
+reviewed.
+
+### `git review clean`
+
+- With no `<branch>`, deletes every `review/*` and `review-fixes/*` branch.
+- Never deletes the branch you are currently on.
+- Also drops any banked commit-by-commit edit refs, even when no review branches
+  remain.
+- Leaves the `--delta` marker untouched — discard it with `git review forget --delta`.
+- Leaves saved reviews (`review-saved/*`) untouched — discard one with
+  `git review forget --saved`.
+
+### `git review forget --delta`
+
+Discards the recorded last-reviewed tip that `--delta` relies on. The marker is
+kept deliberately so `--delta` survives `git review clean`; this is how you clear
+it.
+
+- `<branch>` — forget the marker(s) for one source branch, both the remote one
+  and the `--local` one if present.
+- `--all` — forget every recorded marker (leaves `reviewworkflow.base` alone).
+- `--stale` — fetch and prune `origin`, then forget only the markers whose branch
+  no longer exists: remote markers whose `origin/<branch>` is gone (e.g. PRs that
+  were merged and deleted), and `--local` markers whose local `<branch>` is gone.
+  Aborts without removing anything if the fetch fails.
+- `--dry-run` — with `--stale`, list what would be forgotten without doing it.
+  Rejected with the other modes, where the target is already explicit.
+
+### `git review forget --saved`
+
+Discards a review put aside with `git review save`: deletes
+`review-saved/<branch>`, its banked edits and its metadata. Because a saved review
+was paused (not completed), it also rolls the `--delta` marker back to your last
+actual review, the same way `git review abort` does.
+
+- `<branch>` — discard the saved review for one source branch.
+- `--all` — discard every saved review.
+- `--dry-run` — list what would be discarded without discarding it.
+
+## Configuring the base branch
+
+The base branch is where PRs are integrated (`develop`, `main`, `master`, …) and
+varies per team, so there is no default — set it once per repository:
+
+```sh
+git config reviewworkflow.base develop
+```
+
+Resolution order: positional `base` argument (or `--base <base>`) →
+`reviewworkflow.base`. If neither is set, a full review fails and asks you to
+configure one. The base is any commit-ish — a branch, a tag (`v1.0`) or a
+commit — not only a branch name.
+
+## Configure the remote
+
+By default the commands fetch and push against `origin`. If you review a
+repository you do not own (an `upstream`, with your `origin` as a fork, say),
+point the workflow at that remote:
+
+```sh
+git config reviewworkflow.remote upstream
+```
+
+It affects `git review start` and `git review forget --delta --stale`. A
+`--local` review ignores the remote entirely.
+
+### Per-repository by design
+
+Both `reviewworkflow.base` and `reviewworkflow.remote` are plain `git config`
+keys, so they are stored **per repository** (in each repo's `.git/config`). You
+don't manage profiles or a shared config file — every repository you work in
+keeps its own base and remote independently, and they never leak into one
+another:
+
+```sh
+# repo A: PRs land on main, fetched from origin (the default)
+cd ~/project-a && git config reviewworkflow.base main
+
+# repo B: PRs land on develop, reviewed from an upstream you don't own
+cd ~/project-b
+git config reviewworkflow.base develop
+git config reviewworkflow.remote upstream
+```
+
+The same applies to the `--delta` markers — they live in each repo's config too.
+If you want a fallback that applies to *all* your repos, set it globally
+(`git config --global reviewworkflow.base main`); a per-repo value overrides it,
+and a positional `base` argument overrides both.
+
+## Typical workflow
+
+```sh
+git config reviewworkflow.base develop      # once per repo
+
+git review start feature/login              # stage the whole PR
+# ...open the repo in your IDE, read the staged diff, edit inline, run tests...
+git review finish                            # extract fixes to review-fixes/feature/login
+git diff --cached && git commit -m "address review comments"
+git review clean feature/login              # tidy up
+
+# Re-review after the author pushes more commits:
+git review start feature/login --delta       # only the new commits
+git review start feature/login --delta --step  # ...and walk them one by one
+
+# Or walk the PR commit by commit from the start:
+git review start feature/login --step        # start on the first commit
+# ...edit, then...
+git review next                              # bank edits, move to the next commit
+git review next                              # ...until "no more commits"
+git review finish                            # replay all your edits onto the tip
+
+# Pick an explicit starting commit:
+git review start feature/login --from a1b2c3d
+
+# Review the branch you are already on (omit the name):
+git switch feature/login && git review start         # vs the configured base
+git review start --base develop                       # ...or against an explicit base
+
+# Compare against a tag instead of a branch:
+git review start feature/login v1.0
+
+# Compare two releases read-only:
+git review compare v1.0 v2.0
+
+# Review your own local branch before pushing, offline:
+git review start feature/login --local
+```
+
+## Requirements
+
+- Git 2.23+ (uses `git switch`). Git 2.38+ is recommended: excluding base
+  content that was merged into the PR uses `git merge-tree --write-tree`, and on
+  older git that one step is skipped (the merged base content would then show in
+  `--delta`/`--from`).
+- A remote named `origin` (or whatever you set with `reviewworkflow.remote`).
+- A POSIX shell. On Linux and macOS this is the default. On Windows the commands
+  run under Git Bash or WSL, not in `cmd.exe` or PowerShell.
+
+## Contributing
+
+Bug reports, fixes and ideas are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for how to run the tests and the release process.
+
+## License
+
+[MIT](LICENSE) © EzeVillo

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/bin/git-review

@@ -0,0 +1,104 @@
+#!/usr/bin/env sh
+#
+# git-review — entry-point dispatcher for the `git review <verb>` workflow.
+#
+# git discovers this as the `review` subcommand once bin/ is on PATH, so
+# `git review <verb> [args]` runs us with <verb> in $1. We route <verb> to its
+# implementation in the private git-review-verbs/ directory — files that are NOT
+# on PATH and not named git-*, so git cannot discover them as `git <verb>`; the
+# dispatcher is the only entry point. `-h`/no args lists the commands;
+# `--version` prints the version.
+#
+set -eu
+
+prog="git review"
+VERSION="0.1.0"
+
+usage() {
+	cat <<EOF
+git review workflow — review a pull request branch locally
+
+usage: $prog <command> [<args>]
+       $prog (-h | --version)
+
+Commands:
+  git review start [<branch>] [<base> | --base <base> | --delta | --from <commit>] [--step] [--local]
+                     stage a PR diff on a new review/<branch> branch
+                     (omit <branch> to review the branch you are on)
+  git review compare <a> <b> [--step]
+                     stage the diff between two commit-ish, read-only (finish refuses)
+  git review next    advance a commit-by-commit review to the next commit
+  git review prev    step a commit-by-commit review back to the previous commit
+  git review status  show the state of the review on the current branch
+  git review list    list every review/* branch in progress
+  git review preview [--stat]
+                     show your edits so far without committing or switching
+  git review finish [--onto-source] [--resume | --abort]
+                     extract your edits onto review-fixes/<branch>
+                     (--abort undoes it and returns you to editing)
+  git review save    pause the current review and return to where you started
+  git review continue [<branch>]
+                     resume a review paused with git review save
+  git review abort   cancel the current review and return to where you started
+  git review clean [<branch>]
+                     delete review/* and review-fixes/* branches (all if no <branch>)
+  git review forget (--delta | --saved) ...
+                     discard a review's persistent state (delta markers or a saved review)
+
+Run '$prog <command> -h' for details on each command (git reserves
+'$prog <command> --help' for man pages, which this workflow does not install).
+EOF
+}
+
+case "${1:-}" in
+-h | --h | "")
+	usage
+	exit 0
+	;;
+-V | --version)
+	echo "$VERSION"
+	exit 0
+	;;
+esac
+
+verb="$1"
+
+# Reject anything that could escape the verbs directory: a path separator, or a
+# dot-path like '..' / '.foo'. (A leading '-' was already handled above.) This
+# keeps `git review ../some-binary` from reaching a sibling binary.
+case "$verb" in
+*/* | .*)
+	echo "error: '$verb' is not a git review command. See '$prog -h'." >&2
+	exit 1
+	;;
+esac
+
+# Resolve our own real location — $0 may be a symlink (install.sh / Homebrew put
+# the dispatcher onto PATH via a symlink) or a bare name (PATH lookup) — so the
+# verbs directory and the sourced lib are found beside the real file, not beside
+# the symlink. Mirrors the resolution the verbs themselves use.
+self="$0"
+case "$self" in
+*/*) ;;
+*) self="$(command -v -- "$self" 2>/dev/null || printf '%s\n' "$self")" ;;
+esac
+while [ -L "$self" ]; do
+	link="$(readlink "$self")"
+	case "$link" in
+	/*) self="$link" ;;
+	*) self="$(dirname "$self")/$link" ;;
+	esac
+done
+# shellcheck disable=SC1007  # CDPATH= empties CDPATH for this cd, not an assignment
+libexec="$(CDPATH= cd -- "$(dirname -- "$self")" && pwd)"
+
+target="$libexec/git-review-verbs/$verb"
+if [ ! -x "$target" ]; then
+	echo "error: '$verb' is not a git review command. See '$prog -h'." >&2
+	exit 1
+fi
+
+# Verbs that use shared helpers source "${GIT_REVIEW_LIBEXEC:?}/git-review-lib.sh".
+export GIT_REVIEW_LIBEXEC="$libexec"
+shift
+exec "$target" "$@"