> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Layout versioning

> Manage, version, and deploy your Forest layout configurations across environments using branches.

Every layout change you make in Forest, column ordering, field visibility, segments, custom views, is versioned. This lets you iterate safely in development, test in staging, and promote to production without disrupting your operators.

## How layout versioning works

A Forest project has two independently versioned parts:

* **Back-end code**, your back-end customizations (datasources, actions, computed fields, hooks). Versioned with Git.
* **Layout**, your UI configuration (field visibility, columns, segments, forms, dashboards). Versioned with Forest branches.

Branches are isolated copies of a layout. You create one, make changes, test them, then deploy when ready. The production layout is never touched until you explicitly deploy.

## Environments and layouts

Each environment has its own layout:

| Environment      | Typical use                                          |
| ---------------- | ---------------------------------------------------- |
| Development      | Your personal branch, safe to experiment             |
| Remote (staging) | Test layout changes with your team before production |
| Production       | Live layout seen by all operators                    |

When you enter Layout Editor mode in your development environment, changes are saved to your current branch, not immediately deployed anywhere.

## Creating a branch

A branch is created from an existing environment's layout. Use the Forest CLI:

```bash theme={null}
forest branch my-feature-layout --origin production
```

This creates a branch called `my-feature-layout` that starts from the production layout. Switch to it:

```bash theme={null}
forest switch my-feature-layout
```

## Making layout changes

With your branch active, open the Forest UI in your browser. Enter Layout Editor mode and make your changes, reorder columns, create segments, configure forms. All changes are saved automatically to your branch.

## Comparing layouts

Before deploying, review what changed:

```bash theme={null}
forest schema:diff
```

This shows the difference between your branch and the target environment's layout.

## Deploying changes

To push your branch to a remote (staging) environment:

```bash theme={null}
forest push --environment staging
```

To deploy to production:

```bash theme={null}
forest deploy
```

<Warning>
  Deploying overwrites the target environment's layout. Review your changes with `forest schema:diff` before deploying to production.
</Warning>

## Rolling back

If a layout change causes issues in production, roll back by deploying a previous branch or resetting the environment:

```bash theme={null}
forest environments:reset --environment staging --from production
```

<Note>
  Layout rollbacks only affect the UI configuration, your back-end code and database are not touched.
</Note>

## Team collaboration

When multiple people work on the same project:

* Each developer works on their own named branch
* Branches are isolated, one developer's changes don't affect another's view
* Changes are only visible to others after a push or deploy
* The CLI `forest branch` command lists all active branches

## Avoiding conflicts

Layout branches don't support merging, deploying one branch's changes overwrites the target. To collaborate safely:

* Communicate which collections or features each person is working on
* Work on distinct parts of the layout to avoid overlap
* Use short-lived branches and deploy frequently

## Best practices

<AccordionGroup>
  <Accordion title="Name branches descriptively">
    `feature/add-order-segments` is clearer than `dev-branch-1`. Use kebab-case.
  </Accordion>

  <Accordion title="Keep branches short-lived">
    The longer a branch lives, the more it diverges from production and the harder it is to deploy cleanly.
  </Accordion>

  <Accordion title="Always test in a remote environment first">
    Before deploying to production, push to staging and verify the layout renders as expected for at least one operator role.
  </Accordion>

  <Accordion title="Use schema:diff before each deploy">
    Read every change before pushing. The diff is the last review gate before operators see the change.
  </Accordion>
</AccordionGroup>