> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bijection branch

> Fork live data, try changes, compare, apply or discard

<Warning>Branches are in beta.</Warning>

Manage branches of the selected deployment. A branch is a fork of the
deployment's committed data at a pinned revision; external calls made on it
are held and never leave it.

* Create: `bijection branch create what-if`
* Compare: `bijection branch compare what-if items:list`
* Apply: `bijection branch apply what-if --commit`

## Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch [options] [command]
```

## Options

These options choose the parent deployment for every subcommand. Without them,
`bijection branch` manages branches of your dev deployment.

<dl>
  <dt>`--prod`</dt>

  <dd>
    Manage branches of this project's default production deployment.
  </dd>

  <dt>`--deployment <deployment>`</dt>

  <dd>
    Manage branches of a specific deployment. Accepts:

    * a deployment name (e.g. joyful-capybara-123)
    * a deployment reference (e.g. dev/james, staging)
    * `dev` (for your personal dev deployment)
    * `prod` (for your project’s default production deployment)
    * `local` (for your local dev deployment).
      You can also select deployments in other projects with `project-slug:reference` or `team-slug:project-slug:reference`.
  </dd>
</dl>

You can also select the parent with `--url <url> --admin-key <adminKey>`, or
with `--env-file <envFile>` naming a file that sets `BIJECTION_DEPLOYMENT` or
`BIJECTION_SELF_HOSTED_URL`. A branch URL is refused: branches are managed on
their parent, with the parent's admin key.

## Subcommands

* [`bijection branch create`](#bijection-branch-create) — Fork the deployment's committed data at its current revision
* [`bijection branch list`](#bijection-branch-list) — List branches you can open
* [`bijection branch status`](#bijection-branch-status) — Show one branch
* [`bijection branch share`](#bijection-branch-share) — Let users open the branch with their own identity
* [`bijection branch unshare`](#bijection-branch-unshare) — Stop letting users open the branch with their own identity
* [`bijection branch extend`](#bijection-branch-extend) — Move the branch expiry
* [`bijection branch discard`](#bijection-branch-discard) — Discard the branch and everything committed on it
* [`bijection branch compare`](#bijection-branch-compare) — Run a query on the branch and on its parent and compare the results
* [`bijection branch apply`](#bijection-branch-apply) — Preview replaying your branch operations not yet applied onto live; `--commit` applies them
* [`bijection branch rebase`](#bijection-branch-rebase) — Replay your branch operations onto a fresh fork of live

Every `<key>` is 1 to 40 lowercase letters, digits or hyphens, starting with a
letter or digit.

If a command that changes a branch gets no response, the CLI can't tell whether
the change took effect. Check with `bijection branch status` before retrying.

## `bijection branch create`

Fork the deployment's committed data at its current revision.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch create [options] <key>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>
</dl>

### Options

<dl>
  <dt>`--empty`</dt>

  <dd>
    Start from an empty log instead of live data. Only administrators can
    create an empty branch.
  </dd>

  <dt>`--ttl-hours <n>`</dt>

  <dd>
    Hours until the branch expires. Defaults to 72 (3 days); at most 720 (30
    days).
  </dd>

  <dt>`--show-admin-key`</dt>

  <dd>
    Print the branch admin key and how to deploy to the branch.
  </dd>
</dl>

## `bijection branch list`

List branches you can open.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch list [options]
```

### Options

<dl>
  <dt>`--json`</dt>

  <dd>
    Output as JSON.
  </dd>
</dl>

## `bijection branch status`

Show one branch: its state, basis, expiry, owner, users it is shared with, how
far you have applied it, and a fresh personal link.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch status [options] <key>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>
</dl>

### Options

