Stages

A stage is a named category of data in the active checkout. forest add registers a stage and binds it to a local path in one step:

forest add raw ./data/raw
forest add processed ./data/processed --direction push

The stage's sync_by in the checkout's forest.yaml sets what one unit is. forest add leaves it at the default; edit the file to change it:

Value	One unit is
subdirectory (default)	each subdirectory of the bound path
directory	the whole bound path
file	each file in the bound path

A third argument REMOTE:PATH stores the stage under PATH on the checkout's remote instead of <checkout>/<stage>, for example forest add raw ./data/raw origin:field/2026/raw. REMOTE must be the checkout's own remote.

--direction is both (default), push or pull. A bare forest push or forest pull skips stages that don't allow its direction. Naming such a stage is an error:

$ forest pull
Skipping stage 'processed' (direction: push).
SKIP raw/plot-01  already synced to origin
SKIP raw/plot-02  already synced to origin
$ forest pull processed
Error: stage 'processed' is push-only; pull not allowed. Set direction: both in forest.yaml to change this.

Bindings

The stage stays in .forest/checkouts/<checkout>/forest.yaml. The local path is a binding, and bind and unbind change it:

$ forest unbind processed
Unbound stage 'processed' from data/processed.
$ forest bind
processed   <unbound>
raw data/raw
$ forest push
Warning: stage 'processed' is not bound; skipping. Run: forest bind processed <PATH>
SKIP raw/plot-01  already synced to origin
SKIP raw/plot-02  already synced to origin
$ forest push processed
Error: stage 'processed' is not bound. Run: forest bind processed <PATH>
$ forest bind processed ./data/processed
Bound stage 'processed' -> data/processed

The checkout config after the two add commands and the sync_by edit:

$ cat .forest/checkouts/survey/forest.yaml
project: survey
stages:
  raw:
    remote_path: survey/raw
  processed:
    remote_path: survey/processed
    sync_by: directory
    direction: push