Diff and Checkout

Review pull request changes with local checkout and diff tooling.

See Global flags for JSON output, workspace/repository selection, and display options.

bb pr checkout

Check out a pull request’s source branch locally.

bb pr checkout <id> [options]

Arguments

Argument	Description
id	Pull request ID

Options

Only global flags apply.

Examples

# Checkout PR #42 to review locally
bb pr checkout 42

# Checkout PR from specific repository
bb pr checkout 42 -w myworkspace -r myrepo

Notes

The command fetches only the pull request’s source branch, then checks it out:

• Branch in this repository: it uses the git remote that points at the repository (whatever its name, falling back to origin when no remote URL matches) and checks out <source-branch>. A new branch tracks <remote>/<source-branch>.
• Branch in a fork: it fetches from the fork’s remote if you have one, otherwise straight from the fork’s URL (same protocol as your remote), and checks it out as pr-<id>. Your own branches are never touched, even when the fork’s branch has the same name (for example main).
• Local branch already exists: it is fast-forwarded to the latest commit, and its upstream setting is left alone. Unpushed local commits on top of the pull request are kept. If the branch has diverged from the pull request, the command fails before switching branches rather than overwrite anything.

git errors, such as uncommitted changes that would be overwritten, stop the command and are reported as they are. Fetch progress is shown on stderr.

--json returns { success, pullRequestId, branch, pullRequest }, where branch is the local branch that was checked out.

---

bb pr diff

View the diff of a pull request in unified diff format.

bb pr diff [id] [options]

Arguments

Argument	Description
id	Pull request ID (optional, defaults to the open PR for the current branch)

Options

Option	Description
--color <when>	Colorize output: auto, always, never (default: auto)
--name-only	Show only names of changed files
--stat	Show diffstat (files changed, insertions, deletions)
--web	Open diff in web browser; prints the URL when stdout is not a terminal

Examples

# View diff for PR #42
bb pr diff 42

# Auto-detect PR from current branch
bb pr diff

# Show only changed file names
bb pr diff 42 --name-only

# Show statistics (like git diff --stat)
bb pr diff 42 --stat

# Open diff in browser
bb pr diff 42 --web

# Return browser URL as JSON
bb pr diff 42 --web --json

# Disable colors for piping to file or other commands
bb pr diff 42 --color never > pr-42.patch

# Get diffstat as JSON for scripting
bb pr diff 42 --stat --json

--stat output:

src/index.ts | +12 -3
src/utils.ts | +4
docs/README.md | -8

3 files changed, 16 insertions(+), 11 deletions(-)

Diffstat can be incomplete

--stat and --name-only fetch one diffstat page. For a large PR, file counts and addition/deletion totals may cover only part of the changes. For complete totals, use the paginated reporting recipe.

Notes

• When no ID is provided, the command searches for an open pull request whose source branch matches your current git branch
• --color auto colors the diff only when stdout is a terminal: green for additions, red for deletions, cyan for hunk headers. Whole lines are colored by their leading marker, there is no language-aware highlighting
• On a terminal the diff opens in your pager (less -FRX unless BB_PAGER or PAGER says otherwise). Piped output and --json are never paged
• --color never forces plain text, which is what you want when redirecting to a file or piping into another command. The global --no-color flag does the same for every command
• The value is validated before the request. A typo fails with --color must be one of: auto, always, never plus a (Did you mean never?) suggestion, rather than silently falling back
• Passing --color <when> at all turns the global color setting on, because the CLI resolves color by scanning raw argv for a --color token. bb pr diff 42 --color never still leaves the diff body uncolored, but it overrides --no-color and NO_COLOR for everything else that invocation prints. See Global Flags → Precedence summary
• -w is the global short alias for --workspace. To open the diff in a browser you must spell out --web
• For opening other Bitbucket pages (PR detail, files, commits, pipelines, settings) in the browser, see bb browse