git-reviewer 2.12.0 → 2.13.1

package/README.md

@@ -3,14 +3,14 @@
 [![CI](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/dheerajjha/reviewer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-335-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-359-brightgreen.svg)](test/)
 [![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen.svg)](package.json)
 
 When an agent writes the code, reading it becomes the bottleneck — and the tool
 built for reading a diff, the pull request, wants a branch, a remote and a push
 you are not ready to make yet.
 
-`reviewer` gives you the pull-request view of your working directory instead:
+reviewer gives you the pull-request view of your working directory instead:
 inline comments with threaded follow-ups, each attached to the exact line you
 mean, with no branch, no remote, no push and no account. Then it hands the
 marked-up review back to the agent to act on.
@@ -19,15 +19,19 @@ marked-up review back to the agent to act on.
 npm install -g git-reviewer
 
 cd ~/your-project
-reviewer | claude -p "Apply this review."
+git reviewer | claude -p "Apply this review."
 ```
 
-That is the whole loop. `reviewer` opens the review in your browser; when you
+Installed as `git-reviewer`, it runs as `git reviewer` — git treats any
+`git-<name>` command on your PATH as a subcommand, so the name you install is
+the name you type. `reviewer` is the same program under a shorter name.
+
+That is the whole loop. `git reviewer` opens the review in your browser; when you
 press **Submit Review**, the review is written to stdout and the command
 exits — so whatever is on the other end of the pipe receives it and starts
 work. Nothing to copy, no second command, no file to go and find.
 
-Without a pipe, `reviewer` is just a review tool: it tells you where the
+Without a pipe, `git reviewer` is just a review tool: it tells you where the
 review was saved and keeps serving, because you may have more to read.
 Everything it says to you goes to stderr either way, so only the review is
 ever on stdout.
@@ -46,8 +50,8 @@ When the review and the hand-off happen at different times, the two-step form
 still works and is the one to reach for:
 
 ```bash
-reviewer                                            # read the diff, comment on it
-reviewer export . --format prompt | claude -p "Apply this review."
+git reviewer                                        # read the diff, comment on it
+git reviewer export . --format prompt | claude -p "Apply this review."
 ```
 
 Comments persist between sessions and survive the code moving underneath them —
@@ -64,8 +68,8 @@ comment they answer, and everything is saved as you type.
 ## Usage
 
 ```
-reviewer [repository] [options]
-reviewer export [repository] [--format json|prompt]
+git reviewer [repository] [options]
+git reviewer export [repository] [--format json|prompt]
 
   repository        A git repository, or any directory inside one
                     (default: the current directory)
@@ -79,10 +83,10 @@ reviewer export [repository] [--format json|prompt]
 ```
 
 ```bash
-reviewer                    # review the repository you are standing in
-reviewer ~/work/api         # review another one
-reviewer . --no-open        # print the URL, open it yourself
-reviewer . --port 8080      # somewhere other than 4500
+git reviewer                # review the repository you are standing in
+git reviewer ~/work/api     # review another one
+git reviewer . --no-open    # print the URL, open it yourself
+git reviewer . --port 8080  # somewhere other than 4500
 ```
 
 Two at once is fine — the second one finds its own port.
@@ -110,19 +114,25 @@ To install it as a command rather than running it through `npx`:
 
 ```bash
 npm install -g git-reviewer
-reviewer .
+git reviewer .
 ```
 
-The package is `git-reviewer` because `reviewer` and `code-reviewer` were both
-already taken on npm. It installs the command under both names, so whichever
-one you reach for is the one that is there:
+The package is called `git-reviewer` because `reviewer` was already taken on
+npm — and it turns out to be the right name. Git runs any `git-<name>` on your
+PATH as a subcommand, so the name you install is the name you type. It also
+installs `reviewer`, the same program under a shorter name, for anyone who
+prefers it:
 
 ```bash
-reviewer                    # the command
-git-reviewer                # the package name, if that is what you typed
-git reviewer                # git dispatches to it like any other subcommand
+git reviewer                # the name it is installed as
+reviewer                    # the same program, shorter
 ```
 
+Whichever you use is the name it uses back: help and hints are printed in
+terms of the command you actually ran, so they can be pasted as they are.
+Under git, `git reviewer --help` opens the manual page — git reads `--help` on
+any subcommand that way — and `git reviewer -h` prints the usage.
+
 From a clone, if you would rather not install anything:
 
 ```bash
@@ -132,7 +142,7 @@ cd reviewer && npm install && npm link
 
 ## What it shows you
 
