workler remove

Delete a workspace.

workler remove <name> [--force]

workler rm is an alias.

Behavior

Recursively deletes .worktrees/<name> — after checking that nothing would be lost:

• Refuses if the workspace has local data — uncommitted changes to tracked files, staged changes, untracked files, and ignored files. Deletion is forever, so this guard is deliberately stricter than the tracked-only dirty check used by status and sync: a gitignored database, a hand-made .env, and nested .worktrees/ all count. Two things do not count:
  • What .workler produces. The destinations of the project's copy and link rules, while they are what apply makes of their source (the source exists in the main project and is reached through real folders, since apply skips an absent source and refuses one behind a symbolic link, and the destination is a link to it or a copy with its content), and the paths of its setup --if-missing lines that a guarded command created in this workspace, while the entry there is still the one it made (node_modules say; setup records them, so a folder you made by hand at a guard path is local data; files written inside a recorded guard folder later count as its output and are deleted with it) are regenerated by workler apply and workler setup, so they are not local data, whether they are ignored or merely untracked. A copied .env you edited inside the workspace no longer matches its source, so it is local data (apply would refuse to overwrite it without --force too), and so is a file that was at a destination before its rule was added. A rule destination that is a tracked file still counts when it differs from the commit.
  • An empty .worktrees/. That is where Workler keeps its lock, so a nested workspace you already removed, or a group command that locked this repository as one of its sources, leaves the empty directory behind and it holds nothing. A non-empty one holds nested workspaces and counts.
• main can never be removed.

A workspace you ran Portler in holds its state in an ignored .portler/, which counts as local data like any other ignored folder. Stop its services and clear that state first (portler down, then portler clean); --force would delete the folder while the services keep running.

Removal is plain directory deletion: any nested workspaces under the workspace's own .worktrees/ go with it, and local branches that exist only in that clone are lost — run workler branch-sync first if you want them mirrored into the root as refs/workler/<name>/....

In a project group, the guard covers every member clone (each judged against its own source repository's .workler), and the workspace folder must hold nothing but the members, an unchanged .workler copy, and what the group's own rules and --if-missing lines produce (plus .workler-setup.json, Workler's record of the latter, while it is a regular file that reads exactly as Workler writes it): a nested .worktrees/, a member directory that is not a clone, a repository at a member's path that is not the recorded clone of that member (an unrelated repository dropped there, or a clone made for another workspace or location), or a symbolic link or file sitting at a member's path or at any folder on the way to it (whatever the link points at; it is never followed) all count as local data. A member that was never cloned holds nothing and does not block removal. The .workler copy is harmless only while it is a regular file that still matches the group's file; once you edit it (for example to configure nested group workspaces), replace it with a symbolic link (even one pointing at the group's file), or the group's .workler changes after the workspace was created, it counts as local data. The error lists every reason.

Options

Flag	Description
--force	Remove even with local data

Output

removed feature-a

Errors

• No workspace named <name>.
• Workspace has local data (without --force): workspace has local changes: <path>, followed by what was found, one entry per line as Git spells it (uncommitted: README.md, untracked: notes.txt, ignored: .portler/), the first ten of them. A name holding a control character, a bidirectional-text control, a line or paragraph separator, a quote or a backslash is printed quoted with C-style escapes (untracked: "a\nb"), so it stays on its own line. In a project group each reason is listed, with a member clone's entries under it.
• <name> is main.

Examples

workler remove feature-a
workler remove broken-experiment --force
workler branch-sync && workler remove feature-a   # keep its branches as refs first