Skip to content

Tutorial

This tutorial teaches forest the way the FastAPI user guide teaches FastAPI: short chapters, each building on the last, each runnable as you read.

Every command and every block of output in these pages was captured from a real session — if you type along, your terminal should match what you see here, byte counts included.

The worked example

You are surveying forest plots. Field notes and temperature logs land in data/raw/, one folder per plot; a summary table lives in data/processed/. Git can version the code that produces the summary — the data itself belongs to forest. Over seven chapters you will build this repository:

field-notes/
  data/
    raw/                 # stage 'raw' — one unit per plot
      plot-01/
      plot-02/
    processed/           # stage 'processed' — one unit, the whole directory
  samples.csv            # manifest: sample IDs → units (chapter 6)
  .forest/               # forest's control area (chapter 1)

and sync it to a remote — a plain local directory, so you need no cloud account or credentials to finish the tutorial. Everything you learn carries over unchanged to S3 or SFTP remotes.

  • 1 — Workspaces

    forest init and the nameless .forest/ container.

    Workspaces

  • 2 — Checkouts

    Named data views, HEAD-style switching in O(1).

    Checkouts

  • 3 — Stages & binding

    Registering data categories and binding them to local paths.

    Stages

  • 4 — Remotes

    Adding, selecting, and inspecting sync targets.

    Remotes

  • 5 — Push, pull & status

    Moving data and reading its sync state.

    Syncing

  • 6 — Targeting slices

    Single units, --stage, manifest IDs, dry runs, excludes.

    Targeting

  • 7 — Dogfood

    How the forest repo itself runs forest.

    Dogfood

Prerequisites

Install forest and make sure rclone is on your $PATH (rclone version should print something). That's all — no cloud account, no credentials, and no existing git repository required.

Fresh rclone install?

If rclone has never been configured on your machine, it prefixes its first transfers with NOTICE: Config file ... not found - using defaults. Harmless — silence it with touch ~/.config/rclone/rclone.conf.