How do I deprovision an environment with compass?

Table of Contents

compass env deprovision is the symmetric counterpart to compass env provision. It removes the git worktree registration and deletes the worktree directory, freeing the environment's ports for future reuse.

Question

How do I deprovision (remove) a named environment?

Answer

Before deprovisioning — stop services

Stop any running services in the environment first to avoid stale processes: 

cd ~/Development/OreStudio/ores_dev_festive_hawking
./projects/ores.compass/compass.sh services stop

Deprovision — compass env deprovision

Run the command from any other worktree (not the one being removed): 

# Interactive confirmation:
./projects/ores.compass/compass.sh env deprovision festive-hawking

# Skip confirmation (e.g. in scripts):
./projects/ores.compass/compass.sh env deprovision festive-hawking -y

What it does:

  1. Resolves the worktree directory: ores_dev_festive_hawking (new style) or OreStudio.festive-hawking (legacy — checked as fallback for backwards compatibility).
  2. Refuses to remove the current worktree (safety guard).
  3. Prompts for confirmation unless -y is given.
  4. Runs git worktree remove --force <dir>.
  5. If git remove fails (e.g. stale ref), prunes the worktree list and removes the directory with shutil.rmtree as a fallback.

Safety notes

  • The genesis environment (ores_dev_prime_origin) is a regular worktree; you can deprovision it, but doing so will prevent provisioning new worktrees until you re-clone. Do not deprovision genesis unless decommissioning the entire machine.
  • All uncommitted changes in the worktree are lost. The -y flag bypasses the confirmation prompt — use with care in scripts.
  • The environment's ports (ORES_BASE_PORT, ORES_NATS_PORT) are freed automatically: the next compass env provision run will not see them in any remaining sibling .env file.

Flags summary

Flag Effect
name (positional) Adjective-noun name of the environment to remove
-y, --yes Skip the confirmation prompt

Script

projects/ores.compass/src/env_create.py — run_deprovision()

Tested by

Manual smoke test: provision an environment, then deprovision it; verify the directory and git worktree registration are both gone.

See also

Emacs 29.3 (Org mode 9.6.15)