git worktree: add adopt command for existing git worktrees

[calebdw]

Add jj git worktree adopt command that adopts existing Git worktrees
as jj workspaces. Three modes are supported:

• No arguments: adopts the Git worktree at the current directory.
• Named worktrees: jj git worktree adopt <name>... adopts specific
  Git worktrees by name from any jj workspace or git worktree.
• --all: adopts all unadopted Git worktrees at once.

The command works from within an existing jj workspace or from inside
an unadopted git worktree by discovering the parent jj repo via git.
Guardrails prevent adopting from the main workspace directory and
report clear errors for already-adopted or nonexistent worktrees.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (cli/src/config-schema.json)
• I have added/updated tests to cover my changes
• I fully understand the code that I am submitting (what it does,
  how it works, how it's organized), including any code drafted by an LLM.
• For any prose generated by an LLM, I have proof-read and copy-edited with
  an eye towards deleting anything that is irrelevant, clarifying anything
  that is confusing, and adding details that are relevant. This includes,
  for example, commit descriptions, PR descriptions, and code comments.

[yuja]

This looks quite messy. Can we instead add a maintenance command to enable/disable Git worktree?

[calebdw]

@yuja,

I've pushed updates that clean up the implementation and tried to make it less messy.

On the design question: this behavior only applies to colocated repositories. The whole point of colocation is that jj and git share the same working state---if a user has opted into colocation, then git worktrees are part of that shared state. When another process modifies git refs, HEAD, or the working copy outside of jj, the next jj command automatically imports those changes without requiring a maintenance command. I was trying to extend that same principle to worktrees, which are just another dimension of git state.

This is particularly relevant with AI coding tools (like Claude Code, Cursor, etc.), which increasingly use git worktree add/remove/move to manage parallel sessions. When one of those tools creates a git worktree and then runs jj inside it, it should just work: the same way running jj after git checkout just works today.

I'm not sure how a maintenance command would handle all the different cases that come up:

• Adopting externally-created worktrees: If someone runs git worktree add ../feature and then cd ../feature && jj status, a maintenance command means that first jj invocation fails instead of working.
• Forgetting removed worktrees: If an external tool runs git worktree remove, the jj workspace metadata becomes stale. This seems like it should be reconciled automatically, similar to how stale git refs are cleaned up during import.
• Repairing moved worktrees: git worktree move changes paths that jj tracks. This also feels like state that should be reconciled on the next operation.

Happy to discuss further if you have a specific design in mind.

[yuja]

When one of those tools creates a git worktree and then runs jj inside it, it should just work: the same way running jj after git checkout just works today.

Maybe I don't follow, but since a jj workspace isn't initialized yet, I don't expect jj would work in that Git worktree directory. It's different from running git checkout in an existing jj workspace.

I don't have a strong feeling about removed worktrees, but it isn't probably a new problem? A jj workspace can also be removed by rm -Rf.

[PhilipMetzger]

I agree with Yuya that this is to messy and see my other comment down in the stack.

[calebdw]

@yuja,

On auto-adopting worktrees: The whole premise of colocation is that jj and git share state, and jj automatically syncs that state on every invocation. When an external tool runs git checkout or modifies refs, jj imports those changes automatically---no maintenance command needed. Git worktrees are just another dimension of that shared git state. If an external tool (which knows nothing about jj) runs git worktree add ../feature, the resulting directory already points back to the same git repo that jj is colocated with. Requiring the user to then run something like jj workspace add --adopt is an unnecessary extra step when we have all the information needed to initialize the workspace automatically. This is especially relevant for AI coding tools that use git worktree add/remove to manage parallel sessions.

On reconciling removed worktrees: This actually is different from rm -Rf. When you rm -Rf a workspace directory, jj still tracks the workspace---it shows up in jj workspace list and jj log as secondary@ with a stale commit. The workspace metadata is orphaned. The same thing happens when an external tool runs git worktree remove. In a colocated repo, if the git worktree is gone, the corresponding jj workspace should be cleaned up too, otherwise you accumulate stale workspace references that the user has to manually forget.

[yuja]

As far as I can tell, colocation is a per-workspace state. Users can freely choose to add a non-colocated jj workspace or Git worktree.

I'm not against adding an opt-in feature to synchronize Git worktrees and jj workspaces automatically (similar to snapshot.auto-update-stale), but an explicit command should come first.

[calebdw]

@yuja, @PhilipMetzger I've restructured the PRs 👍

[yuja]

Same here. Something like jj git workspace adapt seems better.