Skip to content

docs: worktree setup hooks#219

Merged
marcus merged 2 commits intomainfrom
docs/worktree-setup-hooks
Mar 1, 2026
Merged

docs: worktree setup hooks#219
marcus merged 2 commits intomainfrom
docs/worktree-setup-hooks

Conversation

@marcus
Copy link
Copy Markdown
Owner

@marcus marcus commented Mar 1, 2026

Adds documentation for the automatic setup that runs when a worktree is created.

What's documented

  • Env file copying — which files are copied, behavior for missing files
  • Directory symlinks — opt-in via symlinkDirs config, when to use it
  • .worktree-setup.sh hook — how to create it, available env vars (MAIN_WORKTREE, WORKTREE_BRANCH, WORKTREE_PATH), practical examples
  • Error handling — failures don't block worktree creation

Changes

  • New: website/docs/worktree-setup.md
  • Updated: website/docs/workspaces-plugin.md — cross-reference added in the "what happens on creation" section

Build verified: npm run build passes.

When sidecar is started from a git repo subfolder, WorkDir is set to
that subfolder (e.g. /repos/myrepo/subfolder). Both doCreateWorktree
and fetchAndCreateWorktree were computing the new worktree's parent
directory as filepath.Dir(WorkDir), which resolves to the git root
itself — placing the new worktree *inside* the main repo instead of
beside it.

Fix: use ProjectRoot (already correctly resolved to the main worktree
path via GetMainWorktreePath) instead. When ProjectRoot is empty fall
back to WorkDir for safety.

Adds a regression test documenting the path-computation invariant.

Fixes #174
Documents the automatic setup that runs when a worktree is created:
- Env file copying (.env, .env.local, .env.development, .env.development.local)
- Directory symlinking (opt-in via symlinkDirs config)
- .worktree-setup.sh hook with env vars and examples

Cross-references from workspaces-plugin.md.
@marcus marcus merged commit 665df41 into main Mar 1, 2026
3 checks passed
@marcus marcus deleted the docs/worktree-setup-hooks branch March 1, 2026 02:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant