1. Workspaces

A workspace is the per-repo .forest/ control area: a registry of checkouts plus an active pointer. Everything forest owns lives inside it; your data does not.

Create the tutorial project and initialize a workspace:

mkdir field-notes && cd field-notes
forest init

Initialized empty forest workspace in /home/user/field-notes/.forest

Next steps:
  1. Run 'forest checkout create <name>' to create your first checkout
  2. Run 'forest remote add <name> <url>' to configure a remote
  3. Run 'forest add <stage> <path>' to register a stage and bind local data

What just happened on disk

forest init creates only two things:

field-notes/
  .forest/
    config.yaml    # the workspace registry
  .gitignore       # managed patterns, so user-local state never lands in git

The registry starts empty — version: 1 and no checkouts:

.forest/config.yaml

version: 1
checkouts: {}

And the managed .gitignore covers the files that will stay local to your machine in later chapters:

.gitignore

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

No root config, no checkout, no active pointer. The workspace container itself is nameless — names come in with checkouts, next chapter.

Re-running is safe

forest init on an existing workspace never re-initializes; it reports what is still missing from your setup:

forest init

No active checkout selected.
Run: forest checkout NAME

That is also your cue for chapter 2.

Forest and git never overlap

Git owns .git/; forest owns .forest/. Neither requires the other — field-notes isn't even a git repository yet, and forest doesn't mind. If you later run git init here, the managed .gitignore is already in place.

Recap: a workspace is the nameless .forest/ container: one registry file plus a managed .gitignore, nothing else.

Next: put something in the workspace — checkouts.