Remove worktree

hwt remove removes a linked worktree and closes its Herdr workspace. hwt rm is an alias.

hwt remove [flags]

Run it from the workspace being removed, or provide a workspace ID from anywhere:

hwt remove --workspace w_8Jx2

Why removal is fast

Deleting a large worktree synchronously can take a long time when directories such as node_modules, deps, or build caches contain hundreds of thousands of entries. The terminal remains blocked while the filesystem walks and deletes every file.

hwt keeps that wait out of the critical path:

1. It validates that the workspace is a linked Herdr worktree and checks its Git metadata.
2. Unless --force is set, it refuses locked worktrees and checkouts with uncommitted or untracked files.
3. It atomically renames the checkout into a temporary sibling directory on the same filesystem.
4. It closes the Herdr workspace and removes the small Git worktree metadata entry.
5. It starts a detached background deletion for the renamed directory.
6. It releases the worktree’s registered ports and returns without waiting for the recursive delete.

Under normal conditions, the expensive recursive deletion still happens without blocking the person or agent issuing the command. If the background process cannot start, hwt falls back to finishing the cleanup synchronously. If closing the workspace or removing metadata fails, hwt attempts to move the checkout back into place.

This fast remove path is a key difference from waiting for Herdr’s built-in worktree removal to synchronously delete a dependency-heavy checkout.

Removal hooks

pre_remove runs from the linked checkout before removal; post_remove runs from the primary checkout after metadata, route, and port cleanup. Strings are the normal synchronous format. Opt individual commands into background execution:

pre_remove:
  - cmd: pitchfork stop --local
    async: true
post_remove:
  - cmd: echo 'worktree removed'
    async: true

Async hooks survive closure of the workspace and CLI exit. HWT reports output log paths (also available as async_logs in JSON). Blocking failures retain their existing behavior; async failures are recorded in logs. Background file deletion waits for async pre-remove hooks to finish, without delaying the CLI. If background cleanup cannot start while async pre-remove hooks are running, HWT retains the moved-aside directory and reports an error rather than deleting files in use.

The checkout is renamed and its Git metadata removed while async pre-remove jobs run. Keep path- or Git-sensitive cleanup synchronous. See configuration for aliases and execution details.

Flags

Flag	Description
-w, --workspace ID	Workspace ID. Defaults to the current workspace.
-f, --force	Remove a dirty or locked worktree.
--json	Print machine-readable output.

Caution

--force bypasses the dirty and locked checks. It can permanently remove uncommitted and untracked files.