# scribase branch

Creates and manages database branches. Local branches use copy-on-write
snapshots of the local Postgres cluster; remote branches are registered with
the control-plane API and tied to pull requests or preview environments.

## Local branch commands

These operate on the local `.scribase/` workspace.

### `branch new <name> [--schema FILE]`

Creates a new branch from the current primary database. Prints the branch
connection string and returns immediately.

```sh
scribase branch new my-feature
# postgresql://postgres:postgres@127.0.0.1:54399/postgres
```

With `--schema`, the schema is compiled and applied to the new branch:

```sh
scribase branch new my-feature --schema ./schema.scribase
```

Copy-on-write branching is fast — typically under one second.

### `branch list` (local)

Lists all local branches and their status.

```sh
scribase branch list
```

Output:

```
my-feature               running   postgresql://...
old-experiment           stopped   postgresql://...
```

### `branch url <name>`

Prints the connection string for a named branch.

```sh
scribase branch url my-feature
```

### `branch delete <name>`

Stops and removes a local branch cluster.

```sh
scribase branch delete my-feature
```

---

## Remote branch commands

These call the control-plane API and require `SCRIBASE_API_URL` and
`SCRIBASE_ACCESS_TOKEN`.

### `branch register <org> <project> <env> [--base <parent-env>]`

Registers an environment as a branch of another, capturing the parent's schema
as the merge base. This is the first step before a `branch merge` or `branch diff`.

```sh
scribase branch register acme store pr-42 --base production
```

### `branch list <org> <project>`

Lists all remote branches registered for a project.

```sh
scribase branch list acme store
```

### `branch diff <org> <project> <base-env> <head-env>`

Shows the schema diff between two environments.

```sh
scribase branch diff acme store production pr-42
```

Returns a list of changed objects: added, modified, and removed tables, columns,
functions, and policies.

### `branch merge <org> <project> <base-env> <head-env> [--force]`

Merges the schema from `head-env` into `base-env`.

```sh
scribase branch merge acme store production pr-42
```

Without `--force`, the merge fails if there are conflicts. With `--force`, the
head schema wins on any conflict.

### `branch pr <org> <project> <env> <provider> <repo> <number> [--url-template <t>]`

Links a branch to a pull request. Supported providers: `github`, `gitlab`,
`bitbucket`, `generic`.

```sh
scribase branch pr acme store pr-42 github acme/store 42
scribase branch pr acme store pr-42 generic my-repo 42 --url-template "https://git.example.com/{repo}/pr/{number}"
```

---

## Workflow example

```sh
# 1. Create a branch for a feature
scribase branch new feat-payments

# 2. Develop against the branch
psql "$(scribase branch url feat-payments)"

# 3. Register the remote environment as a branch
scribase branch register acme store feat-payments --base production

# 4. Open a PR and link it
scribase branch pr acme store feat-payments github acme/store 12

# 5. Review the diff
scribase branch diff acme store production feat-payments

# 6. Merge when approved
scribase branch merge acme store production feat-payments
```