git-review-workflow 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/LICENSE +21 -21
  2. package/README.es.md +548 -548
  3. package/README.md +540 -540
  4. package/VERSION +1 -1
  5. package/bin/git-review +1 -1
  6. package/bin/git-review-lib.sh +0 -0
  7. package/bin/git-review-verbs/abort +0 -0
  8. package/bin/git-review-verbs/clean +0 -0
  9. package/bin/git-review-verbs/compare +0 -0
  10. package/bin/git-review-verbs/continue +0 -0
  11. package/bin/git-review-verbs/finish +0 -0
  12. package/bin/git-review-verbs/forget +0 -0
  13. package/bin/git-review-verbs/list +0 -0
  14. package/bin/git-review-verbs/next +0 -0
  15. package/bin/git-review-verbs/prev +0 -0
  16. package/bin/git-review-verbs/preview +0 -0
  17. package/bin/git-review-verbs/save +0 -0
  18. package/bin/git-review-verbs/start +0 -0
  19. package/bin/git-review-verbs/status +0 -0
  20. package/package.json +42 -39
package/README.md CHANGED
@@ -1,540 +1,540 @@
1
- # git-review-workflow
2
-
3
- > Review a pull request by **editing and running** it, not just reading it. The
4
- > whole PR lands in your working tree as one staged diff; your fixes are then
5
- > extracted onto a clean branch automatically. Re-review only what changed.
6
-
7
- [![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)
8
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9
- [![Release](https://img.shields.io/github/v/tag/EzeVillo/git-review-workflow?label=release&sort=semver)](https://github.com/EzeVillo/git-review-workflow/releases)
10
-
11
- **English** · [Español](README.es.md)
12
-
13
- ---
14
-
15
- Reviewing in a web UI is fine for leaving comments, but poor for actually
16
- *running* and *editing* the code. `git review start` puts the entire PR in your
17
- working tree as **staged, uncommitted changes**: it creates a `review/<branch>`
18
- branch whose working tree holds the PR tip, but whose `HEAD` sits at the
19
- merge-base with your base branch. Because it is just your working tree, you open
20
- the whole PR in any editor — read the diff, edit inline, run the tests — and when
21
- you are done, `git review finish` pulls *your* edits back out onto a separate
22
- `review-fixes/<branch>` branch (or onto the PR branch itself), keeping them
23
- cleanly apart from the author's work. Re-review only the new commits after an
24
- update with `--delta`.
25
-
26
- > **All commands live under `git review <verb>`** — `git review start`,
27
- > `git review finish`, `git review status`, and so on, the way `git bisect` and
28
- > `git stash` group their verbs.
29
-
30
- ## Why not just use my IDE's PR view?
31
-
32
- Most tools let you *see* a PR. The gap this fills is *acting* on one — editing
33
- and running it like ordinary working-tree changes, then handing your fixes back
34
- without manual stashing or cherry-picking.
35
-
36
- | | View the PR | Edit & run as working tree | Auto-extract your fixes | Incremental re-review (`--delta`) | Editor-agnostic |
37
- |---------------------------------|:-----------------:|:--------------------------:|:-----------------------:|:---------------------------------:|:---------------:|
38
- | **git-review-workflow** | ✅ | ✅ | ✅ | ✅ | ✅ |
39
- | `gh pr checkout` / `glab` | ⚠️ plain checkout | ✅ | ❌ | ❌ | ✅ |
40
- | JetBrains *Review Pull Request* | ✅ | ⚠️ in-IDE only | ❌ | ❌ | ❌ |
41
- | VS Code *GitHub PR* extension | ✅ | ⚠️ in-IDE only | ❌ | ❌ | ❌ |
42
- | GitHub / GitLab web UI | ✅ | ❌ | ❌ | ⚠️ partial | ✅ |
43
-
44
- Because the PR is just staged changes, anything that reads a Git diff sees all
45
- of it — including AI coding agents like Claude Code or Codex that have no
46
- PR-review feature of their own. Point one at the staged diff and it can review or
47
- fix the whole PR in place.
48
-
49
- And for the small stuff — a rename, a typo, a clearer variable name — fixing it
50
- yourself is faster and less bureaucratic than leaving a comment and waiting for a
51
- round-trip, especially when you are already looking at the PR in your editor.
52
- Because your edits are extracted automatically, the fix costs about the same as
53
- the comment would have. Or hand the staged diff to an agent and have it make the
54
- change for you.
55
-
56
- If you mostly *comment*, your IDE's native PR panel is enough. If you review by
57
- editing and running the code — in any editor or agent — this is the gap it fills.
58
-
59
- ## Quick start
60
-
61
- ```sh
62
- # 1. Install (needs Node.js; see Installation for Homebrew and a no-Node option)
63
- npm install -g git-review-workflow
64
-
65
- # 2. Tell it where PRs are integrated, once per repo
66
- git config reviewworkflow.base develop
67
-
68
- # 3. Stage a PR branch as a single diff, then open the repo in your IDE
69
- git review start feature/login
70
- # ...read and edit the staged diff in your editor, run tests...
71
- git review finish # extract your edits onto review-fixes/feature/login
72
- ```
73
-
74
- Prefer Homebrew, a native Windows (PowerShell) installer, or an install that
75
- does not need Node? See [Installation](#installation). For the full flow —
76
- re-reviewing updates, walking a PR commit by commit, cleanup — see
77
- [Typical workflow](#typical-workflow).
78
-
79
- ## Installation
80
-
81
- These commands plug into `git` as a single subcommand — you run them as
82
- `git review start`, `git review finish`, and so on. Pick whichever method matches
83
- your setup. The package-manager options are the easiest and **set up your `PATH`
84
- for you**.
85
-
86
- ### npm (recommended)
87
-
88
- If you have [Node.js](https://nodejs.org), this is the one-command install. It
89
- puts `git review` on your `PATH` for you and works on Linux, macOS and Windows
90
- (on Windows the commands still run under Git Bash):
91
-
92
- ```sh
93
- npm install -g git-review-workflow
94
- ```
95
-
96
- Update with `npm install -g git-review-workflow@latest`; uninstall with
97
- `npm uninstall -g git-review-workflow`. Tab completion is set up the same way as
98
- the other non-Homebrew installs — see the note below.
99
-
100
- ### Homebrew (macOS / Linux)
101
-
102
- ```sh
103
- brew tap EzeVillo/git-review-workflow https://github.com/EzeVillo/git-review-workflow
104
- brew install EzeVillo/git-review-workflow/git-review-workflow
105
- ```
106
-
107
- Tab completion is configured automatically. To update to the latest release:
108
- `brew upgrade git-review-workflow`.
109
-
110
- ### Windows (PowerShell)
111
-
112
- You still need [Git for Windows](https://gitforwindows.org), which provides the
113
- shell these commands run in. Open PowerShell and run:
114
-
115
- ```powershell
116
- irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.ps1 | iex
117
- ```
118
-
119
- This installs the command into `~\.local\bin` and adds that folder to your user
120
- `PATH` automatically. Open a new terminal after it finishes. Re-run to update; to
121
- uninstall:
122
-
123
- ```powershell
124
- irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.ps1 | iex
125
- ```
126
-
127
- (If you have Node, `npm install -g git-review-workflow` works on Windows too —
128
- the commands still run under Git Bash either way.)
129
-
130
- ### One-line install (Linux, macOS, WSL, Git Bash)
131
-
132
- No package manager? This downloads the command and installs it into
133
- `~/.local/bin` — you don't need to clone the project first:
134
-
135
- ```sh
136
- curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.sh | sh
137
- ```
138
-
139
- Re-run to update (always installs the latest release). To uninstall (pass the
140
- same `PREFIX` if you overrode it):
141
-
142
- ```sh
143
- curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.sh | sh
144
- ```
145
-
146
- <details>
147
- <summary>From a downloaded copy</summary>
148
-
149
- If you cloned or downloaded the project, open its folder in a terminal and run:
150
-
151
- ```sh
152
- ./install.sh
153
- ```
154
-
155
- This installs the `git review` dispatcher into `~/.local/bin` (change the
156
- location with `PREFIX=/usr/local/bin ./install.sh`). The verbs travel beside it
157
- as private helpers, not as separate commands on your `PATH`. Undo it any time
158
- with `./uninstall.sh`. To update, just `git pull` inside the repo — the symlink
159
- picks up changes automatically.
160
- </details>
161
-
162
- <details>
163
- <summary>"command not found" — adding <code>~/.local/bin</code> to your PATH</summary>
164
-
165
- Your `PATH` is the list of folders your terminal searches when you type a
166
- command. Homebrew, npm and the PowerShell installer add their folder for you. The
167
- one-line and manual installs use `~/.local/bin`, which is already on the `PATH`
168
- on most systems. If it isn't, the installer prints a note — add it **once** by
169
- pasting one line into your shell's config file:
170
-
171
- | If your terminal uses… | Add this line to the file… | The line to add |
172
- |-----------------------------------|----------------------------------|----------------------------------------|
173
- | **bash** | `~/.bashrc` | `export PATH="$HOME/.local/bin:$PATH"` |
174
- | **zsh** (default on recent macOS) | `~/.zshrc` | `export PATH="$HOME/.local/bin:$PATH"` |
175
- | **fish** | *(no file — just run this once)* | `fish_add_path ~/.local/bin` |
176
-
177
- Not sure which one you use? Run `echo $0`. After editing the file, **open a new
178
- terminal** (or `source` the file). Run `git review -h` to confirm.
179
- </details>
180
-
181
- <details>
182
- <summary>Tab completion (manual installs)</summary>
183
-
184
- Homebrew sets this up for you. Otherwise, tell your shell to load the matching
185
- file on start. Replace `/path/to/git-review-workflow` with where you downloaded
186
- the project.
187
-
188
- ```sh
189
- # bash — in ~/.bashrc
190
- source /path/to/git-review-workflow/completions/git-review-workflow.bash
191
-
192
- # zsh — in ~/.zshrc
193
- source /path/to/git-review-workflow/completions/git-review-workflow.zsh
194
-
195
- # fish — copy into fish's completions folder (no config line needed)
196
- cp /path/to/git-review-workflow/completions/git-review-workflow.fish \
197
- ~/.config/fish/completions/
198
- ```
199
-
200
- Then open a new terminal. Typing `git review ` and pressing **Tab** now offers
201
- the verbs; `git review start ` offers your branch names.
202
- </details>
203
-
204
- <details>
205
- <summary>Git Bash on Windows — SSL error during install?</summary>
206
-
207
- If you see `schannel: next InitializeSecurityContext failed` or a
208
- `revocation check` message, your Git for Windows is using the Windows SSL
209
- backend. Fix it once, then re-run the installer:
210
-
211
- ```sh
212
- git config --global http.sslBackend openssl
213
- ```
214
-
215
- </details>
216
-
217
- ## Commands
218
-
219
- > **How to read the syntax:** `<x>` is **required**, `[x]` is **optional**, and
220
- > `a | b` means **pick one, not both**.
221
-
222
- Every command is a verb under `git review`. Run `git review -h` for the list, or
223
- `git review <verb> -h` for one verb's details.
224
-
225
- | Command | What it does |
226
- |----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
227
- | `git review [-h \| --version]` | List all verbs or print the installed version. |
228
- | `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). |
229
- | `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. |
230
- | `git review next` / `git review prev` | Move a `--step` review to the next / previous commit. |
231
- | `git review status` | Show the state of the review on the current branch. |
232
- | `git review list` | List every review in progress and every saved one (current branch marked `*`). |
233
- | `git review save` | Pause the current review as `review-saved/<branch>` and return to where you started. |
234
- | `git review continue [branch]` | Resume a review saved with `git review save`. |
235
- | `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. |
236
- | `git review preview [--stat]` | Show the edits you have made so far — the diff `finish` would extract — without committing or switching branch. |
237
- | `git review abort` | Cancel the current review and return to where you started. |
238
- | `git review clean [branch]` | Delete the `review/*` and `review-fixes/*` branches for `<branch>`, or all of them. |
239
- | `git review forget --delta (<branch> \| --all \| --stale [--dry-run])` | Discard the `--delta` marker for one branch, all of them, or only stale ones. |
240
- | `git review forget --saved (<branch> \| --all) [--dry-run]` | Discard a review saved with `git review save`. |
241
-
242
- ### `git review start`
243
-
244
- Has two independent axes — **range** (where the review starts) and **layout**
245
- (`--step` or not), which compose freely.
246
-
247
- - `<branch>` — the branch to review. **Omit it to review the branch you currently
248
- have checked out** — git's own default (like `push`, `status`, `log`). It only
249
- resolves the name; the mode is still chosen by flags, so pair the omitted branch
250
- with `--local` to review your local work. Without `--local` it reviews
251
- `origin/<branch>` — if that differs from your checked-out branch you get a note,
252
- since you would be reviewing a different snapshot than you have. With no branch,
253
- fails on a detached HEAD or while on a `review/*` branch.
254
- - `base` — commit-ish to diff against: a branch, a **tag**, or a commit. Taken
255
- from `reviewworkflow.base` (see below); a positional argument overrides it.
256
- **Required for a full review** — there is no built-in default, so a full review
257
- with no base set fails and asks you to configure one. Not used with `--delta` or
258
- `--from`, which carry their own starting point — passing an explicit base
259
- alongside them is an error (a base from config is simply ignored).
260
- - `--base <base>` — the base to diff against, as a flag. Use it to pass a base
261
- while letting `<branch>` default to the current branch — e.g.
262
- `git review start --base develop` reviews the branch you are on against
263
- `develop` (the lone positional is always taken as `<branch>`, so the flag is how
264
- you reach the base without naming the branch). Cannot be combined with a
265
- positional base.
266
- - `--delta` — review only the commits added **since your last review** of this
267
- branch, instead of the whole PR. Perfect for re-reviewing an updated PR. The
268
- recorded tip survives `git review clean`, so this works even after you deleted
269
- the review branches; discard it explicitly with `git review forget --delta`.
270
- - `--from <commit>` — review only the commits **after `<commit>`**. Handy when
271
- there is no recorded review to delta from, or to pick an exact starting point.
272
- Mutually exclusive with `--delta`.
273
- - `--step` — review the range **one commit at a time** (combine with `--delta`
274
- or `--from` to walk just those commits). You start on the first commit after
275
- the merge-base; the command prints its author message. Edit files, then run
276
- `git review next` to bank your edits and move to the next commit with a clean
277
- tree. When the commits run out, run `git review finish` and all your banked
278
- edits are replayed onto the PR tip — exactly as in a whole-PR review.
279
- - `--local` — review your **local** branches directly, without fetching. The
280
- review is built from your local `<branch>` and diffed against your local base,
281
- so it works offline and lets you review your own work before pushing. It keeps
282
- its own `--delta` marker, separate from the remote one, so local and remote
283
- reviews of the same branch name never overwrite each other's progress.
284
- - Always updates from `origin` first and **fails** if it cannot (unless
285
- `--local`). The review is built from `origin/<branch>`, never a stale local
286
- copy. If a local branch of the same name points somewhere else, it prints a
287
- note: the review reflects the remote, not your checkout, and a later
288
- `git review finish --onto-source` would refuse until your local branch matches.
289
- - Refuses to run if you have local changes — start from a clean branch.
290
- - **Merges of the base branch are excluded.** If the author merged the base
291
- (e.g. `develop`) into the PR, that merged-in content is left out of the review
292
- in every mode, so you only see the author's own changes.
293
- - `--` ends option parsing, the usual git convention: everything after it is
294
- treated as a positional argument, so a branch whose name starts with `-` can
295
- still be reviewed (e.g. `git review start -- --weird develop`).
296
-
297
- ### `git review compare`
298
-
299
- Stage the diff between two commit-ish — two tags, two commits, two branches — as
300
- one read-only review, so you can read it inline or walk it commit by commit with
301
- the same UX as a real review, without `git diff | less`.
302
-
303
- ```sh
304
- git review compare v1.0 v2.0 # stage the diff between two releases
305
- git review compare v1.0 v2.0 --step # ...and walk it commit by commit
306
- ```
307
-
308
- - It diffs `<a>..<b>`: `<a>` is the lower bound (where the review starts), `<b>`
309
- the tip whose content fills the working tree. Both are resolved to commits, so
310
- tags and raw SHAs work, not only branch names.
311
- - It is **read-only by design**. The whole edit→finish half of the workflow needs
312
- a writable branch to write back to, and a tag or a commit is not one — so
313
- `git review finish` on a compare refuses explicitly ("this review is read-only,
314
- there is nothing to write back"). Use `git review abort` to end it.
315
- - `--step` walks it one commit at a time, exactly like `git review start --step`,
316
- with `git review next` / `git review prev`.
317
-
318
- ### `git review next` / `git review prev`
319
-
320
- Move a `--step` review forward or backward. Each move banks the current commit's
321
- edits and restores any edits you had banked on the commit you move to, so you can
322
- walk back and forth without losing work.
323
-
324
- ### `git review status`
325
-
326
- Shows the current review: source PR, mode, and — in `--step` mode — which commit
327
- you are on (`[k/N]`) and which steps have banked edits.
328
-
329
- ### `git review list`
330
-
331
- Shows *every* `review/*` branch in progress at once (with its source PR, mode and
332
- step position). Reviews paused with `git review save` are listed too, under
333
- `saved`. The branch you are currently on is marked with a `*`.
334
-
335
- ### `git review save` / `git review continue`
336
-
337
- `git review save` lets you put a review aside and pick it up later. It turns the
338
- current `review/<branch>` into `review-saved/<branch>` and returns you to the
339
- branch you started from, carrying everything needed to resume exactly where you
340
- left off:
341
-
342
- - In whole-PR mode, the staged PR diff and your uncommitted edits.
343
- - In `--step` mode, the commit you are on, its edits, and every edit you have
344
- banked on the other commits. The banked-edit refs are moved out of
345
- `refs/review-edits/` (which `git review clean` prunes) into
346
- `refs/review-saved-edits/`, so a `git review clean` never touches a saved review.
347
-
348
- `git review continue` turns `review-saved/<branch>` back into the active
349
- `review/<branch>` and restores that exact state — in `--step` mode it drops you
350
- back on the same commit, with `git review next` / `git review prev` working as
351
- before. With no argument it resumes the only saved review, or lists them if there
352
- is more than one; name a branch to pick a specific one.
353
-
354
- Starting a fresh `git review start` on a branch that already has a saved review
355
- is refused, so you do not silently lose the paused one — resume it or discard it
356
- with `git review forget --saved` first.
357
-
358
- ### `git review finish`
359
-
360
- - Default — create `review-fixes/<branch>` on top of the PR tip with your edits
361
- staged, so you can review and commit them yourself.
362
- - `--onto-source` — stage your edits on the PR branch itself instead, so you can
363
- review and commit them yourself there.
364
- - Either way the result stays local — review it and push it yourself when ready.
365
- - `--resume` — in `--step` mode, if banked edits overlap the PR tip, the replay
366
- leaves conflict markers and stops. Resolve them in the working tree, then run
367
- `git review finish --resume` (with the same flags) to continue.
368
- - `--abort` — undo the last finish and drop you back on `review/<branch>` exactly
369
- where you were editing, the same way `git merge --abort` backs out a merge. It
370
- refuses if you have changed the finish branch since, so you do not lose work;
371
- add `--force` to discard those changes and abort anyway.
372
- - Refuses on a read-only `git review compare` — there is no writable branch to
373
- write your edits back to.
374
-
375
- ### `git review preview`
376
-
377
- Shows the edits you have made so far — the same diff `git review finish` would
378
- extract, your review edits on top of the PR tip — but it **never commits, never
379
- switches branch and never touches your working tree or index**, so you go straight
380
- back to editing where you left off. Think of it as "what would `finish` give me
381
- right now?".
382
-
383
- - `--stat` — show a diffstat summary instead of the full diff.
384
- - In `--step` mode it replays the current commit's edits plus every banked edit
385
- onto the tip, exactly like `finish`. An edit that genuinely conflicts with the
386
- tip is the one case that differs: a read-only preview cannot leave you conflict
387
- markers, so it omits that edit and prints a note pointing you at `finish`.
388
-
389
- ### `git review abort`
390
-
391
- Cancels the current review in one step: it returns you to the branch you started
392
- from, then deletes the `review/<branch>` branch and its banked edits. Because the
393
- review was cancelled (not completed), it rolls the `--delta` marker back to your
394
- last actual review, so a later `--delta` does not skip commits you never
395
- reviewed.
396
-
397
- ### `git review clean`
398
-
399
- - With no `<branch>`, deletes every `review/*` and `review-fixes/*` branch.
400
- - Never deletes the branch you are currently on.
401
- - Also drops any banked commit-by-commit edit refs, even when no review branches
402
- remain.
403
- - Leaves the `--delta` marker untouched — discard it with `git review forget --delta`.
404
- - Leaves saved reviews (`review-saved/*`) untouched — discard one with
405
- `git review forget --saved`.
406
-
407
- ### `git review forget --delta`
408
-
409
- Discards the recorded last-reviewed tip that `--delta` relies on. The marker is
410
- kept deliberately so `--delta` survives `git review clean`; this is how you clear
411
- it.
412
-
413
- - `<branch>` — forget the marker(s) for one source branch, both the remote one
414
- and the `--local` one if present.
415
- - `--all` — forget every recorded marker (leaves `reviewworkflow.base` alone).
416
- - `--stale` — fetch and prune `origin`, then forget only the markers whose branch
417
- no longer exists: remote markers whose `origin/<branch>` is gone (e.g. PRs that
418
- were merged and deleted), and `--local` markers whose local `<branch>` is gone.
419
- Aborts without removing anything if the fetch fails.
420
- - `--dry-run` — with `--stale`, list what would be forgotten without doing it.
421
- Rejected with the other modes, where the target is already explicit.
422
-
423
- ### `git review forget --saved`
424
-
425
- Discards a review put aside with `git review save`: deletes
426
- `review-saved/<branch>`, its banked edits and its metadata. Because a saved review
427
- was paused (not completed), it also rolls the `--delta` marker back to your last
428
- actual review, the same way `git review abort` does.
429
-
430
- - `<branch>` — discard the saved review for one source branch.
431
- - `--all` — discard every saved review.
432
- - `--dry-run` — list what would be discarded without discarding it.
433
-
434
- ## Configuring the base branch
435
-
436
- The base branch is where PRs are integrated (`develop`, `main`, `master`, …) and
437
- varies per team, so there is no default — set it once per repository:
438
-
439
- ```sh
440
- git config reviewworkflow.base develop
441
- ```
442
-
443
- Resolution order: positional `base` argument (or `--base <base>`) →
444
- `reviewworkflow.base`. If neither is set, a full review fails and asks you to
445
- configure one. The base is any commit-ish — a branch, a tag (`v1.0`) or a
446
- commit — not only a branch name.
447
-
448
- ## Configure the remote
449
-
450
- By default the commands fetch and push against `origin`. If you review a
451
- repository you do not own (an `upstream`, with your `origin` as a fork, say),
452
- point the workflow at that remote:
453
-
454
- ```sh
455
- git config reviewworkflow.remote upstream
456
- ```
457
-
458
- It affects `git review start` and `git review forget --delta --stale`. A
459
- `--local` review ignores the remote entirely.
460
-
461
- ### Per-repository by design
462
-
463
- Both `reviewworkflow.base` and `reviewworkflow.remote` are plain `git config`
464
- keys, so they are stored **per repository** (in each repo's `.git/config`). You
465
- don't manage profiles or a shared config file — every repository you work in
466
- keeps its own base and remote independently, and they never leak into one
467
- another:
468
-
469
- ```sh
470
- # repo A: PRs land on main, fetched from origin (the default)
471
- cd ~/project-a && git config reviewworkflow.base main
472
-
473
- # repo B: PRs land on develop, reviewed from an upstream you don't own
474
- cd ~/project-b
475
- git config reviewworkflow.base develop
476
- git config reviewworkflow.remote upstream
477
- ```
478
-
479
- The same applies to the `--delta` markers — they live in each repo's config too.
480
- If you want a fallback that applies to *all* your repos, set it globally
481
- (`git config --global reviewworkflow.base main`); a per-repo value overrides it,
482
- and a positional `base` argument overrides both.
483
-
484
- ## Typical workflow
485
-
486
- ```sh
487
- git config reviewworkflow.base develop # once per repo
488
-
489
- git review start feature/login # stage the whole PR
490
- # ...open the repo in your IDE, read the staged diff, edit inline, run tests...
491
- git review finish # extract fixes to review-fixes/feature/login
492
- git diff --cached && git commit -m "address review comments"
493
- git review clean feature/login # tidy up
494
-
495
- # Re-review after the author pushes more commits:
496
- git review start feature/login --delta # only the new commits
497
- git review start feature/login --delta --step # ...and walk them one by one
498
-
499
- # Or walk the PR commit by commit from the start:
500
- git review start feature/login --step # start on the first commit
501
- # ...edit, then...
502
- git review next # bank edits, move to the next commit
503
- git review next # ...until "no more commits"
504
- git review finish # replay all your edits onto the tip
505
-
506
- # Pick an explicit starting commit:
507
- git review start feature/login --from a1b2c3d
508
-
509
- # Review the branch you are already on (omit the name):
510
- git switch feature/login && git review start # vs the configured base
511
- git review start --base develop # ...or against an explicit base
512
-
513
- # Compare against a tag instead of a branch:
514
- git review start feature/login v1.0
515
-
516
- # Compare two releases read-only:
517
- git review compare v1.0 v2.0
518
-
519
- # Review your own local branch before pushing, offline:
520
- git review start feature/login --local
521
- ```
522
-
523
- ## Requirements
524
-
525
- - Git 2.23+ (uses `git switch`). Git 2.38+ is recommended: excluding base
526
- content that was merged into the PR uses `git merge-tree --write-tree`, and on
527
- older git that one step is skipped (the merged base content would then show in
528
- `--delta`/`--from`).
529
- - A remote named `origin` (or whatever you set with `reviewworkflow.remote`).
530
- - A POSIX shell. On Linux and macOS this is the default. On Windows the commands
531
- run under Git Bash or WSL, not in `cmd.exe` or PowerShell.
532
-
533
- ## Contributing
534
-
535
- Bug reports, fixes and ideas are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
536
- for how to run the tests and the release process.
537
-
538
- ## License
539
-
540
- [MIT](LICENSE) © EzeVillo
1
+ # git-review-workflow
2
+
3
+ > Review a pull request by **editing and running** it, not just reading it. The
4
+ > whole PR lands in your working tree as one staged diff; your fixes are then
5
+ > extracted onto a clean branch automatically. Re-review only what changed.
6
+
7
+ [![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)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9
+ [![Release](https://img.shields.io/github/v/tag/EzeVillo/git-review-workflow?label=release&sort=semver)](https://github.com/EzeVillo/git-review-workflow/releases)
10
+
11
+ **English** · [Español](README.es.md)
12
+
13
+ ---
14
+
15
+ Reviewing in a web UI is fine for leaving comments, but poor for actually
16
+ *running* and *editing* the code. `git review start` puts the entire PR in your
17
+ working tree as **staged, uncommitted changes**: it creates a `review/<branch>`
18
+ branch whose working tree holds the PR tip, but whose `HEAD` sits at the
19
+ merge-base with your base branch. Because it is just your working tree, you open
20
+ the whole PR in any editor — read the diff, edit inline, run the tests — and when
21
+ you are done, `git review finish` pulls *your* edits back out onto a separate
22
+ `review-fixes/<branch>` branch (or onto the PR branch itself), keeping them
23
+ cleanly apart from the author's work. Re-review only the new commits after an
24
+ update with `--delta`.
25
+
26
+ > **All commands live under `git review <verb>`** — `git review start`,
27
+ > `git review finish`, `git review status`, and so on, the way `git bisect` and
28
+ > `git stash` group their verbs.
29
+
30
+ ## Why not just use my IDE's PR view?
31
+
32
+ Most tools let you *see* a PR. The gap this fills is *acting* on one — editing
33
+ and running it like ordinary working-tree changes, then handing your fixes back
34
+ without manual stashing or cherry-picking.
35
+
36
+ | | View the PR | Edit & run as working tree | Auto-extract your fixes | Incremental re-review (`--delta`) | Editor-agnostic |
37
+ |---------------------------------|:-----------------:|:--------------------------:|:-----------------------:|:---------------------------------:|:---------------:|
38
+ | **git-review-workflow** | ✅ | ✅ | ✅ | ✅ | ✅ |
39
+ | `gh pr checkout` / `glab` | ⚠️ plain checkout | ✅ | ❌ | ❌ | ✅ |
40
+ | JetBrains *Review Pull Request* | ✅ | ⚠️ in-IDE only | ❌ | ❌ | ❌ |
41
+ | VS Code *GitHub PR* extension | ✅ | ⚠️ in-IDE only | ❌ | ❌ | ❌ |
42
+ | GitHub / GitLab web UI | ✅ | ❌ | ❌ | ⚠️ partial | ✅ |
43
+
44
+ Because the PR is just staged changes, anything that reads a Git diff sees all
45
+ of it — including AI coding agents like Claude Code or Codex that have no
46
+ PR-review feature of their own. Point one at the staged diff and it can review or
47
+ fix the whole PR in place.
48
+
49
+ And for the small stuff — a rename, a typo, a clearer variable name — fixing it
50
+ yourself is faster and less bureaucratic than leaving a comment and waiting for a
51
+ round-trip, especially when you are already looking at the PR in your editor.
52
+ Because your edits are extracted automatically, the fix costs about the same as
53
+ the comment would have. Or hand the staged diff to an agent and have it make the
54
+ change for you.
55
+
56
+ If you mostly *comment*, your IDE's native PR panel is enough. If you review by
57
+ editing and running the code — in any editor or agent — this is the gap it fills.
58
+
59
+ ## Quick start
60
+
61
+ ```sh
62
+ # 1. Install (needs Node.js; see Installation for Homebrew and a no-Node option)
63
+ npm install -g git-review-workflow
64
+
65
+ # 2. Tell it where PRs are integrated, once per repo
66
+ git config reviewworkflow.base develop
67
+
68
+ # 3. Stage a PR branch as a single diff, then open the repo in your IDE
69
+ git review start feature/login
70
+ # ...read and edit the staged diff in your editor, run tests...
71
+ git review finish # extract your edits onto review-fixes/feature/login
72
+ ```
73
+
74
+ Prefer Homebrew, a native Windows (PowerShell) installer, or an install that
75
+ does not need Node? See [Installation](#installation). For the full flow —
76
+ re-reviewing updates, walking a PR commit by commit, cleanup — see
77
+ [Typical workflow](#typical-workflow).
78
+
79
+ ## Installation
80
+
81
+ These commands plug into `git` as a single subcommand — you run them as
82
+ `git review start`, `git review finish`, and so on. Pick whichever method matches
83
+ your setup. The package-manager options are the easiest and **set up your `PATH`
84
+ for you**.
85
+
86
+ ### npm (recommended)
87
+
88
+ If you have [Node.js](https://nodejs.org), this is the one-command install. It
89
+ puts `git review` on your `PATH` for you and works on Linux, macOS and Windows
90
+ (on Windows the commands still run under Git Bash):
91
+
92
+ ```sh
93
+ npm install -g git-review-workflow
94
+ ```
95
+
96
+ Update with `npm install -g git-review-workflow@latest`; uninstall with
97
+ `npm uninstall -g git-review-workflow`. Tab completion is set up the same way as
98
+ the other non-Homebrew installs — see the note below.
99
+
100
+ ### Homebrew (macOS / Linux)
101
+
102
+ ```sh
103
+ brew tap EzeVillo/git-review-workflow https://github.com/EzeVillo/git-review-workflow
104
+ brew install EzeVillo/git-review-workflow/git-review-workflow
105
+ ```
106
+
107
+ Tab completion is configured automatically. To update to the latest release:
108
+ `brew upgrade git-review-workflow`.
109
+
110
+ ### Windows (PowerShell)
111
+
112
+ You still need [Git for Windows](https://gitforwindows.org), which provides the
113
+ shell these commands run in. Open PowerShell and run:
114
+
115
+ ```powershell
116
+ irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.ps1 | iex
117
+ ```
118
+
119
+ This installs the command into `~\.local\bin` and adds that folder to your user
120
+ `PATH` automatically. Open a new terminal after it finishes. Re-run to update; to
121
+ uninstall:
122
+
123
+ ```powershell
124
+ irm https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.ps1 | iex
125
+ ```
126
+
127
+ (If you have Node, `npm install -g git-review-workflow` works on Windows too —
128
+ the commands still run under Git Bash either way.)
129
+
130
+ ### One-line install (Linux, macOS, WSL, Git Bash)
131
+
132
+ No package manager? This downloads the command and installs it into
133
+ `~/.local/bin` — you don't need to clone the project first:
134
+
135
+ ```sh
136
+ curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-install.sh | sh
137
+ ```
138
+
139
+ Re-run to update (always installs the latest release). To uninstall (pass the
140
+ same `PREFIX` if you overrode it):
141
+
142
+ ```sh
143
+ curl -fsSL https://raw.githubusercontent.com/EzeVillo/git-review-workflow/main/web-uninstall.sh | sh
144
+ ```
145
+
146
+ <details>
147
+ <summary>From a downloaded copy</summary>
148
+
149
+ If you cloned or downloaded the project, open its folder in a terminal and run:
150
+
151
+ ```sh
152
+ ./install.sh
153
+ ```
154
+
155
+ This installs the `git review` dispatcher into `~/.local/bin` (change the
156
+ location with `PREFIX=/usr/local/bin ./install.sh`). The verbs travel beside it
157
+ as private helpers, not as separate commands on your `PATH`. Undo it any time
158
+ with `./uninstall.sh`. To update, just `git pull` inside the repo — the symlink
159
+ picks up changes automatically.
160
+ </details>
161
+
162
+ <details>
163
+ <summary>"command not found" — adding <code>~/.local/bin</code> to your PATH</summary>
164
+
165
+ Your `PATH` is the list of folders your terminal searches when you type a
166
+ command. Homebrew, npm and the PowerShell installer add their folder for you. The
167
+ one-line and manual installs use `~/.local/bin`, which is already on the `PATH`
168
+ on most systems. If it isn't, the installer prints a note — add it **once** by
169
+ pasting one line into your shell's config file:
170
+
171
+ | If your terminal uses… | Add this line to the file… | The line to add |
172
+ |-----------------------------------|----------------------------------|----------------------------------------|
173
+ | **bash** | `~/.bashrc` | `export PATH="$HOME/.local/bin:$PATH"` |
174
+ | **zsh** (default on recent macOS) | `~/.zshrc` | `export PATH="$HOME/.local/bin:$PATH"` |
175
+ | **fish** | *(no file — just run this once)* | `fish_add_path ~/.local/bin` |
176
+
177
+ Not sure which one you use? Run `echo $0`. After editing the file, **open a new
178
+ terminal** (or `source` the file). Run `git review -h` to confirm.
179
+ </details>
180
+
181
+ <details>
182
+ <summary>Tab completion (manual installs)</summary>
183
+
184
+ Homebrew sets this up for you. Otherwise, tell your shell to load the matching
185
+ file on start. Replace `/path/to/git-review-workflow` with where you downloaded
186
+ the project.
187
+
188
+ ```sh
189
+ # bash — in ~/.bashrc
190
+ source /path/to/git-review-workflow/completions/git-review-workflow.bash
191
+
192
+ # zsh — in ~/.zshrc
193
+ source /path/to/git-review-workflow/completions/git-review-workflow.zsh
194
+
195
+ # fish — copy into fish's completions folder (no config line needed)
196
+ cp /path/to/git-review-workflow/completions/git-review-workflow.fish \
197
+ ~/.config/fish/completions/
198
+ ```
199
+
200
+ Then open a new terminal. Typing `git review ` and pressing **Tab** now offers
201
+ the verbs; `git review start ` offers your branch names.
202
+ </details>
203
+
204
+ <details>
205
+ <summary>Git Bash on Windows — SSL error during install?</summary>
206
+
207
+ If you see `schannel: next InitializeSecurityContext failed` or a
208
+ `revocation check` message, your Git for Windows is using the Windows SSL
209
+ backend. Fix it once, then re-run the installer:
210
+
211
+ ```sh
212
+ git config --global http.sslBackend openssl
213
+ ```
214
+
215
+ </details>
216
+
217
+ ## Commands
218
+
219
+ > **How to read the syntax:** `<x>` is **required**, `[x]` is **optional**, and
220
+ > `a | b` means **pick one, not both**.
221
+
222
+ Every command is a verb under `git review`. Run `git review -h` for the list, or
223
+ `git review <verb> -h` for one verb's details.
224
+
225
+ | Command | What it does |
226
+ |----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
227
+ | `git review [-h \| --version]` | List all verbs or print the installed version. |
228
+ | `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). |
229
+ | `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. |
230
+ | `git review next` / `git review prev` | Move a `--step` review to the next / previous commit. |
231
+ | `git review status` | Show the state of the review on the current branch. |
232
+ | `git review list` | List every review in progress and every saved one (current branch marked `*`). |
233
+ | `git review save` | Pause the current review as `review-saved/<branch>` and return to where you started. |
234
+ | `git review continue [branch]` | Resume a review saved with `git review save`. |
235
+ | `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. |
236
+ | `git review preview [--stat]` | Show the edits you have made so far — the diff `finish` would extract — without committing or switching branch. |
237
+ | `git review abort` | Cancel the current review and return to where you started. |
238
+ | `git review clean [branch]` | Delete the `review/*` and `review-fixes/*` branches for `<branch>`, or all of them. |
239
+ | `git review forget --delta (<branch> \| --all \| --stale [--dry-run])` | Discard the `--delta` marker for one branch, all of them, or only stale ones. |
240
+ | `git review forget --saved (<branch> \| --all) [--dry-run]` | Discard a review saved with `git review save`. |
241
+
242
+ ### `git review start`
243
+
244
+ Has two independent axes — **range** (where the review starts) and **layout**
245
+ (`--step` or not), which compose freely.
246
+
247
+ - `<branch>` — the branch to review. **Omit it to review the branch you currently
248
+ have checked out** — git's own default (like `push`, `status`, `log`). It only
249
+ resolves the name; the mode is still chosen by flags, so pair the omitted branch
250
+ with `--local` to review your local work. Without `--local` it reviews
251
+ `origin/<branch>` — if that differs from your checked-out branch you get a note,
252
+ since you would be reviewing a different snapshot than you have. With no branch,
253
+ fails on a detached HEAD or while on a `review/*` branch.
254
+ - `base` — commit-ish to diff against: a branch, a **tag**, or a commit. Taken
255
+ from `reviewworkflow.base` (see below); a positional argument overrides it.
256
+ **Required for a full review** — there is no built-in default, so a full review
257
+ with no base set fails and asks you to configure one. Not used with `--delta` or
258
+ `--from`, which carry their own starting point — passing an explicit base
259
+ alongside them is an error (a base from config is simply ignored).
260
+ - `--base <base>` — the base to diff against, as a flag. Use it to pass a base
261
+ while letting `<branch>` default to the current branch — e.g.
262
+ `git review start --base develop` reviews the branch you are on against
263
+ `develop` (the lone positional is always taken as `<branch>`, so the flag is how
264
+ you reach the base without naming the branch). Cannot be combined with a
265
+ positional base.
266
+ - `--delta` — review only the commits added **since your last review** of this
267
+ branch, instead of the whole PR. Perfect for re-reviewing an updated PR. The
268
+ recorded tip survives `git review clean`, so this works even after you deleted
269
+ the review branches; discard it explicitly with `git review forget --delta`.
270
+ - `--from <commit>` — review only the commits **after `<commit>`**. Handy when
271
+ there is no recorded review to delta from, or to pick an exact starting point.
272
+ Mutually exclusive with `--delta`.
273
+ - `--step` — review the range **one commit at a time** (combine with `--delta`
274
+ or `--from` to walk just those commits). You start on the first commit after
275
+ the merge-base; the command prints its author message. Edit files, then run
276
+ `git review next` to bank your edits and move to the next commit with a clean
277
+ tree. When the commits run out, run `git review finish` and all your banked
278
+ edits are replayed onto the PR tip — exactly as in a whole-PR review.
279
+ - `--local` — review your **local** branches directly, without fetching. The
280
+ review is built from your local `<branch>` and diffed against your local base,
281
+ so it works offline and lets you review your own work before pushing. It keeps
282
+ its own `--delta` marker, separate from the remote one, so local and remote
283
+ reviews of the same branch name never overwrite each other's progress.
284
+ - Always updates from `origin` first and **fails** if it cannot (unless
285
+ `--local`). The review is built from `origin/<branch>`, never a stale local
286
+ copy. If a local branch of the same name points somewhere else, it prints a
287
+ note: the review reflects the remote, not your checkout, and a later
288
+ `git review finish --onto-source` would refuse until your local branch matches.
289
+ - Refuses to run if you have local changes — start from a clean branch.
290
+ - **Merges of the base branch are excluded.** If the author merged the base
291
+ (e.g. `develop`) into the PR, that merged-in content is left out of the review
292
+ in every mode, so you only see the author's own changes.
293
+ - `--` ends option parsing, the usual git convention: everything after it is
294
+ treated as a positional argument, so a branch whose name starts with `-` can
295
+ still be reviewed (e.g. `git review start -- --weird develop`).
296
+
297
+ ### `git review compare`
298
+
299
+ Stage the diff between two commit-ish — two tags, two commits, two branches — as
300
+ one read-only review, so you can read it inline or walk it commit by commit with
301
+ the same UX as a real review, without `git diff | less`.
302
+
303
+ ```sh
304
+ git review compare v1.0 v2.0 # stage the diff between two releases
305
+ git review compare v1.0 v2.0 --step # ...and walk it commit by commit
306
+ ```
307
+
308
+ - It diffs `<a>..<b>`: `<a>` is the lower bound (where the review starts), `<b>`
309
+ the tip whose content fills the working tree. Both are resolved to commits, so
310
+ tags and raw SHAs work, not only branch names.
311
+ - It is **read-only by design**. The whole edit→finish half of the workflow needs
312
+ a writable branch to write back to, and a tag or a commit is not one — so
313
+ `git review finish` on a compare refuses explicitly ("this review is read-only,
314
+ there is nothing to write back"). Use `git review abort` to end it.
315
+ - `--step` walks it one commit at a time, exactly like `git review start --step`,
316
+ with `git review next` / `git review prev`.
317
+
318
+ ### `git review next` / `git review prev`
319
+
320
+ Move a `--step` review forward or backward. Each move banks the current commit's
321
+ edits and restores any edits you had banked on the commit you move to, so you can
322
+ walk back and forth without losing work.
323
+
324
+ ### `git review status`
325
+
326
+ Shows the current review: source PR, mode, and — in `--step` mode — which commit
327
+ you are on (`[k/N]`) and which steps have banked edits.
328
+
329
+ ### `git review list`
330
+
331
+ Shows *every* `review/*` branch in progress at once (with its source PR, mode and
332
+ step position). Reviews paused with `git review save` are listed too, under
333
+ `saved`. The branch you are currently on is marked with a `*`.
334
+
335
+ ### `git review save` / `git review continue`
336
+
337
+ `git review save` lets you put a review aside and pick it up later. It turns the
338
+ current `review/<branch>` into `review-saved/<branch>` and returns you to the
339
+ branch you started from, carrying everything needed to resume exactly where you
340
+ left off:
341
+
342
+ - In whole-PR mode, the staged PR diff and your uncommitted edits.
343
+ - In `--step` mode, the commit you are on, its edits, and every edit you have
344
+ banked on the other commits. The banked-edit refs are moved out of
345
+ `refs/review-edits/` (which `git review clean` prunes) into
346
+ `refs/review-saved-edits/`, so a `git review clean` never touches a saved review.
347
+
348
+ `git review continue` turns `review-saved/<branch>` back into the active
349
+ `review/<branch>` and restores that exact state — in `--step` mode it drops you
350
+ back on the same commit, with `git review next` / `git review prev` working as
351
+ before. With no argument it resumes the only saved review, or lists them if there
352
+ is more than one; name a branch to pick a specific one.
353
+
354
+ Starting a fresh `git review start` on a branch that already has a saved review
355
+ is refused, so you do not silently lose the paused one — resume it or discard it
356
+ with `git review forget --saved` first.
357
+
358
+ ### `git review finish`
359
+
360
+ - Default — create `review-fixes/<branch>` on top of the PR tip with your edits
361
+ staged, so you can review and commit them yourself.
362
+ - `--onto-source` — stage your edits on the PR branch itself instead, so you can
363
+ review and commit them yourself there.
364
+ - Either way the result stays local — review it and push it yourself when ready.
365
+ - `--resume` — in `--step` mode, if banked edits overlap the PR tip, the replay
366
+ leaves conflict markers and stops. Resolve them in the working tree, then run
367
+ `git review finish --resume` (with the same flags) to continue.
368
+ - `--abort` — undo the last finish and drop you back on `review/<branch>` exactly
369
+ where you were editing, the same way `git merge --abort` backs out a merge. It
370
+ refuses if you have changed the finish branch since, so you do not lose work;
371
+ add `--force` to discard those changes and abort anyway.
372
+ - Refuses on a read-only `git review compare` — there is no writable branch to
373
+ write your edits back to.
374
+
375
+ ### `git review preview`
376
+
377
+ Shows the edits you have made so far — the same diff `git review finish` would
378
+ extract, your review edits on top of the PR tip — but it **never commits, never
379
+ switches branch and never touches your working tree or index**, so you go straight
380
+ back to editing where you left off. Think of it as "what would `finish` give me
381
+ right now?".
382
+
383
+ - `--stat` — show a diffstat summary instead of the full diff.
384
+ - In `--step` mode it replays the current commit's edits plus every banked edit
385
+ onto the tip, exactly like `finish`. An edit that genuinely conflicts with the
386
+ tip is the one case that differs: a read-only preview cannot leave you conflict
387
+ markers, so it omits that edit and prints a note pointing you at `finish`.
388
+
389
+ ### `git review abort`
390
+
391
+ Cancels the current review in one step: it returns you to the branch you started
392
+ from, then deletes the `review/<branch>` branch and its banked edits. Because the
393
+ review was cancelled (not completed), it rolls the `--delta` marker back to your
394
+ last actual review, so a later `--delta` does not skip commits you never
395
+ reviewed.
396
+
397
+ ### `git review clean`
398
+
399
+ - With no `<branch>`, deletes every `review/*` and `review-fixes/*` branch.
400
+ - Never deletes the branch you are currently on.
401
+ - Also drops any banked commit-by-commit edit refs, even when no review branches
402
+ remain.
403
+ - Leaves the `--delta` marker untouched — discard it with `git review forget --delta`.
404
+ - Leaves saved reviews (`review-saved/*`) untouched — discard one with
405
+ `git review forget --saved`.
406
+
407
+ ### `git review forget --delta`
408
+
409
+ Discards the recorded last-reviewed tip that `--delta` relies on. The marker is
410
+ kept deliberately so `--delta` survives `git review clean`; this is how you clear
411
+ it.
412
+
413
+ - `<branch>` — forget the marker(s) for one source branch, both the remote one
414
+ and the `--local` one if present.
415
+ - `--all` — forget every recorded marker (leaves `reviewworkflow.base` alone).
416
+ - `--stale` — fetch and prune `origin`, then forget only the markers whose branch
417
+ no longer exists: remote markers whose `origin/<branch>` is gone (e.g. PRs that
418
+ were merged and deleted), and `--local` markers whose local `<branch>` is gone.
419
+ Aborts without removing anything if the fetch fails.
420
+ - `--dry-run` — with `--stale`, list what would be forgotten without doing it.
421
+ Rejected with the other modes, where the target is already explicit.
422
+
423
+ ### `git review forget --saved`
424
+
425
+ Discards a review put aside with `git review save`: deletes
426
+ `review-saved/<branch>`, its banked edits and its metadata. Because a saved review
427
+ was paused (not completed), it also rolls the `--delta` marker back to your last
428
+ actual review, the same way `git review abort` does.
429
+
430
+ - `<branch>` — discard the saved review for one source branch.
431
+ - `--all` — discard every saved review.
432
+ - `--dry-run` — list what would be discarded without discarding it.
433
+
434
+ ## Configuring the base branch
435
+
436
+ The base branch is where PRs are integrated (`develop`, `main`, `master`, …) and
437
+ varies per team, so there is no default — set it once per repository:
438
+
439
+ ```sh
440
+ git config reviewworkflow.base develop
441
+ ```
442
+
443
+ Resolution order: positional `base` argument (or `--base <base>`) →
444
+ `reviewworkflow.base`. If neither is set, a full review fails and asks you to
445
+ configure one. The base is any commit-ish — a branch, a tag (`v1.0`) or a
446
+ commit — not only a branch name.
447
+
448
+ ## Configure the remote
449
+
450
+ By default the commands fetch and push against `origin`. If you review a
451
+ repository you do not own (an `upstream`, with your `origin` as a fork, say),
452
+ point the workflow at that remote:
453
+
454
+ ```sh
455
+ git config reviewworkflow.remote upstream
456
+ ```
457
+
458
+ It affects `git review start` and `git review forget --delta --stale`. A
459
+ `--local` review ignores the remote entirely.
460
+
461
+ ### Per-repository by design
462
+
463
+ Both `reviewworkflow.base` and `reviewworkflow.remote` are plain `git config`
464
+ keys, so they are stored **per repository** (in each repo's `.git/config`). You
465
+ don't manage profiles or a shared config file — every repository you work in
466
+ keeps its own base and remote independently, and they never leak into one
467
+ another:
468
+
469
+ ```sh
470
+ # repo A: PRs land on main, fetched from origin (the default)
471
+ cd ~/project-a && git config reviewworkflow.base main
472
+
473
+ # repo B: PRs land on develop, reviewed from an upstream you don't own
474
+ cd ~/project-b
475
+ git config reviewworkflow.base develop
476
+ git config reviewworkflow.remote upstream
477
+ ```
478
+
479
+ The same applies to the `--delta` markers — they live in each repo's config too.
480
+ If you want a fallback that applies to *all* your repos, set it globally
481
+ (`git config --global reviewworkflow.base main`); a per-repo value overrides it,
482
+ and a positional `base` argument overrides both.
483
+
484
+ ## Typical workflow
485
+
486
+ ```sh
487
+ git config reviewworkflow.base develop # once per repo
488
+
489
+ git review start feature/login # stage the whole PR
490
+ # ...open the repo in your IDE, read the staged diff, edit inline, run tests...
491
+ git review finish # extract fixes to review-fixes/feature/login
492
+ git diff --cached && git commit -m "address review comments"
493
+ git review clean feature/login # tidy up
494
+
495
+ # Re-review after the author pushes more commits:
496
+ git review start feature/login --delta # only the new commits
497
+ git review start feature/login --delta --step # ...and walk them one by one
498
+
499
+ # Or walk the PR commit by commit from the start:
500
+ git review start feature/login --step # start on the first commit
501
+ # ...edit, then...
502
+ git review next # bank edits, move to the next commit
503
+ git review next # ...until "no more commits"
504
+ git review finish # replay all your edits onto the tip
505
+
506
+ # Pick an explicit starting commit:
507
+ git review start feature/login --from a1b2c3d
508
+
509
+ # Review the branch you are already on (omit the name):
510
+ git switch feature/login && git review start # vs the configured base
511
+ git review start --base develop # ...or against an explicit base
512
+
513
+ # Compare against a tag instead of a branch:
514
+ git review start feature/login v1.0
515
+
516
+ # Compare two releases read-only:
517
+ git review compare v1.0 v2.0
518
+
519
+ # Review your own local branch before pushing, offline:
520
+ git review start feature/login --local
521
+ ```
522
+
523
+ ## Requirements
524
+
525
+ - Git 2.23+ (uses `git switch`). Git 2.38+ is recommended: excluding base
526
+ content that was merged into the PR uses `git merge-tree --write-tree`, and on
527
+ older git that one step is skipped (the merged base content would then show in
528
+ `--delta`/`--from`).
529
+ - A remote named `origin` (or whatever you set with `reviewworkflow.remote`).
530
+ - A POSIX shell. On Linux and macOS this is the default. On Windows the commands
531
+ run under Git Bash or WSL, not in `cmd.exe` or PowerShell.
532
+
533
+ ## Contributing
534
+
535
+ Bug reports, fixes and ideas are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
536
+ for how to run the tests and the release process.
537
+
538
+ ## License
539
+
540
+ [MIT](LICENSE) © EzeVillo