Quick start¶

This uses a local directory as the remote, so you need no cloud account. For a real remote, pass an S3 or SFTP URL to forest remote add, such as s3://my-bucket/prefix.

mkdir -p ~/forest-remote
cd my-project
forest init
forest remote add origin ~/forest-remote
forest remote use origin
forest checkout demo
forest add raw ./data/raw

remote use sets the remote that new checkouts remember. forest checkout demo creates the checkout if needed and switches to it. forest add binds the stage raw to ./data/raw, and each subdirectory there is a unit. forest moves units, so loose files directly in ./data/raw are not pushed.

Push¶

With two files in data/raw/run1/:

$ forest push
Transferred: 2 B, 2 files
PUSH raw/run1  2 files, 2 B -> origin

A bare forest push or forest pull covers every bound stage whose direction allows it. The remote now holds ~/forest-remote/demo/raw/run1/a.txt (<checkout>/<stage>/<unit>/<file>).

Status¶

forest status compares against the live remote and transfers nothing. Add data/raw/run1/c.txt, then limit it to one stage:

$ forest status raw
synced:origin  raw/run1/a.txt  matches remote
synced:origin  raw/run1/b.txt  matches remote
local-changed:origin  raw/run1/c.txt  absent on remote

Push one unit, then pull¶

$ forest push raw/run1
Transferred: 1 B, 1 files
PUSH raw/run1  1 files, 1 B -> origin
$ forest pull
SKIP raw/run1  already synced to origin

Pull skips a unit when the remote's file hashes match your files.

Next: the tutorial, the data model and the CLI reference.