git-reviewer 2.13.0 → 2.14.0

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-355-brightgreen.svg)](test/)
+[![Tests](https://img.shields.io/badge/tests-372-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)
@@ -73,20 +77,30 @@ reviewer export [repository] [--format json|prompt]
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --staged      Review only staged changes (HEAD vs index)
   -f, --format <f>  Export format: json (default) or prompt
   -h, --help        Show help
   -v, --version     Show the version
 ```
 
 ```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.
 
+Use `git reviewer --staged` to review what the next commit would contain.
+The file list, diff and full context come from the index, so edits made after
+`git add` stay out of the view. An empty index comparison stays empty; it does
+not fall back to the last commit. The scope bar and exported review identify
+this as a staged review. The default command still shows all working-tree
+changes. As with the default view, reload after changing what is staged. Saved comments
+are shared between views and may refer to code outside the current comparison;
+check their anchors before applying them.
+
 ### When you are not standing in a repository
 
 The page opens on a picker rather than on an empty box:
@@ -110,19 +124,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 +152,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 |
@@ -290,8 +310,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.
@@ -362,7 +382,7 @@ rather than a public issue.
 
 ```bash
 npm install           # 3 dependencies, no build step, ~6MB
-npm test              # 355 tests
+npm test              # 372 tests
 npm run test:watch
 npm run test:coverage
 ```
@@ -389,7 +409,7 @@ temporary directory. The HTTP tests do not stub git: each one builds a real
 repository in a temp directory and runs real `git` against it, because diff
 parsing is exactly where a stub would be wrong in the same way the code is.
 
-Tests run on Linux and macOS across Node 18, 20, and 22. See
+Tests run on Linux, macOS and Windows across Node 18, 20, and 22. See
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Tech
@@ -413,11 +433,18 @@ The ones most likely to change how the tool feels:
 - [#2](https://github.com/dheerajjha/reviewer/issues/2) — give comments a state, so a review can be worked through and marked off
 - [#3](https://github.com/dheerajjha/reviewer/issues/3) — report whether each anchor still matches the file
 - [#4](https://github.com/dheerajjha/reviewer/issues/4) — expose the review over MCP, so an agent works through it interactively
-- [#6](https://github.com/dheerajjha/reviewer/issues/6) — review a commit range, not just the working tree
+- [#6](https://github.com/dheerajjha/reviewer/issues/6) — open straight into a comparison from the command line, `git reviewer --range main...HEAD`
 
 [CONTRIBUTING.md](CONTRIBUTING.md) covers the setup and what a good change looks
 like here.
 
+## Related
+
+[margins](https://github.com/dheerajjha/margins) is its sibling for notes rather
+than diffs: `margins` in a folder of markdown opens it in the browser, with a
+file tree, `[[wikilinks]]` and backlinks, search, and editing with a live
+preview. `npm install -g margins`.
+
 ## License
 
 [MIT](LICENSE) © Dheeraj Jha

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;
     }
 
@@ -246,7 +250,7 @@ async function main() {
     options.port ?? (Number(process.env.PORT) || DEFAULT_PORT),
     { onReviewSubmitted, handoff: handingOff, onIdle }
   );
-  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath);
+  const url = buildUrl(`http://${DEFAULT_HOST}:${server.address().port}`, repoPath, options.staged);
 
   note(`\n  Code Reviewer  ${url}`);
   if (repoPath) note(`  reviewing      ${repoPath}`);
@@ -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

@@ -22,7 +22,7 @@ const SCHEMA = 'code-review/v1';
  * @property {string} schema
  * @property {string} generatedAt ISO 8601
  * @property {{path: string, name: string, head: string|null, branch: string|null}} repository
- * @property {'working'|'lastCommit'|null} mode
+ * @property {'working'|'staged'|'lastCommit'|'range'|null} mode
  * @property {{comments: number, files: number}} summary
  * @property {AgentComment[]} comments
  */
@@ -205,6 +205,10 @@ function describeScope({ repository, mode, range }) {
     return `Reviewed: uncommitted changes in the working tree, against ${repository.branch ?? 'HEAD'}${at}.`;
   }
 
+  if (mode === 'staged') {
+    return 'Comparison: staged changes in the index, against HEAD. Saved comments are shared between review views and may refer to changes outside this comparison; check their anchors before applying them.';
+  }
+
   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

package/lib/changes.js

@@ -268,7 +268,24 @@ function collectCommitChanges(diffSummary, statuses) {
   });
 }
 
+/**
+ * Files in the next commit, including their index status rather than any
+ * later working-tree edits. Omitting HEAD also works before the first commit.
+ * @param {import('simple-git').SimpleGit} git
+ */
+async function collectStagedChanges(git) {
+  if (await git.raw(['ls-files', '--unmerged', '-z'])) {
+    throw new Error('Resolve merge conflicts before reviewing staged changes.');
+  }
+  const [summary, raw] = await Promise.all([
+    git.diffSummary(['--cached']),
+    git.raw(['diff', '--cached', '--name-status', '-z', '-M'])
+  ]);
+  return collectCommitChanges(summary, parseNameStatus(raw));
+}
+
 module.exports = {
+  collectStagedChanges,
   collectWorkingChanges,
   collectCommitChanges,
   classifyCommitFile,

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
@@ -40,21 +43,29 @@ Options:
   -p, --port <n>    Port to listen on (default 4500; falls back to a free
                     port if that one is taken)
       --no-open     Print the URL instead of opening a browser
+      --staged      Review only staged changes (HEAD vs index)
   -f, --format <f>  Export format: json (default) or prompt
       --file <path> Export comments for one repo-relative file
   -h, --help        Show this help
   -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'];
@@ -73,6 +84,7 @@ class UsageError extends Error {
  * @property {string|null} repoPath absolute path, or null when not given
  * @property {number|null} port explicit port, or null to use the default
  * @property {boolean} open whether to launch a browser
+ * @property {boolean} staged whether to review only the index
  * @property {'json'|'prompt'} format for `export`
  * @property {string|null} file repo-relative file to export, or all files
  * @property {boolean} help
@@ -94,6 +106,7 @@ function parseArgs(argv, cwd = process.cwd()) {
     repoPath: null,
     port: null,
     open: true,
+    staged: false,
     format: 'json',
     file: null,
     help: false,
@@ -128,6 +141,10 @@ function parseArgs(argv, cwd = process.cwd()) {
         options.open = false;
         break;
 
+      case '--staged':
+        options.staged = true;
+        break;
+
       case '-p':
       case '--port': {
         const value = rest[++i];
@@ -191,6 +208,10 @@ function parseArgs(argv, cwd = process.cwd()) {
     throw new UsageError('--file is only valid with reviewer export');
   }
 
+  if (options.staged && options.command !== 'serve') {
+    throw new UsageError('--staged is only valid when serving a review');
+  }
+
   return options;
 }
 
@@ -239,10 +260,11 @@ function parseFile(value, flag) {
  *
  * @param {string} origin e.g. http://127.0.0.1:4500
  * @param {string|null} repoPath
+ * @param {boolean} [staged]
  * @returns {string}
  */
-function buildUrl(origin, repoPath) {
-  if (!repoPath) return origin;
+function buildUrl(origin, repoPath, staged = false) {
+  if (!repoPath) return staged ? `${origin}/?staged=1` : origin;
 
   // Slashes are left as slashes. They are legal in a query value -- RFC 3986
   // has `query = *( pchar / "/" / "?" )` -- and encoding them turns the most
@@ -253,7 +275,29 @@ function buildUrl(origin, repoPath) {
   //
   // Everything else stays encoded, including the characters that would
   // otherwise end the query and take the rest of the path with them.
-  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}`;
+  return `${origin}/?repo=${encodeURIComponent(repoPath).replace(/%2F/g, '/')}${staged ? '&staged=1' : ''}`;
+}
+
+/**
+ * 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';
 }
 
-module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS };
+const USAGE = usage();
+
+module.exports = { parseArgs, buildUrl, UsageError, USAGE, FORMATS, usage, invokedAs };

package/lib/sessions.js

@@ -11,10 +11,11 @@ const crypto = require('crypto');
  */
 
 /**
- * @typedef {'working'|'lastCommit'|'range'} ReviewMode
+ * @typedef {'working'|'staged'|'lastCommit'|'range'} ReviewMode
  * `working` diffs the working tree against HEAD; `lastCommit` diffs HEAD
  * against its parent, which is what a clean tree falls back to; `range`
  * diffs two refs the reviewer chose.
+ * `staged` diffs the index against HEAD without including working-tree edits.
  */
 
 /**

package/man/git-reviewer.1

@@ -0,0 +1,84 @@
+.\" 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
+.B \-\-staged
+Review only staged changes, comparing HEAD with the index. Unstaged edits are
+excluded, and an empty index comparison does not fall back to the last commit.
+.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.13.0",
+  "version": "2.14.0",
   "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"
+  ]
 }

package/public/app.js

@@ -2,6 +2,7 @@
 // In web mode, this will be http://localhost:4500
 // In Electron, this will be the random port Electron assigned
 const API_BASE = `${window.location.origin}/api`;
+const stagedByDefault = new URLSearchParams(window.location.search).get('staged') === '1';
 
 let currentRepoId = null;
 let currentFiles = [];
@@ -492,10 +493,10 @@ function renderScope(data) {
       document.getElementById('nextCommitBtn').disabled = true;
     }
   } else {
-    label.append('Uncommitted changes');
+    label.append(data.mode === 'staged' ? 'Staged changes' : 'Uncommitted changes');
     if (branch) label.append(' on ', strong(branch));
     meta.textContent = plural(data.files.length, 'file') + ' changed';
-    setNote(null);
+    setNote(data.mode === 'staged' ? 'The diff excludes unstaged changes. Saved comments are shared between views and may refer to other code; check their anchors.' : null);
   }
 
   row.classList.add('hidden');
@@ -781,7 +782,7 @@ async function loadRepo(scope = {}) {
       body: JSON.stringify(
         scope.commits ? { repoPath, commits: scope.commits }
           : scope.base ? { repoPath, base: scope.base, ...(scope.head ? { head: scope.head } : {}) }
-            : { repoPath }
+            : { repoPath, staged: stagedByDefault }
       )
     });
 
@@ -817,13 +818,13 @@ async function loadRepo(scope = {}) {
       // `message`, and the scope bar above is still showing how many commits
       // that covers -- so this is information, not an error, and it must not
       // be dressed as one.
-      if (data.mode === 'range') {
+      if (data.mode === 'range' || data.mode === 'staged') {
         // The scope bar is already explaining this; a status line repeating
         // it underneath is two bars saying one thing.
         clearStatus();
         hidePicker();
         displayFiles([]);
-        showEmptyFileList(data.range?.kind !== 'commits'
+        showEmptyFileList(data.mode === 'staged' ? 'No staged changes.' : data.range?.kind !== 'commits'
           ? 'No files differ between these two.'
           : data.range.first === data.range.last
             ? 'This commit changes no files.'

package/server.js

@@ -12,7 +12,7 @@ const {
   resolveRepoFile,
   PathEscapeError
 } = require('./lib/paths');
-const { collectWorkingChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
+const { collectWorkingChanges, collectStagedChanges, collectCommitChanges, parseNameStatus } = require('./lib/changes');
 const { SessionStore } = require('./lib/sessions');
 const { normalizeComments } = require('./lib/comments');
 const { formatReview, reviewFilename, commentsFilename } = require('./lib/review');
@@ -137,6 +137,18 @@ function createApp(options = {}) {
     const git = gitFactory(session.repoPath);
     const absolutePath = resolveRepoFile(session.repoPath, filePath);
 
+    if (session.mode === 'staged') {
+      try {
+        // `:0:` names the stage outright. A bare `:` reads a file called
+        // `0:foo` as stage 0 of `foo`, and shows the wrong file's text.
+        return await git.show([`:0:${filePath}`]);
+      } catch {
+        // A staged deletion has no index entry. Its old content comes from
+        // HEAD, even if a replacement now exists in the working tree.
+        return git.show([`HEAD:${filePath}`]).catch(() => { throw new FileNotFoundError(filePath); });
+      }
+    }
+
     if (session.range) {
       // A range is two commits, and the working tree is neither of them. It
       // used to be the fallback here, which was merely odd while the head of
@@ -222,6 +234,9 @@ function createApp(options = {}) {
   }
 
   async function diffForFile(git, session, filePath) {
+    if (session.mode === 'staged') {
+      return git.diff(['--cached', '--', filePath]);
+    }
     if (session.range) {
       return git.diff([session.range.from, session.range.head, '--', filePath]);
     }
@@ -768,7 +783,10 @@ function createApp(options = {}) {
       // Resolve to the root of the working tree before anything is keyed on
       // this path. A subdirectory passes `checkIsRepo()` quite happily and
       // then produces a file list whose diffs are all empty; see lib/repo.js.
-      const { base, head, commits: run } = req.body ?? {};
+      const { base, head, commits: run, staged = false } = req.body ?? {};
+      if (typeof staged !== 'boolean' || (staged && (base != null || head != null || run != null))) {
+        return res.status(400).json({ error: 'Choose staged changes or a commit comparison, not both.' });
+      }
       const root = await repoRoot(repoPath, gitFactory);
       if (!root) {
         return res.status(400).json({ error: 'Not a valid git repository' });
@@ -781,7 +799,15 @@ function createApp(options = {}) {
       let range = null;
       let message;
 
-      if (run && typeof run === 'object') {
+      if (staged) {
+        try {
+          files = await collectStagedChanges(git);
+        } catch (error) {
+          return res.status(400).json({ error: error.message });
+        }
+        mode = 'staged';
+        message = files.length ? `Found ${files.length} staged file(s)` : 'No staged changes';
+      } else if (run && typeof run === 'object') {
         // Commits themselves, one or a run: see resolveCommitRun.
         try {
           range = await resolveCommitRun(git, `${run.from ?? ''}`.trim(), `${run.to ?? run.from ?? ''}`.trim());