Reviews
A branch holds a stack of reviews, and each review is a contiguous slice of
commits. The gs review subtree is how you shape that stack after the commits
exist: carve a range into a review, split one in two, fold two into one, reorder
them, or rebase them onto a new base. This page covers the shape-changing verbs
plus the read-only inspectors (show, diff, for, list) and
gs autostack, which builds the whole stack for you.
Every command below accepts --repo <name> (default: inferred from the origin
remote) and the shared output flags (--plain, --json, --no-color,
--verbose) documented in CLI conventions. Review ids
like r1 and commit refs like c3 follow the forms in
reference syntax. To carve a single commit into a
review in one step, use gs commit --review -t, documented in
commits and syncing.
gs review create#
Carve a new review out of a range of commits. Pushes automatically unless you
pass --no-push.
gs review create [options] [range]
| Flag | Description |
|---|---|
--title, -t |
Review title. For a single-commit range it defaults to the commit subject; for a multi-commit range a title is required. |
--last N |
Use the last N uncovered commits as the range instead of a positional argument. |
--fixes N |
Issue number this stack fixes (repeatable). The issue closes when every review on the branch is landed or abandoned. |
--automerge |
Land the whole stack automatically once every review is approved and CI is green. Turns on when the stack is pushed; --automerge=false turns it off. See gs stack automerge. |
--no-push |
Carve the review locally without pushing. Push when ready. |
--allow-dirty |
Push even when the tree has uncommitted or untracked changes. They stay local. |
--squash |
Land the review as one commit (the default). |
--rebase |
Land the review's commits as they are, on top of the base branch. |
--title, -t--last N--fixes N--automerge--automerge=false turns it off. See gs stack automerge.--no-push--allow-dirty--squash--rebaseThe [range] argument selects the commits to carve. Omit it and create uses
the uncovered commits above the last review. See
reference syntax for the full range grammar. The
landing-strategy flags (--squash, --rebase) are mutually exclusive and are
covered in landing and cleanup.
Pushing happens in two moves. The first create on a fresh branch pushes the
branch when the server is missing the commits. The create whose range reaches
the branch tip pushes the manifest and allocates patchset 1 for every review
carved on the branch. A mid-stack carve (one that leaves uncovered commits above
it) cannot push its manifest yet, so it prints push deferred and waits for the
carve that reaches the tip.
# Carve the bottom two commits, then the rest of the branch.
gs review create c1..c2 -t "billing: subscription model"
gs review create -t "billing: POST /api/billing endpoint" --fixes 214
An unpushed carve lives only in the local manifest. If you gs checkout r1
or switch branches before pushing, the deferred carves can be dropped. Push
the manifest (gs push, or the final create) before any gs checkout rN.
gs review split#
Split one review into two at a commit. The --at commit becomes the tip of the
named review; the commits above it form a new review on top. Pushes the updated
manifest automatically unless you pass --no-push.
gs review split [options] <review-id>
| Flag | Description |
|---|---|
--at |
Endpoint to split at (c<n>, a sha, or HEAD~k). |
--title, -t |
Title for the new upper review. Defaults to the subject of its top commit. |
--no-push |
Split in the local manifest only. Push when ready. |
--allow-dirty |
Push even when the tree has uncommitted or untracked changes. They stay local. |
--atc<n>, a sha, or HEAD~k).--title, -t--no-push--allow-dirtyThe lower review keeps its id and its title. The new upper review is created
with the subject of its top commit as the title, so it is never carved empty.
Pass -t to set a better one at split time, or fix it afterward with
gs review retitle.
gs review split r2 --at c4 -t "api: pagination"
The server validates --at against the review's pushed tip. If the review
has local commits above its pushed tip that you have not pushed yet, a valid
split point can be rejected as if it were the tip. Run gs push first, then
split.
gs review show#
Show a review's details: title, author, reviewers, state, and patchsets.
gs review show [<review-id>]
This command takes no flags beyond the shared --repo. Omit the review id to
show the review at HEAD.
gs review show r1
gs review diff#
Show a review's patch. Omit the id to diff the review at HEAD.
gs review diff [<review-id>]
| Flag | Description |
|---|---|
--patchset N |
Show a specific patchset (default: the latest). |
--patchset Ngs review diff r2 --patchset 1
gs review for#
Find the review that landed a commit. Prints its id, title, status, and URL.
gs review for <commit>
<commit> is a SHA, full or abbreviated, from git log, git blame, or the
GitHub mirror, or any revision your clone resolves (HEAD~2, a tag). It works
for every land kind: a squash commit, any commit a rebase land carried in,
including one in the middle of the review, and a merge commit from before
history went linear. A commit that did not
land through a review (pushed straight to the branch, or from before the repo
moved to GitStack) exits non-zero with that message. --json prints the
answer as JSON.
gs review for 4b3316fa
R12 billing: proration service
status: landed (squash) 2026-10-13T15:04:05Z
url: https://gitstack.sh/acme/api/reviews/R12
commit: 4b3316fa1c2e is the review's landed commitCommits a land creates also carry a Reviewed-on: trailer with the review's
URL; see gs submit.
gs review retitle#
Change a review's title. Aliased as gs review edit.
gs review retitle [options] <review-id>
| Flag | Description |
|---|---|
--title, -t |
New review title. |
--title, -tOmit -t and gs opens your editor to write the title.
gs review retitle r3 -t "auth: rotate refresh tokens"
gs review fold#
Fold two adjacent reviews into one. Pass the lower review first, then the upper.
Pushes the updated manifest automatically unless you pass --no-push.
gs review fold [options] <lower-review-id> <upper-review-id>
| Flag | Description |
|---|---|
--no-push |
Fold in the local manifest only. Push when ready. |
--allow-dirty |
Push even when the tree has uncommitted or untracked changes. They stay local. |
--no-push--allow-dirtyThe two reviews must sit next to each other in the stack; you cannot fold across a review in between.
gs review fold r1 r2
gs review reorder#
Reorder the reviews in the stack. List every review in the stack in the new bottom-up order. Pushes the updated manifest automatically.
gs review reorder <review-id> <review-id> ...
This command takes no flags beyond the shared --repo. Give the full order, not
a partial move: the ids you pass become the stack, bottom first.
# Move r3 to the bottom of a three-review stack.
gs review reorder r3 r1 r2
gs review rebase#
Rebase a review, or the whole stack, onto another branch. The rebase runs on the server.
gs review rebase [options] [<review-id>]
| Flag | Description |
|---|---|
--stack |
Rebase every review in the stack. |
--onto |
Target branch to rebase onto. |
--stack--ontoPass a review id to rebase one review, or --stack to move the whole stack.
--onto names the branch to land on.
gs review rebase --stack --onto main
gs review abandon#
Abandon a review. The commits stay in your local history; the review is closed on the server.
gs review abandon [options] <review-id>
| Flag | Description |
|---|---|
--reason |
Reason for abandoning, recorded on the review. |
--reasongs review abandon r4 --reason "folded into r2"
gs review list#
List reviews. By default it shows open reviews where you are the author or a reviewer.
gs review list [options]
| Flag | Description |
|---|---|
--all |
Include merged and abandoned reviews (default: open only). |
--mine |
Reviews you authored. |
--reviewing |
Reviews you are a reviewer on. |
--status |
Filter by state: open, merged, or abandoned. |
--branch |
Filter to one branch. |
--author |
Filter by author ULID. |
--all--mine--reviewing--statusopen, merged, or abandoned.--branch--authorgs review list --mine --status open
gs review list --branch add-billing --all
gs autostack#
Decompose the current branch into a clean stack of reviews in one command. Autostack proposes a split, validates it against the repo's build, test, and format commands, applies fixes across a few rounds, then carves and pushes the reviews.
gs autostack [options]
| Flag | Description |
|---|---|
--reset |
Abandon the branch's existing reviews and re-autostack a pushed branch. |
--resetAutostack needs a clean working tree. It rewrites the branch in place to lay out the new stack, then pushes the branch, creates the reviews, and pushes the manifest. If the split flagged any open questions, they are posted as comments on the reviews. When it finishes it prints the branch, the review ids, and the count of flagged questions.
If the branch already has reviews, autostack refuses so it does not clobber
existing work. Re-run with --reset to abandon those reviews and rebuild the
stack from scratch.
gs autostack
gs autostack --reset
Because it lays out a new commit sequence, autostack rewrites the branch in
place (a force-push on --reset). It saves the previous tip at
refs/autostack/backup/<branch> so you can recover if something goes wrong
mid-run.
Where to go next#
| Page | What it covers |
|---|---|
| Commits and syncing | commit, amend, push, and the one-step --review carve |
| Stacks and navigation | reading the stack and moving between reviews |
| Feedback and approvals | comments, replies, resolve, and approve |
| Landing and cleanup | submitting reviews and the landing strategy flags |
--review carve