Git

The plugin runs git in the environment's workspace on its machine. The Diff tab, the composer's changed-files segment and the Info tab read from it.

bb git status <environment-id> [--merge-base-branch <branch>] [--json]
bb git branches <environment-id> [--query <text>] [--limit <n>] [--json]
bb git diff <environment-id> --target <target> [--json]
bb git files <environment-id> --target <target> [--ignore-whitespace] [--json]
bb git file <environment-id> --target <target> --path <path> --side old|new [--json]
bb git patch <environment-id> --target <target> --path <path>... [--json]
bb git viewed list|mark|unmark|clear <environment-id> --target <target> ...

• <target> is uncommitted, branch_committed, all or commit. Branch targets take --merge-base-branch; commit takes --sha. file takes --merge-base-ref <sha> for branch targets instead.
• status includes ahead/behind counts only with --merge-base-branch. Each file list holds at most 200 entries (tracked changes first); fileCount is the total. When squash-merge detection hits its limits (1,000 commits, 1 second), mergeBase.squashMergeCheckComplete is false and the counts may include commits that were already squash-merged.
• --ignore-whitespace counts and diffs with git -w: whitespace-only files stay listed with +0 -0 and get an empty patch.
• files --json reports each file's revision: old and new git modes and blob ids (<oldMode>:<oldBlob>:<newMode>:<newBlob>). Any content or mode edit, including whitespace, changes it; staging does not.
• Viewed is stored per environment and diff target. A file shows as Viewed only while its current revision equals the stored one, so new edits un-view it. viewed mark records the current revision unless you pass --revision; viewed list --path takes up to 500 paths. Mutations print { "ok": true } with --json.
• The old bb environment status|diff|diff-files|diff-file|diff-patch|branches|diff-viewed commands still run and print the bb git command that replaced them.

showGitChanges (default true) shows the composer's changed-files segment; turn it off with bb plugin config bb--git set showGitChanges false. showCommitButton (default false) shows the thread header's Commit action; turn it on with bb plugin config bb--git set showCommitButton true.

Other plugins read the same data through RPC. status is a keyed read: pass environment ids and get one row per id, refreshed after the workspace's files or refs change.

experimental_useRpcKeyedQuery({
  pluginId: "bb--git",
  contract: gitRpcContract,
  method: "status",
  keys: [environmentId],
});

bb plugin rpc inspect bb--git prints the input and output schemas.

Branch targets resolve the requested ref first, then fall back to origin/<branch>. If no merge base with HEAD resolves, diff reads report an error instead of an empty diff.