@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 161 lines 4.3 KB
Raw
1 ---
2 title: Worktrees
3 description: Run alchemy deploy, dev, and tests from several git worktrees at once — one stage per worktree, so parallel agents never touch each other's resources.
4 ---
5
6 Coding agents often work in parallel, each in its own
7 [git worktree](https://git-scm.com/docs/git-worktree). Every worktree
8 is a full checkout of your app, so each one can deploy, run
9 `alchemy dev`, and run tests. They just need separate
10 [stages](/environments/stages).
11
12 ## Why worktrees collide
13
14 The default stages are named after your user, not your checkout.
15
16 ```sh
17 alchemy deploy # live_sam, from every worktree
18 alchemy dev # dev_sam, from every worktree
19 ```
20
21 Two worktrees deploying `live_sam` are one stage. Each deploy
22 replaces the other's code, and a `destroy` in one deletes resources
23 the other still uses.
24
25 ## Name a stage after the worktree
26
27 Derive the stage from the worktree's directory name.
28
29 ```sh
30 basename "$(git rev-parse --show-toplevel)"
31 # feat-x
32 ```
33
34 Stage names must match `[a-z0-9][-_a-z0-9]*`, so name worktree
35 directories with letters, digits, `-`, and `_`.
36
37 ## Deploy
38
39 Put the stage in a script so neither you nor an agent has to type it.
40
41 ```json
42 {
43 "scripts": {
44 "deploy": "alchemy deploy --stage live_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")",
45 "destroy": "alchemy destroy --stage live_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
46 }
47 }
48 ```
49
50 `pnpm run deploy` in `feat-x` now deploys `live_sam_feat-x`, and
51 `pnpm run destroy` tears down only that stage.
52
53 ## Dev
54
55 `alchemy dev` gets its own stage the same way.
56
57 ```json
58 {
59 "scripts": {
60 "dev": "alchemy dev --stage dev_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
61 }
62 }
63 ```
64
65 Each worktree's Workers and dev servers pick a free localhost port,
66 so several dev sessions run side by side. Don't pin a fixed
67 `dev.port` in code that runs in more than one worktree.
68
69 ## Destroy a dev stage
70
71 Resources with no local emulator, and anything you pinned with
72 [`remote()`](/environments/local-development#local-by-default-live-on-demand),
73 are real cloud resources. They keep running after `alchemy dev`
74 exits. Destroy the dev stage with `alchemy destroy`.
75
76 ```json
77 {
78 "scripts": {
79 "dev:destroy": "alchemy destroy --stage dev_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
80 }
81 }
82 ```
83
84 `alchemy destroy` defaults to the deploy stage, so always pass the
85 dev stage here.
86
87 ## Test
88
89 `Test.make` deploys to `test_$USER` by default, so tests need a
90 worktree stage too. How you pass it depends on your
91 [test runner](/testing/test-harness#runners).
92
93 ### With @alchemy.run/test
94
95 The `alchemy-test` runner takes the stage as a flag.
96
97 ```json
98 {
99 "scripts": {
100 "test": "alchemy-test --stage test_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
101 }
102 }
103 ```
104
105 `pnpm test` in `feat-x` now deploys every test stack to
106 `test_sam_feat-x`. Extra arguments still pass through, so
107 `pnpm test test/integ.test.ts -t "serves"` runs one test on the
108 same stage.
109
110 ### With bun test or Vitest
111
112 Neither runner has a stage flag. Set `ALCHEMY_TEST_STAGE`, which
113 `--stage` sets for you under `alchemy-test`.
114
115 ```json
116 {
117 "scripts": {
118 "test": "ALCHEMY_TEST_STAGE=test_${USER}_$(basename \"$(git rev-parse --show-toplevel)\") bun test"
119 }
120 }
121 ```
122
123 Swap `bun test` for `vitest run` on Vitest.
124
125 ## Tell your agents
126
127 Agents follow the scripts they find. Spell out the rule in
128 `AGENTS.md` (or `CLAUDE.md`).
129
130 ```md
131 ## Stages
132
133 This repo is worked on from several git worktrees at once.
134 Never run `alchemy deploy`, `alchemy dev`, `alchemy destroy`, or the test runner directly.
135 Use `pnpm run deploy`, `pnpm run dev`, `pnpm run destroy`, `pnpm run dev:destroy`,
136 and `pnpm test`, which pick a stage named after this worktree.
137 Before deleting the worktree, run `pnpm run dev:destroy` and `pnpm run destroy`.
138 ```
139
140 ## Clean up before removing a worktree
141
142 A deleted worktree takes its scripts with it, not its cloud
143 resources. Destroy its stages first.
144
145 ```sh
146 pnpm run dev:destroy
147 pnpm run destroy
148 git worktree remove ../feat-x
149 ```
150
151 If the worktree is already gone, run the destroy from any checkout
152 with the stage spelled out.
153
154 ```sh
155 alchemy destroy --stage dev_sam_feat-x
156 alchemy destroy --stage live_sam_feat-x
157 ```
158
159 This works when the worktrees share a remote
160 [state store](/state-store). With local state, each worktree's state lives
161 in its own `.alchemy/` directory, so destroy before you delete it.