<dl>
  <dt>`--json`</dt>

  <dd>
    Output as JSON.
  </dd>

  <dt>`--show-admin-key`</dt>

  <dd>
    Print the branch admin key and how to deploy to the branch.
  </dd>

  <dt>`--identity <identity>`</dt>

  <dd>
    Act as this user, as `bijection run --identity` does: JSON-formatted
    UserIdentity, e.g. `'{ tokenIdentifier: "issuer|subject" }'`. Status shows
    how far this identity has applied.
  </dd>
</dl>

## `bijection branch share`

Let users open the branch with their own identity. Only the branch's owner or
an administrator can share it.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch share [options] <key> <principal...>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>

  <dt>`<principal...>`</dt>

  <dd>
    User token identifiers (`issuer|subject`), not JWTs.
  </dd>
</dl>

## `bijection branch unshare`

Stop letting users open the branch with their own identity. Takes effect at
once, including for open connections.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch unshare [options] <key> <principal...>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>

  <dt>`<principal...>`</dt>

  <dd>
    User token identifiers (`issuer|subject`) to remove.
  </dd>
</dl>

## `bijection branch extend`

Move the branch expiry. The basis does not move, and a branch that has
already expired can't be extended.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch extend [options] <key>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>
</dl>

### Options

<dl>
  <dt>`--ttl-hours <n>`</dt>

  <dd>
    Required. Hours from now until the branch expires; at most 720 (30 days).
  </dd>
</dl>

## `bijection branch discard`

Discard the branch and everything committed on it. What was already applied
to live stays applied.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch discard [options] <key>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>
</dl>

## `bijection branch compare`

Run a query on the branch and on its parent and compare the results. The
parent is read at the branch's basis.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch compare [options] <key> <functionPath>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>

  <dt>`<functionPath>`</dt>

  <dd>
    Query function path, e.g. `"items:list"`.
  </dd>
</dl>

### Options

<dl>
  <dt>`--args <json>`</dt>

  <dd>
    Query arguments as a JSON object. Defaults to `{}`.
  </dd>

  <dt>`--json`</dt>

  <dd>
    Output as JSON.
  </dd>

  <dt>`--identity <identity>`</dt>

  <dd>
    Act as this user, as `bijection run --identity` does: JSON-formatted
    UserIdentity, e.g. `'{ tokenIdentifier: "issuer|subject" }'`.
  </dd>
</dl>

## `bijection branch apply`

Preview replaying your branch operations not yet applied onto live; `--commit`
applies them. See [apply and rebase](/branches/apply-and-rebase).

Exits with an error when the preview or the commit is refused or diverged.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch apply [options] <key>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>
</dl>

### Options

<dl>
  <dt>`--commit`</dt>

  <dd>
    Apply the replay if the preview has no refusals.
  </dd>

  <dt>`--json`</dt>

  <dd>
    Output as JSON.
  </dd>

  <dt>`--identity <identity>`</dt>

  <dd>
    Act as this user, as `bijection run --identity` does: JSON-formatted
    UserIdentity, e.g. `'{ tokenIdentifier: "issuer|subject" }'`. Apply
    replays the operations invoked on the branch under this identity.
  </dd>
</dl>

## `bijection branch rebase`

Replay your branch operations onto a fresh fork of live. The original branch
is kept. Only the branch's owner or an administrator can rebase it.

### Syntax

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch rebase [options] <key> <newKey>
```

### Arguments

<dl>
  <dt>`<key>`</dt>

  <dd>
    Branch key.
  </dd>

  <dt>`<newKey>`</dt>

  <dd>
    New branch key. It must not already name a branch.
  </dd>
</dl>

### Options

<dl>
  <dt>`--show-admin-key`</dt>

  <dd>
    Print the branch admin key and how to deploy to the branch.
  </dd>

  <dt>`--identity <identity>`</dt>

  <dd>
    Act as this user, as `bijection run --identity` does: JSON-formatted
    UserIdentity, e.g. `'{ tokenIdentifier: "issuer|subject" }'`. Rebase
    replays the operations invoked on the branch under this identity.
  </dd>
</dl>