Quick start

No config files are hand-written. Onboarding a repository is five commands:

forest init                                       # (1)!
forest checkout demo                              # (2)!
forest remote add origin s3://my-bucket/prefix    # (3)!
forest add raw ./data/raw                         # (4)!
forest push                                       # (5)!

1. Creates only .forest/config.yaml (version: 1, checkouts: {}) and a managed .gitignore. No root config, no checkout, no active pointer yet.
2. Switches to the checkout — creating, registering, and activating it first (with .forest/checkouts/demo/forest.yaml) since the name isn't registered yet. forest checkout create demo is the explicit form.
3. Remotes can be added before any local binding — useful when your data is remote-only at first.
4. Registers a new stage raw and binds it to a local path in one step. Use forest bind to rebind an existing stage.
5. Syncs every bound stage to the active remote.

What just happened on disk

.forest/
  config.yaml                  # workspace registry: version, checkouts{}
  HEAD                         # active checkout name (gitignored)
  checkouts/
    demo/
      forest.yaml              # shared: stages, remotes, manifest
      local.yaml               # user-local: active_remote, stage_paths (gitignored)
      sync_state.json          # user-local push/pull state (gitignored)

Everything forest owns lives under .forest/; your data does not. Shared metadata is committed to git so a fresh clone can bootstrap; user-local files stay out of version control. Details in configuration files.

Inspect and iterate

forest status        # sync state of every bound stage (--checksum re-hashes contents)
forest diff          # what would transfer
forest ls            # list units the active remote knows about
forest flow          # emit a Mermaid data-flow diagram of the checkout

Working from another directory

Every command accepts -C <path> to operate on another repo without cd — same convention as git.

No bucket handy?

Any absolute path works as a remote — forest remote add origin ~/forest-remote syncs to a plain local directory. The tutorial runs entirely on one, no credentials required.

Ready for the full walkthrough? Head to the tutorial.