Skip to main content
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:
EnvironmentTypical use
DevelopmentYour personal branch, safe to experiment
Remote (staging)Test layout changes with your team before production
ProductionLive 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: 
forest branch my-feature-layout --origin production
This creates a branch called my-feature-layout that starts from the production layout. Switch to it: 
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: 
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: 
forest push --environment staging
To deploy to production: 
forest deploy
Deploying overwrites the target environment’s layout. Review your changes with forest schema:diff before deploying to production.

​
Rolling back

If a layout change causes issues in production, roll back by deploying a previous branch or resetting the environment: 
forest environments:reset --environment staging --from production
Layout rollbacks only affect the UI configuration, your back-end code and database are not touched.

​
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

feature/add-order-segments is clearer than dev-branch-1. Use kebab-case.
The longer a branch lives, the more it diverges from production and the harder it is to deploy cleanly.
Before deploying to production, push to staging and verify the layout renders as expected for at least one operator role.
Read every change before pushing. The diff is the last review gate before operators see the change.