-`reviewer` picks what to review based on the state of the repository, so there
+reviewer picks what to review based on the state of the repository, so there
 is nothing to configure:
 
 | Repository state | What you review |
@@ -141,7 +151,7 @@ is nothing to configure:
 | Working directory clean | The last commit against its parent |
 | No commits yet | Every tracked and untracked file, as wholly new |
 
-### Comparing branches
+### Comparing branches and commits
 
 Those defaults cover the common case with nothing to set up, but a branch you
 have worked on for a day is several commits deep, and the default scope only
@@ -178,6 +188,29 @@ commits that add a file and then delete it produce no diff between the ends —
 correctly — and that reads as *"2 commits undo each other"*, not as *"nothing
 to review"*.
 
+#### Reviewing commit by commit
+
+Whenever the review is made of commits, the sidebar lists them above the files:
+the commits a comparison is made of, oldest first, or the branch's recent
+history when you are looking at its last commit.
+
+- **Click** a commit to review it on its own, with its full message above the
+  diff — often the only place the author says *why*.
+- **Shift-click** a second to review the run between them, both ends included.
+  From the last commit, shift-clicking three rows down is "the last three
+  commits"; inside a comparison, it skips the ones you have already read.
+- **`[`** and **`]`** step one commit older or newer, and **All commits** goes
+  back to the whole comparison.
+
+That is the same gesture a pull request's commit picker uses, for the same
+reasons: a large change reads better in the order it was written, and one
+commit of renames is easier to skip than to read around.
+
+A run has to be one unbroken line of history. To diff two points that are not
+— a commit on one branch against another branch — use **Compare**; its pickers
+list recent commits of whichever branch you are comparing, right after the
+local branches.
+
 Comments are kept when you switch between comparisons. One on a file that is
 not in the current view stays in the comments list, marked **Not in this
 view**, and is back in place whenever you open a view that includes the file.
@@ -267,8 +300,8 @@ export` prints the review you saved — no server, no submit step — either as
 JSON or as instructions ready to pipe:
 
 ```bash
-reviewer export . --format prompt | claude -p "Apply this review to the repo."
-reviewer export . | jq '.comments[].file'
+git reviewer export . --format prompt | claude -p "Apply this review to the repo."
+git reviewer export . | jq '.comments[].file'
 ```
 
 Every comment carries an `anchor`: the exact text of the line it was left on.
@@ -305,8 +338,9 @@ The UI is a client of this; nothing is hidden from you.
 | Endpoint | Purpose |
 |---|---|
 | `GET /api/health` | Liveness, plus the number of open sessions |
-| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files. Pass `base` (and optionally `head`) to compare two refs from their merge base |
-| `GET /api/refs/:repoId` | Branches, remote branches, tags and recent commits, for choosing what to compare |
+| `POST /api/load-repo` | Open a repository; returns a `repoId` and the changed files. Pass `base` (and optionally `head`) to compare two refs from their merge base, or `commits: { from, to }` to review one commit or an unbroken run of them, both ends included |
+| `GET /api/refs/:repoId` | Branches, remote branches, tags and recent commits, for choosing what to compare. `?head=` makes the commits those of another branch |
+| `GET /api/log/:repoId` | Commits with their messages: `?base=&head=` for a comparison's commits, oldest first, or `?head=` alone for recent history, newest first |
 | `GET /api/commits/:repoId` | Recent commits only; kept for callers of 2.11 |
 | `GET /api/alive` | Held open by the page; when the last one closes, a terminal run stops |
 | `GET /api/file/:repoId/:path` | The file's diff, as structured lines |
@@ -338,7 +372,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 335 tests
+npm test              # 359 tests
 npm run test:watch
 npm run test:coverage
 ```

package/bin/reviewer.js

@@ -4,7 +4,7 @@
 const fs = require('fs').promises;
 const path = require('path');
 
-const { parseArgs, buildUrl, UsageError, USAGE } = require('../lib/cli');
+const { parseArgs, buildUrl, UsageError, usage, invokedAs } = require('../lib/cli');
 const { homeRelative } = require('../lib/paths');
 const { openInBrowser } = require('../lib/browser');
 const { formatPrompt } = require('../lib/agent');
