The data model

Forest keeps its metadata in .forest/ at the repo root. Your data stays where it is.

Workspace, checkout, stage, unit, files

workspace → checkout → stage → unit → files

Level	What it is
Workspace	The .forest/ directory. It holds the remotes and the list of checkouts.
Checkout	A named data tree, such as demo. forest checkout demo switches to it.
Stage	A named data category in a checkout, bound to a local path with forest add raw ./data/raw.
Unit	One item in a stage. The stage's sync_by in forest.yaml picks it: each subdirectory (default), the whole directory, or each file.

By default, files land on the remote at <remote>/<checkout>/<stage>/<unit>/<file>, for example demo/raw/run1/a.txt. With sync_by: directory or file there is no unit folder, so files sit at <remote>/<checkout>/<stage>/<file>. A stage's remote_path in forest.yaml replaces <checkout>/<stage>; forest add raw ./data/raw origin:field/raw sets it to field/raw.

Remotes

forest remote add origin s3://my-bucket/prefix
forest remote use origin
forest checkout demo

Remotes belong to the workspace, so you can add them before the first checkout. forest remote use only picks the remote for new checkouts. Each checkout keeps the remote it was created with, and stages you add later use that remote too.

What is in .forest/

After init, remote add, remote use, checkout demo, add raw ./data/raw and one push:

.forest/
  config.yaml              # shared: remotes, checkouts and each checkout's remote
  HEAD                     # local: active checkout name
  local.yaml               # local: remote for new checkouts
  config.yaml.lock         # local
  checkouts/
    demo/
      forest.yaml          # shared: stages and their remote paths
      local.yaml           # local: this checkout's remote and stage paths
      sync_state.json      # local: push/pull history
      sync_state.json.lock # local

Commit the shared files. forest init writes a .gitignore that ignores the local ones:

.forest/HEAD
.forest/local.yaml
.forest/config.yaml.lock
.forest/checkouts/*/local.yaml
.forest/checkouts/*/sync_state.json
.forest/checkouts/*/sync_state.json.lock

Status

forest status
forest status raw

forest status compares your local files with the remote live. It transfers nothing and writes no history. See the CLI reference for its rows and flags.