subwave-worktree-dev

To run a docker compose dev stack from a git worktree, you must scaffold missing gitignored env files and mirror required state from the main checkout before starting containers. This ensures the linked worktree has the necessary runtime prerequisites.

Testing a branch in a git worktree often fails in dev mode because critical gitignored files, such as environment configurations and precomputed station state, are missing from the new worktree directory despite the tracked source code being present.

The best way to mirror station state into a git worktree is to copy required state settings, moods, sfx, jingles, sessions, and voice files from the main checkout, deliberately excluding container-generated runtime artifacts to prevent file conflicts.

Running the web npm dev server can require an npm install in the worktree, which can be triggered optionally during the environment preparation phase before bringing up the docker compose stack with the --build flag.

You can optionally reset station state when scaffolding a worktree for dev mode, alongside staging root, controller, web, and docker env files to safely prepare runtime prerequisites without impacting the main checkout's state.

To prepare a git worktree for dev mode, you need bash, git, lsof, ps, docker compose, curl, and npm installed and accessible in your environment to execute the scaffolding scripts and start the full stack.