How worktrees are built
A folder and a workspace per worktree
Section titled “A folder and a workspace per worktree”Offsite creates each worktree under ~/.offsite-worktrees, in a folder per repository:
~/.offsite-worktrees/bloom-1a2b3c4d/fix-login-3acea3. Every worktree is a workspace of
its own, grouped with its repository through git’s shared repository folder, so every
card works in it.
Git knows these worktrees as well: git worktree list in the main checkout lists them,
and a terminal in one sees its branch.
A fresh base and a checkout
Section titled “A fresh base and a checkout”Right before it creates a worktree, Offsite fetches the base from the remote. Then
git worktree add creates the branch and checks out the tracked files into the new
folder. The history is shared: a worktree reads the commits and objects of the main
checkout’s .git, so no second clone lands on the disk.
Smart Copy
Section titled “Smart Copy”What git ignores is missing from a fresh checkout, and for many projects that is the
biggest part: node_modules, target, .venv, build caches. Smart Copy takes the paths
you list in the setup from the main checkout.
Where the file system can, it clones them:
| Host | File system | How |
|---|---|---|
| Mac | APFS | a whole folder in one clonefile() call, single files with fclonefileat() |
| Linux | btrfs, XFS | FICLONE per file |
A clone is copy-on-write. The new folder points at the same data blocks as the original,
so a node_modules of a gigabyte arrives in seconds and takes almost no extra space.
When the worktree changes a file, only the changed blocks are written anew. The main
checkout never sees the change.
Offsite tries one file first, and when that clones, the rest follows the same way. Each
path is assembled in a staging folder and moved into place when complete, so an
interrupted copy never leaves half a node_modules behind.
The Setup popover shows the result per path: cloned, linked, full copy, kept, already there or skipped, tracked by git.
Full copies
Section titled “Full copies”Cloning works within one volume and needs APFS, btrfs or XFS. On ext4, or with the repository on another volume than the worktrees folder, Smart Copy copies the bytes and says so: full copy, other volume or full copy, file system cannot clone.
A full copy takes time and space, so each worktree copies at most 2 GB or 50,000 files.
A path over that shows as too large to copy and stops the setup before the agent
starts. Install it with a setup command instead, npm ci for node_modules, or link it.
Counting the space
Section titled “Counting the space”Finder, du and the sizes in Host Settings › Worktrees add up every file at its full
size, clones included, so a cloned node_modules counts as much as the original. What a
worktree costs the disk shows in the free space of the volume: it shrinks by the
checked-out files, by what the setup installs and by what changes after the clone.
Ports from the branch name
Section titled “Ports from the branch name”Offsite hashes the branch name to one of 100 windows of 100 ports between 20000 and 29999. When another worktree or main checkout holds that window, it hashes again until it finds a free one. The window is stored with the worktree, and each run entry takes a fixed slot in it by name. Run apps side by side shows how to use it.
Results stay until you delete them
Section titled “Results stay until you delete them”Offsite never deletes a worktree, a branch or a commit on its own. It suggests worktrees
that look finished in Host Settings › Worktrees, and Delete worktree asks first.
A deleted worktree’s folder goes to a trash folder under ~/.offsite-worktrees and is
removed in the background.
When a worktree’s folder is gone, its card says Directory missing and its sessions stay closed, so nothing starts in another folder by mistake.