Review a pull request locally with a guided reading order.

A PR can touch many files without explaining where to start. A walkthrough adds a reading order, a reason for each entry, and the parts that need attention.

git-review-workflow follows that order while the complete PR stays available as staged changes in your working tree. You can inspect the implementation and leave observations without editing code. Run tests or make corrections when useful; finishing extracts any corrections onto a separate branch.

When a checkout is enough

If you just need to run a GitHub PR, GitHub CLI's gh pr checkout checks it out for you:

gh pr checkout 123

You can then inspect the project and run its tests. The workflow below adds a reading walkthrough, a staged view of the whole PR, and extraction of any corrections you make during the review.

Before you start

You need Git 2.23 or newer, a configured remote, and a POSIX shell. On Windows, run these commands in Git Bash or WSL. The npm installation also requires Node.js and npm.

This example assumes the PR branch is feature/login, the merge target is main, and both branches exist on origin. Replace those names with your actual branches and start with a clean working tree.

These commands take branch names. The 123 above belongs to GitHub CLI; git review start takes feature/login, rather than a PR number or URL.

Install and configure

npm install -g git-review-workflow
git review --version
git config reviewworkflow.base main

The base setting applies to this repository. Choose the branch your team merges PRs into, such as main or develop. For Homebrew, PowerShell, or installation without Node, see the installation guide.

Open the whole PR

git review start feature/login

By default, this fetches the remote and reviews its branch tip. It creates review/feature/login with HEAD at the merge-base, and stages the PR's complete change in the working tree.

git diff --cached

That diff is now the PR you are reviewing. Open the project in your editor, follow calls outside the diff, and run the project's own setup and test commands.

You can also start from a VS Code, JetBrains, or Visual Studio panel, or the terminal interface. They drive the same workflow.

Check behavior and correct it if needed

Suppose the PR changes a limit check and you suspect it allows one attempt too many. Change the condition in your editor and run the relevant test.

The test command depends on the project. A Node project might use npm test; follow the repository's own instructions.

git review preview

This previews the corrections you have made relative to the PR's code. It lets you check what will be extracted before you finish.

Finish the review

git review finish
git diff --cached

The default result is review-fixes/feature/login, based on the PR tip, with any corrections staged. Review that diff before committing. The result stays local; you choose when to commit and how to share it with the author.

A guided review can also finish without code corrections. Reading the change and leaving observations is a complete use of the workflow.

Give a large PR a reading order

A walkthrough is a Markdown file containing an order for reading the changed files and a reason for each entry. For a login change, the order could be:

1. Read the policy to understand the intended limit.
2. Read the middleware that enforces it.
3. Read the boundary tests to check the behavior.

An author or coding agent can prepare that walkthrough alongside the change. If the PR has none, the reviewer can prepare a local reading order. The walkthrough introduction explains both paths.

The walkthrough proposes a route through the code. You still inspect the implementation and verify its behavior.