# Branches and review

> How content branches work, how promotion merges text by character and reports conflicts, how reviews, releases, scheduling and rollbacks fit together.

A branch is a set of content changes that waits until someone promotes it into `main`. `main` is the live content that sites read. People use branches for a redesign or a campaign; agents use them for every task.

## Create a branch

From the studio, with `galerne branch create <name>`, or with the `create_branch` tool:

```json
{ "name": "agent/translate-de", "title": "German version", "description": "All pages, using the glossary" }
```

Names are lowercase and may use letters, digits, `.`, `_`, `-` and `/`, up to 100 characters. The Free plan includes 2 active branches and Pro 20; Business has no limit. Promote or close a branch to free its slot.

## Fork on write

A new branch is empty. Reading a document on the branch returns the version on `main` until the branch changes it. The first write on the branch copies the document into the branch and records the version it started from, the fork point. From then on the branch has its own copy, with its own drafts, published version and history.

So a branch always shows the whole site: its own changes, and `main` for everything else. A preview that queries with `branch` shows exactly what the site will look like after promotion.

In the studio, several people and agents can edit the same document on the same branch at once. Edits merge live, character by character.

## Review

When the work is done, ask for review with `request_review`, from the studio, or with `galerne branch review --note "…"`. The branch status moves from `open` to `in_review`, and the review view shows:

- every document created, edited or deleted on the branch, with a diff per field;
- the schema deployed on the branch, if any, as a diff against `main`'s;
- fields that also changed on `main` since the fork, as conflicts;
- validation errors and content checks of the changed documents;
- comments on the branch, on documents and on single fields;
- the review history: requests, approvals, changes requested, promotions.

Reviewers approve or ask for changes with a note. Only people can approve: an agent that calls `approve` gets a `403`. Review, releases and scheduling are part of Pro and up.

`branch_changes` returns the same information as JSON, so an agent can read the reviewers' comments and fix what they asked.

Comments can mention people with `@email` or `@[Name]`, and a comment with an assignee becomes a task with an optional due date. See [comments and history](/docs/comments-history.md).

## Promote

Promotion merges the branch into `main`:

```json
{ "branch": "agent/translate-de", "publish": true }
```

Each changed document is merged against its fork point:

- **Text fields merge by character.** If an editor fixed a typo on `main` while an agent rewrote the second paragraph on the branch, both changes survive.
- **Other fields merge three ways.** A field changed only on the branch takes the branch value; a field changed only on `main` keeps the `main` value.
- **Blocks merge by `_key`.** Blocks added, edited or moved on either side are kept, in order.
- **A field changed on both sides to different values is a conflict.** So is a block one side deleted while the other edited it.

Without `onConflict`, promotion stops with a `409 conflict` and lists each document and the conflicting paths. Settle them on the branch, or promote again with `onConflict: "branch"` or `onConflict: "main"` to pick the side that wins. The character-level merge of text fields still applies.

With `publish: true`, the merged documents are published at once and every one must pass validation; otherwise the promotion stops with a `422` and the field errors. Without it, the merged changes land as drafts on `main` and keep their published version until someone publishes. Pass `docs` to promote only some documents.

A branch can carry a schema change for the site code it holds (see [changing the schema on a branch](/docs/schema.md#change-the-schema-on-a-branch)). Promotion deploys it on `main` first, in the same transaction, so the content lands on the model it was written for; a branch with only a schema change can be promoted too. When the site code lives in the same branch, the studio then merges the code: schema, content, code.

Promoted documents leave the branch, which reads through to `main` again. When nothing is left, the branch becomes `merged`. Agents promote only when their member has the promote right; most should ask for review instead.

## Keep a branch up to date

`update_from_main` (or `galerne branch update`) brings changes made on `main` since the fork into the branch. Text merges by character as in promotion; on other conflicting fields the branch value wins, and the result lists them.

## Close a branch

`close_branch` closes a branch without promoting it. Its changes stay in history.

## Releases and scheduling

A release is a branch with a publish date. Create one with `release: true` and an optional `publishAt` time:

```json
{ "name": "release/spring", "title": "Spring collection", "release": true, "publishAt": "2027-03-20T08:00:00+01:00" }
```

At that time, Galerne promotes the release with `publish: true` and the branch side winning conflicts, and sends a `release.published` event. You can also promote it by hand at any time.

To publish or unpublish a single document at a time, use `schedule` (or the studio) with `action` and `at`. See [scheduled publishing and releases](/docs/scheduling.md).

## Roll back

Every promotion is recorded with the state of each document on `main` before it. From the studio you can roll a promotion back: each document returns to its previous draft and published state, as a new change in history, and Galerne sends a `release.rolled_back` event.

To undo a single document, `restore_version` restores a past version from `get_history`, whole or only some fields.

## History

Every change keeps who made it, person or agent, and when. `get_history` lists the versions of a document; pass two versions to get the field diff between them. The Free plan keeps 7 days of history, Pro 90 days and Business one year.
