Workspace, Range, and Commit Review Modes in Open Code Review: A Complete Comparison

Open Code Review (OCR) provides three distinct review modes—Workspace, Range, and Commit—that differ in how they source Git changes, whether they support session resumption, and which files they include in the analysis.

Open Code Review (OCR) is a CLI tool that analyzes Git repositories for code quality issues. When you run ocr review, the tool automatically selects one of three review modes based on the flags you provide, with each mode implementing different diff generation strategies in internal/diff/git.go.

How Review Mode Selection Works

OCR determines which mode to activate by checking for --from/--to or --commit flags. If neither is specified, it defaults to Workspace mode. This branching logic resides in internal/diff/git.go, where the provider initializes as either ModeWorkspace, ModeRange, or ModeCommit.

The Three Review Modes Explained

Workspace Mode (Default)

Workspace mode activates when you run ocr review without --from, --to, or --commit flags. According to the source code in internal/diff/git.go, this mode aggregates staged, unstaged, and untracked changes from your working directory. It executes git diff --cached for staged files, git diff for unstaged modifications, and reads untracked files directly from disk.

However, Workspace mode has a critical limitation: it does not support resume functionality. As enforced in internal/session/resume.go, attempting to resume a workspace review returns the error resume requires --from/--to or --commit; workspace resume is not supported because the working directory lacks an immutable reference point.

Range Mode (--from and --to)

Range mode activates when both --from <ref> and --to <ref> flags are provided. This mode reviews the commit range between two Git references (e.g., main..feature). The implementation first computes the merge-base of the two refs using Provider.mergeBase, then generates a diff between that base and the target ref.

Range mode supports session resumption. Because both references are immutable Git objects, OCR can persist the session state and resume later using ocr review --resume <session-id>.

Commit Mode (--commit)

Commit mode activates with the --commit <hash> (or -c <hash>) flag. This mode uses git show <hash> to review the changes introduced by a single commit. The provider is created via NewCommitProvider in internal/diff/git.go.

Like Range mode, Commit mode supports resumption since a commit hash represents an immutable reference. This makes it ideal for reviewing specific changes without surrounding context.

Technical Implementation Differences

The core differentiation lives in internal/diff/git.go. The ModeWorkspace branch handles working directory state, ModeRange implements merge-base calculation and range diffing, and ModeCommit utilizes NewCommitProvider for single-commit analysis.

Resume capability is gated in internal/session/resume.go, which explicitly rejects workspace sessions while allowing Range and Commit modes to persist and restore their state. The VS Code extension references these modes through the ReviewMode enum defined in extensions/vscode/src/shared/types.ts.

CLI Usage Examples

Review your current working directory (Workspace mode):

# Review all staged, unstaged, and untracked files

ocr review

Compare two branches (Range mode):

# Review changes between main and feature branch

ocr review --from main --to feature

Inspect a specific commit (Commit mode):

# Review commit abc1234

ocr review --commit abc1234

Resume an interrupted review:

# List available sessions

ocr session list

# Resume a specific session (only for Range or Commit modes)

ocr review --resume <session-id>

Summary

• Workspace mode is the default for reviewing working directory changes including untracked files, but cannot be resumed due to mutable state.
• Range mode requires --from and --to references, computes merge-base for accurate diffs, and fully supports session resumption.
• Commit mode targets single commits via --commit, offers immutable references for reliable resumption, and uses git show for diff generation.
• Resume functionality is explicitly disabled for Workspace mode in internal/session/resume.go while implemented for Range and Commit modes.
• All three modes are defined in internal/diff/git.go and documented in pages/src/content/docs/en/cli-reference.md.

Frequently Asked Questions

Can I resume a review if I close my terminal?

Only if you used Range or Commit mode. Workspace mode reviews cannot be resumed because the working directory state changes constantly. Use ocr review --resume <session-id> for Range or Commit reviews as documented in the CLI reference.

Why does Workspace mode include untracked files while other modes do not?

Workspace mode reads the actual working directory state from disk, including files not yet added to Git. Range and Commit modes operate on Git objects (commits and trees), which only track files explicitly added to the repository according to the implementation in internal/diff/git.go.

What happens if I specify both --commit and --from/--to flags?

OCR prioritizes the flags according to its internal logic in internal/diff/git.go. Typically, explicit commit or range flags override the default workspace behavior, but you should specify only one mode to avoid ambiguity as noted in the CLI documentation.

Does the VS Code extension support all three modes?

Yes. The extension uses the ReviewMode enum defined in extensions/vscode/src/shared/types.ts, which includes all three modes and maps them to the corresponding CLI flags when invoking OCR.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}