Skip to content
gardendocs

Virtual filesystem checkout

A garden checkout is not a copy of the repository. It is a virtual filesystem: the directory behaves like an ordinary working tree, but file contents are fetched from the server on first access.

There is no local .git directory — history is server-authoritative, which is why raw git commands don’t work in a checkout.

What this buys you

Section titled “What this buys you”

Cloning is instant, at any size. garden clone mounts the repository rather than transferring it. A decade of history mounts as fast as an empty repo.

Switching commits is cheap. Reviewing or testing someone else’s work costs a mount, not a pull:

Terminal window
garden pr checkout 128
garden checkout .          # back to where you were

A true monorepo is practical. Size stops being the constraint, so the whole project can live in one repository and a cross-cutting change can be a single stack instead of coordinated PRs across four repos.

The one thing to be careful about

Section titled “The one thing to be careful about”

Reading a file costs a network round trip the first time. Reading a handful is cheap. Scanning the whole tree is not — a repo-wide grep -r or find pulls a large fraction of the repository to answer something an index answers instantly.

This bites agents hardest, since exhaustive search is their default move.

Worktrees

Section titled “Worktrees”

Cheap checkouts make several of them normal:

Terminal window
garden worktree add ../hotfix
garden worktree list
garden worktree remove ../hotfix

Each has its own files and current commit, so parallel lines of work don’t disturb each other. Commits are shared. -b <name> is accepted as a label — garden has no branches, so it creates nothing.

Setup and repair

Section titled “Setup and repair”

The mount is why garden setup asks for sudo once. If a checkout stops mounting — usually after an OS upgrade — re-running garden setup is the fix. A login agent keeps checkouts mounted across reboots.

Section titled “Related”