How it works
Syncing one workspace
devmachine sync --workspace <name> applies one workspace and nothing
else. It finds the machine the workspace lives on, so --machine is not
needed. On a machine with many workspaces, a full sync runs every package
of every workspace; this runs only the packages of the one you name.
devmachine sync --workspace acme
devmachine sync --workspace acme --check
devmachine sync --workspace acme --tags claude-code
What it runs
- The workspace’s own packages, with its own settings.
- The skills its packages bring, and the shared logins it asked for.
- The files its packages add to another package’s folder (
extends). - Its routes file in Caddy’s
sites.d, and a Caddy reload when that file changed.
What it leaves alone
- The machine’s own packages. They do not run. A workspace package that relies on one assumes it is already there, as it is after any full sync.
- Every other workspace. Its packages, its routes file and its extension files are not touched, and not even sent.
- Removals of extension files. A full sync removes the file a package left behind when it left the plan. A one-workspace sync does not: see below.
The host variables still list every workspace on the machine
(devmachine_workspaces). Some machine packages read that list, and a
package that ran with half of it would act on half of the machine.
Why it removes no extension file
An extension file’s name starts with its workspace, so acme’s files
look like acme-<package>-<file>. But a workspace named acme-api
writes acme-api-<package>-<file>, which starts with acme- too. A
narrowed sync could only tell its own old files from another
workspace’s by guessing, and a wrong guess deletes somebody else’s site.
So the narrowed sync writes, and never removes. The lock keeps every
path it already knew, so the next full sync still removes a file that
is no longer wanted. See what sync removes.
What the lock records
Only the workspace’s entry in packages.lock is replaced. The machine’s
entry, and every other workspace’s, stay as the last sync left them. With
--tags, only the named packages of that workspace are recorded, as for
a tagged full sync. A dry run (--check) writes nothing.
The lock’s format does not change, so an older CLI reads a lock a one-workspace sync wrote, and its next full sync brings the rest of the machine up to date.
When to run a full sync instead
- After changing a machine package, or a machine’s settings.
- After removing a package that added a file to another’s folder, to have that file removed.
- On a new machine, where the machine packages have never run.