Skip to content
Source
Sign inSign up

Keep workspaces ready

Work with agents / Local workspaces

Keep workspaces ready

You want src ws create to be fast, and you also watch your disk. src keeps a pool of ready workspaces, and you choose how many it keeps.

4 min read

With a ready workspace, create and close do not wait for a copy or an install. A ready workspace is an idle slot folder (ws-<n>) in the folder for workspaces. It has:

  • The files of the tip of your default branch.
  • Its own .git.
  • Its installed dependencies (its layers).

The pool keeps 2 ready workspaces by default.

1. Pick the size of the pool

src ws init --spares 4

The size is from 0 to 20.

2. Prepare the pool

src ws prepare

It builds the new ready workspaces, or deletes those above the size. Then it prints what it did:

Pool: built 2, cleaned 1.

3. See the pool

src ws list

The last line shows the pool, for example Pool: 2 ready, 1 being cleaned, or Pool: off. src ws list --json pool gives it as JSON.

Done

The pool keeps the number of ready workspaces that you picked. create takes one of them, and close gives the folder back.

How the pool works

  • close keeps the folder of a workspace in the pool. It does not delete it.
  • src ws prepare cleans each kept folder, moves the ready ones to the tip of the default branch, and builds more until the pool is full. create, close and the git hooks of auto-prepare start it in the background.
  • create takes a ready workspace and cleans it to its baseline. When no workspace is ready, it cleans a kept folder itself, or makes a new slot.
  • src ws gc also deletes the ready workspaces above the size, and those outside the folder for workspaces.

Prepare ahead of time

src ws prepare writes the files of the tip of your default branch (origin/HEAD, else main, else master) and installs its dependencies. The next create from that commit only clones. Then prepare fills the pool of ready workspaces at that tip.

When the files and the pool are ready, it does nothing. To prepare another revision, give it: src ws prepare release-2. This does not change the pool.

You do not have to run it yourself. Auto-prepare is on by default:

  • Each src ws command checks the tip of the default branch. If it has no prepared base, the command starts a prepare in the background.
  • src ws init adds src ws prepare --background to the git hooks that run when your checkout moves: post-merge, post-rewrite and post-checkout.
  • init uses the hook setup that your repository has: plain .git/hooks, lefthook-local.yml, husky's ~/.config/husky/init.sh, or a core.hooksPath of another tool. It never changes a committed file.

A background prepare is a separate process that ends when it is done. src keeps the newest two prepared bases of the default branch, and the bases that open workspaces use.

Note

A prepare runs the built-in install of your lockfile, which runs the install scripts of your packages, as an install by hand does. It runs commands from .source/workspace.yaml only after you trust them. See Trust the commands of the config.

To turn auto-prepare off, run:

src ws init --no-auto-prepare

This takes src out of the git hooks. To turn it on again, run src ws init. create and close still start a prepare that fills the pool. To stop the pool, see Turn the pool off.

Turn the pool off

src ws init --spares 0
src ws prepare

The prepare deletes the ready workspaces. Then close deletes the folder of each workspace, and each create makes a new slot. To turn the pool on again, run src ws init --spares 2.

What a clean removes

A clean makes the folder the same as a new workspace. Nothing of the old agent stays:

  1. src makes a new .git. The branches, hooks, config and stash of the old agent go.
  2. git reset --hard puts the files of the commit back. Git writes only the files that changed.
  3. git clean deletes each untracked or ignored file, except the dependency folders. The env files, build outputs and .wrangler folder of the old agent go.
  4. If an agent used the folder, or the lockfile changed, the install of each layer runs on top of the dependency folders that are there. Else the layers stay, and no command runs.
  5. src clones the caches of each workspace from the base folder.

How much disk the pool uses

  • The pool keeps one idle folder on the disk for each ready workspace.
  • With pnpm 10.12.1 or later, src turns on the global virtual store of pnpm. Then each node_modules is mostly links into one shared store.
  • On a disk with no copy-on-write, each new ready workspace is a full copy of your files. src ws prepare makes it in the background, so create does not wait for it.