# Branches

Fork a line of versions, write on it, review the difference and merge it back at the version the review read.

A branch is a name for a line of versions. You fork one from a version, write on it freely, review it, and merge it at exactly the version the review read. The served merge requires the target to remain at the fork base.

## Fork

A store starts with `main`. The `create_branch` tool forks a new branch from a retained version of a source branch. After the fork, the two move independently.

## Review

The `review_branch` tool reads the difference between a branch and the branch it came from, in bounded pages. It shows changed records, counts, conflicts, and any link whose other end is missing. The review answers the version it read.

## Merge

The `merge_branch` tool takes that version as `reviewed`. If the branch has moved since the review, the merge is refused. The command compares the supplied reviewed version with the source head. The caller is responsible for actually reading the review. It also refuses merge_target_moved if the target has changed since the fork. The merged branch is left as it is.

**merge_branch**

```json
{
  "request_id": "merge-ward-4b-cleanup",
  "branch": "main",
  "expected": { "generation": "3", "sequence": "41" },
  "from": "ward-4b-cleanup",
  "reviewed": { "generation": "1", "sequence": "9" }
}
```


## Discard and rename

A branch is discarded with the `branch.discard` change kind, which names the branch itself.

Renaming happens offline, with the service stopped. The `branch-rename` command reports what would happen with `--check` and does it with `--apply`. See [Command line](/haematite/reference/cli/#command-branch-rename).

> Agents on branches
> Give an agent a branch of its own and the grants it needs. A person reads the review and submits its captured version to merge. Branch separation does not replace Lys permissions.