Worktree tools: support independent git repos nested inside the project home

Open
  • Is something wrong?
#899 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
14/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
git, rust
Domain
cli, tooling

Research direction

This is design work across several tools: create_worktree, list_worktrees, claim_worktree, release_worktree, remove_worktree, and the register_scope and wait_for_scope_clear scope matching. Start by confirming whether the path-based claim and remove tools already work on a nested repo's worktree, then decide how a repo or path argument should resolve the nearest git repo. Git calls must stay in-process through gix, as the no_subprocess_git_in_production rule requires. Done means the five asks are settled and split into separate issues.

Written by the indexing model from the issue text.

Description

area:mcp area:worktree needs-design type:feat

Problem

A project's home can be a meta-repo: the real work happens in independent git repos cloned into its subfolders, which are not submodules. create_worktree and list_worktrees always act on the project home's repo, so an agent can't make or list a worktree of a nested repo. The agent falls back to raw git worktree, which spyc's own guidance forbids, and from then on spyc's worktree view and cleanup never see those trees.

Reported from a session in which several background agents worked in one nested repo at once, each in its own worktree:

  • Merge race. Two agents merged to the same main at the same moment; one merge was rejected because the destination branch had been updated.
  • Killed agents. The parent session restarted and two agents were killed partway through their work.
  • No cleanup. Seven worktrees were left behind, several of them already merged.

Where spyc stands

  • create_worktree takes branch, base and open. Its repo is always the project's (PROJECT_HOME's), never one given by the caller. base already accepts any revision, so base: "origin/main" works, but nothing fetches first and there is no detached checkout.
  • list_worktrees takes no arguments and lists only the project repo's worktrees.
  • claim_worktree, release_worktree and remove_worktree take a path and resolve the worktree from that path's own .git, so they may already work on a nested repo's worktree given an absolute path. This is unverified, and list_worktrees can't help find one.
  • Claims are git's native worktree locks with a reason string. Nothing ties a claim to a live agent or session, so a killed agent's claim stays until someone releases it.
  • Scopes (register_scope, wait_for_scope_clear) match file paths and globs. Two merges into the same branch that touch different files don't overlap, so merging claims don't serialize them, in a nested repo or the home repo alike.

Asks

  1. Nested repos are first-class. Every worktree tool takes a repo (or path) argument, or resolves the nearest git repo from a path, so a worktree of a nested independent repo can be created, listed, claimed and cleaned like the home repo's.
  2. Worktrees from a remote ref. Fetch, then create from origin/main. Include a detached option for a "check out exactly what's on main" tree.
  3. Merges into one branch queue. A merging claim can name a repo and target branch, so wait_for_scope_clear serializes concurrent merges into the same branch even when their files don't overlap, in nested repos too.
  4. Lifecycle.
    • List and clean every worktree whose branch is merged, across the project's repos.
    • Expire a claim when the agent or session that owns it is gone.
  5. Optional: a merge helper. Rebase onto the latest main, run the repo's check, merge, and retry if main moved. #79 (the :land autopilot) was closed in favour of merging claims; this ask revisits it for agents that merge without a PR in between.

Notes

  • Related: #890 (create_worktree's fallback when the project home holds a stray .git).
  • Never git worktree: spyc's git is in-process through gix (no_subprocess_git_in_production), so a fetch in ask 2 goes through gix as well.
Dominant language
Rust
Stars
17
Forks
2
Avg merge
36m
Merged PRs (30d)
411

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Tripstack-Corp/spyc

All issues in Tripstack-Corp/spyc

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.