bb dry-run

What --dry-run answers, and how far to trust it

--dry-run asks what the real run would do, without doing it. Each command's help says, under "Dry run", what it checks.

A command that changes something answers with a verdict, one effect per change it would make:

would-apply   the change would be made
no-op         nothing needs to change
would-fail    the run would be refused; the reasons say why

How far to trust a verdict is its tier, the weakest check behind it:

server-validated        Bitbucket answered the exact question
preconditions-checked   bb fetched your permission and the current state
                        and checked them
predicted               bb predicted it from partial state, or checked
                        nothing

A command that only reads runs as usual, since reading changes nothing.

Exit codes

In text, a dry run exits with the code the real run would: 0 when it would go through, and the failure's code when it would fail. So "bb pr merge 42 --dry-run && bb pr merge 42" stops at the check.

Under --json or --yaml it exits 0 whenever it reached a verdict, which is in the document, and non-zero only when it could not: 10 when Bitbucket did not answer, 12 when it was interrupted, 1 for a bug in bb.

The document

Under --json the answer is the preview member:

{"preview": {"tier": "...",
             "effects": [{"action", "target", "outcome", "reasons"}],
             "error": {...}},
 "meta": {"command": "...", "bbVersion": "..."}}

error is present exactly when the run would fail, and is what it would fail with. A command that only reads puts what it returned in preview.data.