You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-`modifies_hooks` declaration: automatically disables `before_specify -> speckit.git.feature` on install (with user consent) so the primary checkout stays on a stable branch
17
+
- Requires Spec Kit with `modifies_hooks` support ([github/spec-kit#2209](https://github.com/github/spec-kit/pull/2209))
A [Spec Kit](https://github.com/github/spec-kit) extension for **default-on** git worktree isolation — work on multiple features (or run parallel agents) without checkout switching.
4
6
5
7
## Why another worktree extension?
6
8
7
9
The community [spec-kit-worktree](https://github.com/Quratulain-bilal/spec-kit-worktree) extension is a good starting point. This extension differs in three ways:
8
10
9
11
1.**Default-on** — worktrees are created automatically after `/speckit.specify`. Opt *out* with `--in-place`, rather than opting in.
10
-
2.**Sibling-dir layout** — worktrees live at `../<repo>--<branch>` by default, so each feature gets its own top-level IDE window. Nested `.worktrees/` is available as an option.
12
+
2.**Nested layout by default** — worktrees live at `.worktrees/<branch>/` inside the repo (gitignored, self-contained). Sibling-dir layout (`../<repo>--<branch>`) is available as an option for IDE-per-feature workflows.
11
13
3.**Deterministic bash script** — a real script (`create-worktree.sh`) with `--json` output, `--dry-run`, and `SPECIFY_WORKTREE_PATH` override, suitable for CI and scripted workflows.
Open each directory in its own IDE window. No `.gitignore` changes needed.
33
-
34
-
### Nested
23
+
### Nested (default)
35
24
36
25
Worktrees live inside the repo under `.worktrees/` (auto-gitignored):
37
26
@@ -44,19 +33,39 @@ my-project/
44
33
├── src/
45
34
```
46
35
47
-
Switch with `layout: nested` in `worktree-config.yml`.
36
+
Self-contained — everything stays in one directory. `.worktrees/` is added to `.gitignore` at install time so worktree directories are never accidentally committed to the main repo. Work inside each worktree is committed on its own feature branch.
37
+
38
+
### Sibling
39
+
40
+
Each worktree is a sibling directory of the primary clone:
Open each directory in its own IDE window. Switch with `layout: "sibling"` in `worktree-config.yml`.
48
50
49
51
## Configuration
50
52
51
53
Create `.specify/extensions/worktrees/worktree-config.yml` to override defaults:
52
54
53
55
```yaml
54
-
layout: "sibling"# sibling | nested
56
+
layout: "nested"# nested | sibling
55
57
auto_create: true # false to prompt instead of auto-creating
56
58
sibling_pattern: "{{repo}}--{{branch}}"
57
59
dotworktrees_dir: ".worktrees"
58
60
```
59
61
62
+
## How worktrees stay isolated
63
+
64
+
- **On install** (`specify extension add`): `.worktrees/` is added to `.gitignore` so the directory is ignored before any worktree exists
65
+
- **On create** (`/speckit.worktrees.create`): the script double-checks `.gitignore` as a safety net
66
+
- **Commits stay on the right branch**: each worktree has its own working tree and index — `git add` and `git commit` inside a worktree only affect that worktree's branch, not the main repo
67
+
- **Cleanup**: `/speckit.worktrees.clean` removes worktree directories; it never deletes the git branch itself
**`after_specify`** — automatically creates a worktree after a new feature is specified. Controlled by the `auto_create` config value.
71
80
81
+
## Hook overrides
82
+
83
+
This extension declares `modifies_hooks` in `extension.yml` to **disable** the git extension's `before_specify -> speckit.git.feature` hook on install. This keeps the primary checkout on a stable branch (e.g. `main`) while worktrees handle feature branch isolation.
84
+
85
+
During `specify extension add`, you will see a consent prompt:
86
+
87
+
```
88
+
Extension 'worktrees' requests the following hook modifications:
Answering **Y** disables the hook. Answering **N** installs the extension without modifying hooks (you can disable it manually in `.specify/extensions.yml`). Removing the extension via `specify extension remove worktrees` restores the original hook state.
97
+
98
+
**Requires**: Spec Kit with `modifies_hooks` support (see [github/spec-kit#2209](https://github.com/github/spec-kit/pull/2209)).
99
+
72
100
## Script usage
73
101
74
102
The bash script can be called directly for automation:
75
103
76
104
```bash
77
-
# Create a sibling worktree for branch 005-user-auth
105
+
# Create a nested worktree for branch 005-user-auth (default)
description: "Auto-spawn a worktree after a new feature is specified"
41
41
42
+
lifecycle:
43
+
post_install:
44
+
script: scripts/bash/post-install.sh
45
+
description: "Add .worktrees/ to .gitignore so worktree directories are never committed to the main repo"
46
+
47
+
modifies_hooks:
48
+
- hook: before_specify
49
+
extension: git
50
+
command: speckit.git.feature
51
+
action: disable
52
+
reason: "Worktree-parallel keeps primary checkout on a stable branch (e.g. main); branch creation is handled by git worktree add -b during after_specify"
0 commit comments