docs/jj-workspaces-for-parallel-work.md
When you need to reference or work with code from another branch without disrupting your current work, use jj workspaces. This creates a second working copy of the same repo at a different path, pointed at a different revision.
You're on feature-a actively coding. You need to send another Claude session a prompt like "study the tracing code on pr/main-fdb3446" — but you can't check out that branch without losing your current working state.
jj workspace addcd ~/code/org/project
jj workspace add ../project-traces -r pr/main-fdb3446
Flow wrapper (recommended):
cd ~/code/org/project
f jj workspace lane traces --base pr/main-fdb3446 --path ../project-traces
Now you have two working copies sharing the same repo:
| Path | Branch | Use |
|---|---|---|
~/code/org/project | feature-a | Your active work (untouched) |
~/code/org/project-traces | pr/main-fdb3446 | Full checkout for reference |
Point any tool or Claude session at the second path — it has all files on disk, no risk to your branch.
# Create workspace
jj workspace add ../project-ref -r some-branch
# Now another Claude session can freely explore:
# "study ~/code/org/project-ref — it has the tracing code"
# Clean up when done
jj workspace forget project-ref && rm -rf ../project-ref
# No workspace needed — jj reads any revision directly:
jj file show src/lib/tracing.ts -r pr/main-fdb3446
jj diff --from main --to pr/main-fdb3446 --stat
f jj workspace lane pr2 --base pr/feature-b --path ../project-pr2
# Edit files in both directories independently
# Both share the same jj repo — commits are visible everywhere
f jj workspace review review/alice-feature
cd ~/.jj/workspaces/project/review-alice-feature
Use this when you want one predictable workspace path for a specific review branch instead of a general-purpose lane.
f jj workspace lane fix-otp
f jj workspace lane release-testflight
By default this fetches and anchors each lane on <default_branch>@<remote> (or <default_branch> if the remote bookmark is missing).
.jj/ repo backend (no git clone, no duplication)@)jj log# List workspaces
jj workspace list
# Remove a workspace (keeps the commits, removes the directory association)
jj workspace forget <name>
rm -rf ../project-ref
| Need | Tool |
|---|---|
| Full directory for another tool/session to explore | jj workspace add |
| Stable branch-specific review workspace | f jj workspace review <branch> |
| Read a specific file from another branch | jj file show <path> -r <rev> |
| See what changed on another branch | jj diff --from main --to <branch> |
| Compare two branches | jj log -r 'branchA..branchB' |