feat(worktree): develop against a fork and its upstream from one clone

[aclark4life]

Problem

dbx clone django gives you one checkout of mongodb-forks/django with an upstream remote. Fork maintenance regularly needs both sides at once — reading upstream Django to see what changed, and editing the fork branch to adapt. A second clone means a second full fetch of Django's history and two object stores to keep current.

Solution

Git worktree support, so one clone has both checked out sharing a single object store:

base_dir/django/django/            # fork clone, on mongodb-6.0.x (origin = mongodb-forks)
base_dir/django/django-upstream/   # worktree, on upstream-main (tracks upstream/main)

Comparisons are then local and immediate: git log upstream-main..mongodb-6.0.x.

• dbx worktree add|list|remove — manages worktrees for any repo.
• upstream_worktree group config key — dbx clone creates the worktree automatically. Enabled for django.
• find_all_repos now tags each entry worktree. Worth noting: a linked worktree has .git as a file, so the existing .exists() check was already picking them up as ordinary repos.

The worktree's branch is upstream-<default branch>, not the bare branch name, so it can't collide with a same-named branch already tracking origin in the fork.

Which commands see worktrees

Read-only commands include them; commands that write to a checkout skip them.

Command	Worktrees	Why
status, log, branch	included	Read-only — seeing the upstream checkout's state is the point
sync	skipped	Rebase onto upstream + force-push to origin would push upstream's history into the fork
switch -g <group>	skipped	One checkout per branch; a bulk switch would fail or move a tree in use
install -g <group>	skipped	Shares its clone's package name; would replace the clone's editable install in the group venv

sync is guarded in _sync_repository, the worker all four sync paths route through, so an explicitly named worktree is refused too — the force-push isn't recoverable. switch filters group enumeration only; dbx switch <worktree> <branch> stays allowed, since it's reversible and git refuses on its own if the branch is checked out elsewhere.

dbx remove removes worktrees before their clone and goes through git worktree remove, so no stale .git/worktrees entries.

Testing

467 tests pass (24 new). The worktree tests drive real git repositories rather than mocking subprocess, since the behaviour depends on git's own bookkeeping — .git as a file, worktree registrations, refusing a branch checked out twice. One test asserts subprocess.run is never called for a worktree in sync, so the guard can't regress into "runs git, then bails".

Docs updated in features/repo-management.rst, features/django-fork.rst, design/command-structure.rst, and the API pages; sphinx builds clean.