# Branches

Branches register environments as forks of a parent environment for schema
diffing and merging. A branch captures the parent's schema as a merge base,
enabling safe three-way merges and clean PR workflows.

## Endpoints

### POST /v1/organizations/{org}/projects/{project}/branches

Register an environment as a branch.

**Request body:**

```json
{
  "environment_id": "pr-42",
  "base_environment_id": "production"
}
```

`base_environment_id` is optional. When omitted, the branch has no merge base
(useful for standalone review environments).

**Response `200 OK`:**

```json
{
  "environment_id": "pr-42",
  "base_environment_id": "production",
  "merge_base_schema_version": "abc123",
  "registered_at": "2026-01-01T00:00:00Z"
}
```

---

### GET /v1/organizations/{org}/projects/{project}/branches

List all registered branches.

**Response `200 OK`:**

```json
{
  "branches": [
    {
      "environment_id": "pr-42",
      "base_environment_id": "production",
      "registered_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/diff

Compute the schema diff between two environments.

**Request body:**

```json
{ "base": "production", "head": "pr-42" }
```

**Response `200 OK`:**

```json
{
  "changes": [
    {
      "kind": "table",
      "name": "payments",
      "action": "added",
      "definition": "CREATE TABLE payments (...)"
    },
    {
      "kind": "column",
      "table": "orders",
      "name": "paid_at",
      "action": "added",
      "definition": "timestamptz"
    }
  ]
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/merge

Merge the head environment's schema into the base environment.

**Request body:**

```json
{ "base": "production", "head": "pr-42", "force": false }
```

With `force: false`, the merge fails if there are conflicts. With `force: true`,
the head schema wins on all conflicts.

**Response `200 OK`:**

```json
{
  "merged": true,
  "changes": [...],
  "conflicts": []
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/{env}/pr

Link a branch to a pull request.

**Request body:**

```json
{
  "provider": "github",
  "repository": "acme/store",
  "number": 42,
  "url_template": null
}
```

Supported providers: `github`, `gitlab`, `bitbucket`, `generic`.

For `generic`, provide `url_template` with `{repo}` and `{number}` placeholders:

```json
{
  "provider": "generic",
  "repository": "acme/store",
  "number": 42,
  "url_template": "https://git.example.com/{repo}/pull/{number}"
}
```

---

## CLI shortcuts

```sh
scribase branch register acme store pr-42 --base production
scribase branch diff acme store production pr-42
scribase branch merge acme store production pr-42
scribase branch pr acme store pr-42 github acme/store 42
scribase branch list acme store
```

See [scribase branch](https://docs.scribase.com/docs/cli/branch.md) for the full local and remote branch reference.