Class: Branches¶

Branch manager for a Table.

Unlike tags, create and checkout return a new Table handle scoped to the branch; writes on it do not affect main.

Methods¶

checkout()¶

checkout(name, version?): Promise<Table>

Check out an existing branch and return a handle scoped to it.

With version set, the returned handle is pinned to that version of the branch (a read-only, detached view); otherwise it tracks the branch's latest and stays writable.

Parameters¶

name: string
version?: number

Returns¶

Promise<Table>

create()¶

create(
   name,
   fromRef?,
   fromVersion?): Promise<Table>

Create a branch and return a handle scoped to it.

Parameters¶

name: string Name of the new branch.
fromRef?: string Source branch to fork from. Defaults to main.
fromVersion?: number A specific version on fromRef. Defaults to latest.

Returns¶

Promise<Table>

delete()¶

delete(name): Promise<void>

Delete a branch.

Parameters¶

name: string

Returns¶

Promise<void>

diff()¶

diff(fromBranch): Promise<BranchDiff>

Compare a branch against main without modifying either branch.

Parameters¶

fromBranch: string

Returns¶

Promise<BranchDiff>

list()¶

list(): Promise<Record<string, BranchContents>>

List all branches, mapping name to branch metadata.

Returns¶

Promise<Record<string, BranchContents>>

merge()¶

merge(fromBranch, dryRun): Promise<MergeBranchResult>

Merge a branch into main.

Set dryRun to true to preview the merge. A rejected merge resolves with status: "rejected" instead of throwing.

Parameters¶

fromBranch: string Branch to merge from.
dryRun: boolean = false When true, only preview the merge. Defaults to false.

Returns¶

Promise<MergeBranchResult>