@@ -19,6 +19,10 @@ const {
 const { startServer, DEFAULT_PORT, DEFAULT_HOST } = require('../server');
 const { version } = require('../package.json');
 
+// What to call this command when it talks about itself: whatever the person
+// typed, so a hint can be pasted back as-is. See invokedAs in lib/cli.js.
+const NAME = invokedAs(process.env, process.argv[1]);
+
 /**
  * The `reviewer` command: start the local server and open it in a browser.
  */
@@ -138,7 +142,7 @@ async function main() {
   }
 
   if (options.help) {
-    process.stdout.write(USAGE);
+    process.stdout.write(usage(NAME));
     return;
   }
 
@@ -212,7 +216,7 @@ async function main() {
       note(`\n  Review saved    ${homeRelative(reviewPath)}`);
       note(`  ${count}\n`);
       note('  Hand it to an agent with:');
-      note(`    reviewer export ${repoPath ? homeRelative(repoPath) : '.'} --format prompt | claude -p "Apply this review."\n`);
+      note(`    ${NAME} export ${repoPath ? homeRelative(repoPath) : '.'} --format prompt | claude -p "Apply this review."\n`);
       return;
     }
 
@@ -265,7 +269,7 @@ async function main() {
 main().catch(error => {
   if (error instanceof UsageError) {
     console.error(`error: ${error.message}\n`);
-    process.stderr.write(USAGE);
+    process.stderr.write(usage(NAME));
     process.exit(2);
   }
 

package/lib/agent.js

@@ -205,6 +205,17 @@ function describeScope({ repository, mode, range }) {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  if (mode === 'range' && range?.kind === 'commits') {
+    // Commits themselves, picked from a list. Both ends are *in* the review,
+    // which is the difference from a comparison and worth saying: an agent
+    // told "between A and B" would reasonably assume A's own changes were
+    // outside it.
+    if (range.first === range.last) {
+      return `Reviewed: commit ${range.last}${range.subject ? ` ("${range.subject}")` : ''} on its own, against its parent.`;
+    }
+    return `Reviewed: ${range.commits} commits, ${range.first} through ${range.last} inclusive, as a single combined diff.`;
+  }
+
   if (mode === 'range' && range) {
     // Both ends, and the count, because the count is the only thing that
     // distinguishes "one commit of work" from "nine" once the diff has been

package/lib/cli.js

@@ -9,19 +9,22 @@ const path = require('path');
  * without starting a server or opening a browser.
  */
 
-const USAGE = `reviewer — review local git changes in your browser
+function usage(name = 'git reviewer') {
+  return `${name} — review local git changes in your browser
 
 Usage:
-  reviewer [repository] [options]
-  reviewer export [repository] [--format json|prompt] [--file <path>]
+  ${name} [repository] [options]
+  ${name} export [repository] [--format json|prompt] [--file <path>]
 
-Installed under both names: reviewer and git-reviewer. The second name also
-makes it reachable as a git subcommand: git reviewer
+One program, two names. git reviewer is the name the package is installed as
+-- git runs any git-<name> on your PATH as a subcommand -- and reviewer is the
+short form. Under git, use -h for this text: git reviewer --help opens the
+manual page instead.
 
 Handing a review to an agent:
-  reviewer | claude -p "Apply this review."
+  ${name} | claude -p "Apply this review."
 
-  With something reading its output, reviewer writes the finished review there
+  With something reading its output, it writes the finished review there
   the moment you submit it in the browser, and exits. On a terminal there is
   nothing waiting, so it says where the review was saved and keeps serving.
   Everything it tells you goes to stderr either way, so only the review is
@@ -46,15 +49,22 @@ Options:
   -v, --version     Show the version
 
 Examples:
-  reviewer                 review the repository you are standing in
-  reviewer | claude -p "Apply this review."
-                           review it, then hand it straight to an agent
-  reviewer ~/work/api      review another repository
-  reviewer . --no-open     print the URL, open it yourself
-  reviewer export .        print the review as JSON
-  reviewer export . --file src/auth.js
-  reviewer export . --format prompt | claude -p "apply this review"
+  ${name}
+      review the repository you are standing in
+  ${name} | claude -p "Apply this review."
+      review it, then hand it straight to an agent
+  ${name} ~/work/api
+      review another repository
+  ${name} . --no-open
+      print the URL, open it yourself
+  ${name} export .
+      print the review as JSON
+  ${name} export . --file src/auth.js
+      only the comments on one file
+  ${name} export . --format prompt | claude -p "apply this review"
+      hand over a review written earlier
 `;
+}
 
 /** Formats `reviewer export` can print. */
 const FORMATS = ['json', 'prompt'];
@@ -256,4 +266,26 @@ function buildUrl(origin, repoPath) {
   return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`;
 }
 
-module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS };
+/**
+ * The name to show in help and hints: the one the person actually typed.
+ *
+ * The package is git-reviewer and installs two commands, reviewer and
+ * git-reviewer. Showing one while someone typed the other was the confusing
+ * part, so this answers with theirs. Git sets GIT_EXEC_PATH when it runs a
+ * subcommand, which is how `git reviewer` is told apart from `git-reviewer`
+ * typed directly; npx sets npm_command=exec, and for an npx run neither bare
+ * name is on the PATH, so the hint has to say npx too.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string|undefined} argv1 process.argv[1]
+ */
+function invokedAs(env, argv1) {
+  if (env.npm_command === 'exec') return 'npx git-reviewer';
+  const bin = String(argv1 || '').split(/[\\/]/).pop().replace(/\.js$/, '');
+  if (bin === 'git-reviewer') return env.GIT_EXEC_PATH ? 'git reviewer' : 'git-reviewer';
+  return 'reviewer';
+}
+
+const USAGE = usage();
+
+module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, usage, invokedAs };

package/man/git-reviewer.1

@@ -0,0 +1,80 @@
+.\" Manual page for git-reviewer. git opens this for `git reviewer --help`,
+.\" because it reads --help on any subcommand as a request for its man page.
+.TH GIT-REVIEWER 1 "2026-09-25" "git-reviewer" "User Commands"
+.SH NAME
+git-reviewer, reviewer \- review local git changes in your browser, and hand the review to a coding agent
+.SH SYNOPSIS
+.B git reviewer
+.RI [ repository ]
+.RB [ \-p
+.IR port ]
+.RB [ \-\-no\-open ]
+.br
+.B git reviewer export
+.RI [ repository ]
+.RB [ \-\-format
+.IR json | prompt ]
+.RB [ \-\-file
+.IR path ]
+.SH DESCRIPTION
+Opens the uncommitted changes of a git repository, or its last commit on a
+clean tree, as a pull-request style review in your browser: inline comments
+on any line, threaded follow-ups, and comparisons between branches, tags and
+commits \(em reviewed together, one at a time, or as a run.
+.PP
+With something reading its output, it writes the finished review there the
+moment you submit it, and exits:
+.PP
+.RS
+.B git reviewer | claude \-p "Apply this review."
+.RE
+.PP
+On a terminal it says where the review was saved and keeps serving until
+the tab is closed.
+.PP
+The package is installed as
+.BR git\-reviewer ,
+which git runs as
+.BR "git reviewer" .
+.B reviewer
+is the same program under a shorter name.
+.SH COMMANDS
+.TP
+.B export
+Print the saved review of a repository to stdout, as JSON or as a prompt for
+a coding agent.
+.SH OPTIONS
+.TP
+.BR \-p ", " \-\-port " \fIn\fR"
+Port to listen on. The default is 4500; if it is taken, a free one is used.
+.TP
+.B \-\-no\-open
+Print the address instead of opening a browser.
+.TP
+.BR \-f ", " \-\-format " \fIjson\fR|\fIprompt\fR"
+Export format. The default is json.
+.TP
+.BI \-\-file " path"
+Export only the comments on one repository-relative file.
+.TP
+.BR \-h ", " \-\-help
+Print usage. Under git, use
+.BR \-h :
+git takes
+.B \-\-help
+to mean this page.
+.TP
+.BR \-v ", " \-\-version
+Print the version.
+.SH EXAMPLES
+.TP
+.B git reviewer
+Review the repository you are standing in.
+.TP
+.B git reviewer | claude \-p """Apply this review."""
+Review it, then hand it straight to an agent.
+.TP
+.B git reviewer export . \-\-format prompt | claude \-p """Apply this review."""
+Hand over a review written earlier.
+.SH SEE ALSO
+https://github.com/dheerajjha/reviewer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-reviewer",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "description": "Review your coding agent's changes like a pull request — locally, with inline comments and threaded follow-ups, then hand the marked-up review back to the agent",
   "author": "Dheeraj Jha",
   "license": "MIT",
@@ -38,7 +38,8 @@
     "bin/",
     "lib/",
     "public/",
-    "server.js"
+    "server.js",
+    "man/"
   ],
   "scripts": {
     "start": "node bin/reviewer.js",
@@ -51,5 +52,8 @@
     "cors": "^2.8.5",
     "express": "^4.18.2",
     "simple-git": "^3.20.0"
-  }
+  },
+  "man": [
+    "./man/git-reviewer.1"
+  ]
 }