|
1 | | -# Git worktrees for parallel Claude Code sessions |
| 1 | +# Worktree conventions for bitsandbytes |
2 | 2 |
|
3 | | -## The problem |
| 3 | +For general worktree concepts, setup, and the worktree registry, see `~/git/lab_tools/worktree_guide.md`. This file covers bitsandbytes-specific conventions only. |
4 | 4 |
|
5 | | -When you run Claude Code on a repo, the session builds up context about the files, the branch state, and what it has already done. If you switch branches in the same directory, that context becomes stale -- Claude thinks it is looking at one version of the code, but the files on disk have changed underneath it. |
| 5 | +## Naming |
6 | 6 |
|
7 | | -Two Claude sessions in the same directory will also step on each other's file writes. There is no locking mechanism. If session A edits `server.py` while session B is also editing `server.py`, one of them will silently overwrite the other. |
| 7 | +Worktree directories for bitsandbytes use the short prefix `bnb-`: |
8 | 8 |
|
9 | | -Git worktrees solve both problems. A worktree is a second (or third, or fourth) checkout of the same repository in a different directory. Each worktree has its own working tree with its own branch checked out, but they all share the same `.git` history and remotes. No cloning, no duplicate disk usage for the object store, no extra credential setup. You use whatever global `claude` installation you already have. |
| 9 | +| Purpose | Directory | Branch | |
| 10 | +|---|---|---| |
| 11 | +| Issue fix | `~/git/bnb-fix-<NUMBER>` | `fix/issue-<NUMBER>` | |
| 12 | +| Feature | `~/git/bitsandbytes-<name>` | `feature/<name>` | |
| 13 | +| Experiment | `~/git/bnb-kbit-gemm` | `feature/kbit-gemv-v8` | |
| 14 | +| Deprecation | `~/git/bnb-deprecation` | `deprecation` | |
10 | 15 |
|
11 | | -## Quick start |
12 | | - |
13 | | -Suppose your repo lives at `~/git/bitsandbytes` and you are on `main`. |
14 | | - |
15 | | -Create a worktree for a feature branch: |
16 | | - |
17 | | -```bash |
18 | | -git worktree add ../bitsandbytes-feature-auth -b feature/auth |
19 | | -``` |
20 | | - |
21 | | -This does two things: creates a new branch `feature/auth` (from your current HEAD) and checks it out into `~/git/bitsandbytes-feature-auth`. The directory is created automatically. |
22 | | - |
23 | | -If the branch already exists on the remote: |
24 | | - |
25 | | -```bash |
26 | | -git fetch origin |
27 | | -git worktree add ../bitsandbytes-feature-auth feature/auth |
28 | | -``` |
29 | | - |
30 | | -Now open a second terminal, cd into the new directory, and run `claude`. You have two fully independent sessions -- one in `bitsandbytes` on `main`, one in `bitsandbytes-feature-auth` on `feature/auth`. Same git history, same remotes, completely isolated files. |
31 | | - |
32 | | -Create as many as you need: |
33 | | - |
34 | | -```bash |
35 | | -git worktree add ../bitsandbytes-fix-422 -b fix/issue-422 |
36 | | -git worktree add ../bitsandbytes-experiment -b experiment/new-quantizer |
37 | | -``` |
38 | | - |
39 | | -## Directory layout |
| 16 | +For issue-related work, always include the issue number. The dispatch workflow generates worktrees with this pattern automatically. |
40 | 17 |
|
41 | | -After creating a couple of worktrees, your filesystem looks like this: |
42 | | - |
43 | | -``` |
44 | | -~/git/ |
45 | | -├── bitsandbytes/ # main branch (original clone) |
46 | | -├── bitsandbytes-feature-auth/ # feature/auth branch |
47 | | -├── bitsandbytes-fix-422/ # fix/issue-422 branch |
48 | | -└── bitsandbytes-experiment/ # experiment/new-quantizer branch |
49 | | -``` |
50 | | - |
51 | | -Each directory is a full working tree. You can run tests, install dependencies, and launch Claude Code independently in each one. They all share the `.git` object store from the original clone, so disk usage stays low. |
52 | | - |
53 | | -## Managing worktrees |
54 | | - |
55 | | -List all active worktrees: |
56 | | - |
57 | | -```bash |
58 | | -git worktree list |
59 | | -``` |
60 | | - |
61 | | -Output looks like: |
62 | | - |
63 | | -``` |
64 | | -/home/you/git/bitsandbytes abc1234 [main] |
65 | | -/home/you/git/bitsandbytes-feature-auth def5678 [feature/auth] |
66 | | -/home/you/git/bitsandbytes-fix-422 ghi9012 [fix/issue-422] |
67 | | -``` |
68 | | - |
69 | | -Remove a worktree when you are done with it: |
70 | | - |
71 | | -```bash |
72 | | -git worktree remove ../bitsandbytes-fix-422 |
73 | | -``` |
74 | | - |
75 | | -If you already deleted the directory manually, clean up the stale reference: |
76 | | - |
77 | | -```bash |
78 | | -git worktree prune |
79 | | -``` |
80 | | - |
81 | | -## Setting up each worktree |
82 | | - |
83 | | -Each worktree is its own directory, so project dependencies need to be installed separately. After creating a worktree: |
84 | | - |
85 | | -**Python projects:** |
86 | | -```bash |
87 | | -cd ../bitsandbytes-feature-auth |
88 | | -python -m venv .venv |
89 | | -source .venv/bin/activate |
90 | | -pip install -e ".[dev]" |
91 | | -``` |
92 | | - |
93 | | -**Node projects:** |
94 | | -```bash |
95 | | -cd ../bitsandbytes-feature-auth |
96 | | -npm install |
97 | | -``` |
98 | | - |
99 | | -This is a one-time cost per worktree. After that, the environment is fully independent. |
100 | | - |
101 | | -## Running parallel Claude Code sessions |
102 | | - |
103 | | -The workflow is straightforward: |
104 | | - |
105 | | -1. Create a worktree per branch (see above). |
106 | | -2. Open a separate terminal for each worktree. |
107 | | -3. Run `claude` in each terminal. |
108 | | -4. Each session gets its own independent context, file state, and history. |
109 | | - |
110 | | -Claude Code sessions are directory-scoped. The session picker (`/resume`) groups sessions by repository, including worktrees, so you can tell them apart. Use `/rename` early to give each session a descriptive name like "auth feature" or "quantizer experiment". |
111 | | - |
112 | | -**Do not resume the same session in multiple terminals.** Messages get interleaved and the context becomes incoherent. If you need to branch off an existing session, use `claude --fork-session` to create a clean copy. |
113 | | - |
114 | | -## Working with different models |
115 | | - |
116 | | -You can run different models in different worktrees. This is useful when you want a faster model for straightforward tasks and a stronger model for harder ones: |
117 | | - |
118 | | -```bash |
119 | | -# Terminal 1: use Opus for the complex feature |
120 | | -cd ~/git/bitsandbytes-feature-auth |
121 | | -claude --model opus |
122 | | - |
123 | | -# Terminal 2: use Sonnet for a simple bugfix |
124 | | -cd ~/git/bitsandbytes-fix-422 |
125 | | -claude --model sonnet |
126 | | -``` |
127 | | - |
128 | | -Each session is independent, so there is no conflict. |
129 | | - |
130 | | -## Merging work back |
131 | | - |
132 | | -Worktrees share the same git history, so merging is the same as with regular branches: |
| 18 | +## Quick start |
133 | 19 |
|
134 | 20 | ```bash |
135 | | -# From the main worktree |
136 | 21 | cd ~/git/bitsandbytes |
137 | | -git merge feature/auth |
| 22 | +git worktree add ~/git/bnb-fix-<NUMBER> -b fix/issue-<NUMBER> |
| 23 | +cd ~/git/bnb-fix-<NUMBER> |
138 | 24 | ``` |
139 | 25 |
|
140 | | -Or push the branch and create a PR on GitHub as usual: |
141 | | - |
142 | | -```bash |
143 | | -# From the feature worktree |
144 | | -cd ~/git/bitsandbytes-feature-auth |
145 | | -git push -u origin feature/auth |
146 | | -gh pr create --title "Add auth support" |
147 | | -``` |
| 26 | +## Build and test |
148 | 27 |
|
149 | | -After merging, clean up: |
| 28 | +After creating a worktree, read `agents/testing_guide.md` for build instructions. Run only the tests relevant to your change — not the full suite. |
150 | 29 |
|
151 | | -```bash |
152 | | -git worktree remove ../bitsandbytes-feature-auth |
153 | | -git branch -d feature/auth |
154 | | -``` |
| 30 | +## Dispatch workflow |
155 | 31 |
|
156 | | -## Rules and constraints |
| 32 | +When launched via the dispatch guide (`agents/dispatch_guide.md`), worker agents receive prompt files that include worktree creation commands. The prompts follow the naming conventions above. Workers must create their worktree before starting work. |
157 | 33 |
|
158 | | -- **One branch per worktree.** You cannot check out the same branch in two worktrees. Git enforces this. If you need two sessions on the same branch, clone the repo instead. |
159 | | -- **Do not delete the main worktree.** The original clone directory is the "main" worktree. You can remove any worktree you created with `git worktree add`, but not the original. |
160 | | -- **Shared refs.** All worktrees see the same branches, tags, and remotes. A `git fetch` in one worktree updates refs for all of them. Commits are visible across worktrees immediately (though the working tree files are not -- each worktree only shows files for its checked-out branch). |
161 | | -- **Stash is shared.** `git stash` entries are visible from all worktrees. This can be confusing. Prefer committing work-in-progress to a branch rather than stashing. |
| 34 | +## Completion |
162 | 35 |
|
163 | | -## Cheat sheet |
| 36 | +After implementing and verifying a fix: |
164 | 37 |
|
165 | | -| Task | Command | |
166 | | -|---|---| |
167 | | -| Create worktree + new branch | `git worktree add ../dir -b branch-name` | |
168 | | -| Create worktree for existing branch | `git worktree add ../dir branch-name` | |
169 | | -| List worktrees | `git worktree list` | |
170 | | -| Remove a worktree | `git worktree remove ../dir` | |
171 | | -| Clean up deleted worktrees | `git worktree prune` | |
172 | | -| Rename Claude session | `/rename` inside the session | |
173 | | -| Resume a session | `/resume` inside claude | |
174 | | -| Fork a session | `claude --fork-session` | |
| 38 | +1. Commit with a message referencing the issue: `git commit -m "Fix <description> (#<NUMBER>)"` |
| 39 | +2. Push: `git push -u origin fix/issue-<NUMBER>` |
| 40 | +3. Create a PR with `gh pr create` — include "Fixes #<NUMBER>" in the body. |
| 41 | +4. The worktree manager cron job will clean up the worktree after the PR is merged. |
0 commit comments