From 801d356b72894db918cb340007cc1470148ecc94 Mon Sep 17 00:00:00 2001
From: Jeffrey 'Alex' Clark <alex.clark@mongodb.com>
Date: Tue, 25 Aug 2026 15:14:11 -0400
Subject: [PATCH 1/3] feat(worktree): develop against a fork and its upstream
 from one clone

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.

Add git worktree support so one clone can have both checked out, sharing
a single object store:

  base_dir/django/django/            # fork clone, on mongodb-6.0.x
  base_dir/django/django-upstream/   # worktree, on upstream-main

- New `dbx worktree add|list|remove`.
- New `upstream_worktree` group config key, honoured by `dbx clone`
  right after the preferred-branch switch. Enabled for django.
- `find_all_repos` now tags each entry `worktree` (a linked worktree has
  .git as a file, so it was already being picked up as an ordinary repo
  by the existing .exists() check).

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

Read-only commands (status, log, branch) include worktrees; commands
that write to a checkout skip them:

- sync: rebasing a worktree onto upstream and force-pushing to origin
  would push upstream's history into the fork. Guarded in
  _sync_repository, the worker every sync path routes through, so an
  explicitly named worktree is refused too.
- switch -g: a branch can only be checked out in one worktree at a time.
  Only group enumeration is filtered; `dbx switch <worktree> <branch>`
  stays allowed, since it is reversible and git refuses on its own if
  the branch is checked out elsewhere.
- install -g: a worktree shares its clone's package name and would
  replace the clone's editable install in the group venv.

`dbx remove` removes worktrees before the clone they belong to and goes
through `git worktree remove`, so no stale .git/worktrees entries.
---
 docs/api/commands.rst                   |   8 +
 docs/api/utils.rst                      |   8 +
 docs/design/command-structure.rst       |   5 +
 docs/features/django-fork.rst           |  89 +++++++
 docs/features/repo-management.rst       |  74 ++++++
 src/dbx_python_cli/cli.py               |   2 +
 src/dbx_python_cli/commands/clone.py    |  21 ++
 src/dbx_python_cli/commands/install.py  |  24 +-
 src/dbx_python_cli/commands/remove.py   |  28 ++-
 src/dbx_python_cli/commands/switch.py   |   8 +-
 src/dbx_python_cli/commands/sync.py     |  12 +-
 src/dbx_python_cli/commands/worktree.py | 216 +++++++++++++++++
 src/dbx_python_cli/config.toml          |   4 +
 src/dbx_python_cli/utils/repo.py        |  61 ++++-
 src/dbx_python_cli/utils/worktree.py    | 268 +++++++++++++++++++++
 tests/test_worktree_command.py          | 302 ++++++++++++++++++++++++
 16 files changed, 1115 insertions(+), 15 deletions(-)
 create mode 100644 src/dbx_python_cli/commands/worktree.py
 create mode 100644 src/dbx_python_cli/utils/worktree.py
 create mode 100644 tests/test_worktree_command.py

diff --git a/docs/api/commands.rst b/docs/api/commands.rst
index 710e192..eb83da4 100644
--- a/docs/api/commands.rst
+++ b/docs/api/commands.rst
@@ -130,3 +130,11 @@ dbx_python_cli.commands.test module
    :members:
    :undoc-members:
    :show-inheritance:
+
+dbx_python_cli.commands.worktree module
+---------------------------------------
+
+.. automodule:: dbx_python_cli.commands.worktree
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
index a73073e..bce4cf5 100644
--- a/docs/api/utils.rst
+++ b/docs/api/utils.rst
@@ -34,3 +34,11 @@ dbx_python_cli.utils.venv module
    :members:
    :undoc-members:
    :show-inheritance:
+
+dbx_python_cli.utils.worktree module
+------------------------------------
+
+.. automodule:: dbx_python_cli.utils.worktree
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/design/command-structure.rst b/docs/design/command-structure.rst
index 953eccf..7ab80e2 100644
--- a/docs/design/command-structure.rst
+++ b/docs/design/command-structure.rst
@@ -97,6 +97,11 @@ Related subcommands that share a common domain:
    dbx project list
    dbx project remove
 
+   # Git worktree management
+   dbx worktree add django --upstream
+   dbx worktree list django
+   dbx worktree remove django
+
 Command Groups (Two Levels)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/features/django-fork.rst b/docs/features/django-fork.rst
index 6d157d0..6414176 100644
--- a/docs/features/django-fork.rst
+++ b/docs/features/django-fork.rst
@@ -42,6 +42,10 @@ organisation rather than a personal account:
    [repo.groups.django.preferred_branch]
    django = "mongodb-6.0.x"
 
+   # Add a `django-upstream` worktree on clone so the fork and upstream Django
+   # can both be worked on from one clone
+   upstream_worktree = ["django"]
+
 Each key plays a specific role in fork maintenance:
 
 ``no_fork``
@@ -65,6 +69,11 @@ Each key plays a specific role in fork maintenance:
 ``preferred_branch``
    The branch ``dbx clone`` switches to automatically after cloning.
 
+``upstream_worktree``
+   Lists repos that get a sibling git worktree checked out on the upstream
+   default branch immediately after cloning. See
+   :ref:`django-fork-upstream-worktree`.
+
 Cloning the fork
 ----------------
 
@@ -87,6 +96,86 @@ To clone only the Django fork itself:
 
    dbx clone django
 
+.. _django-fork-upstream-worktree:
+
+Developing against the fork and upstream from one clone
+-------------------------------------------------------
+
+Fork maintenance regularly needs both sides at once: reading upstream Django to
+see what changed, and editing the fork branch to adapt to it. A second clone
+would mean a second full fetch of Django's history and two object stores to keep
+current.
+
+A git *worktree* avoids that. One clone can have several branches checked out at
+the same time, each in its own directory, all sharing a single ``.git`` object
+store. Because ``upstream_worktree = ["django"]`` is set, ``dbx clone`` creates
+one automatically:
+
+.. code-block:: text
+
+   ~/Developer/mongodb/django/
+     django/            # primary clone, on mongodb-6.0.x (origin = mongodb-forks)
+     django-upstream/   # worktree, on upstream-main (tracks upstream/main)
+
+The worktree's branch is named ``upstream-<default branch>`` rather than just
+``main``, so it cannot collide with a branch of the same name already tracking
+``origin`` in the fork.
+
+Fetching in either directory updates the shared object store, so comparisons
+between the two are local and immediate:
+
+.. code-block:: bash
+
+   cd ~/Developer/mongodb/django/django
+   git log upstream-main..mongodb-6.0.x        # what the fork adds
+   git diff upstream-main -- django/db/models  # what the fork changed
+
+Managing worktrees manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``dbx worktree`` manages worktrees for any repo, whether or not
+``upstream_worktree`` is configured:
+
+.. code-block:: bash
+
+   # Add the upstream worktree (django-upstream, on the upstream default branch)
+   dbx worktree add django --upstream
+
+   # Check out a specific upstream branch (django-stable-6.1.x)
+   dbx worktree add django stable/6.1.x --upstream
+
+   # Check out an existing fork branch alongside the current one
+   dbx worktree add django mongodb-6.2.x
+
+   # Override the directory suffix
+   dbx worktree add django stable/6.1.x --upstream --label 61
+
+   # Show every checkout attached to the clone (* marks the primary one)
+   dbx worktree list django
+
+   # Remove by directory suffix (defaults to `upstream`)
+   dbx worktree remove django
+   dbx worktree remove django 61 --force
+
+Removal goes through ``git worktree remove`` so the registration inside the
+primary clone is cleaned up too; deleting the directory by hand would leave a
+stale entry that blocks recreating the worktree later. ``dbx remove`` handles
+this as well, removing worktrees before the clone they belong to.
+
+A branch can only be checked out in one worktree at a time. ``dbx worktree add``
+reports git's refusal rather than working around it, so the fork branch you are
+editing is never silently moved out from under you.
+
+.. note::
+
+   ``django-upstream`` is skipped by ``dbx sync``, ``dbx switch -g django`` and
+   ``dbx install -g django`` — see :ref:`upstream-worktrees` for why. It still
+   appears in ``dbx status``, ``dbx log`` and ``dbx branch``, which only read.
+
+   In particular, the fork clone stays the installed one: a Django worktree has
+   the same package name, so installing it would replace the fork checkout as
+   the live ``django`` package in the group venv.
+
 Syncing a branch with upstream
 ------------------------------
 
diff --git a/docs/features/repo-management.rst b/docs/features/repo-management.rst
index 17e8a41..d24e7e0 100644
--- a/docs/features/repo-management.rst
+++ b/docs/features/repo-management.rst
@@ -241,6 +241,79 @@ completes — equivalent to running ``dbx sync mongo-python-driver`` right after
 - Like ``dbx sync``, it's a no-op (with a warning) if no ``upstream`` remote ends up configured for the repo
 - Pass ``--no-sync`` to ``dbx clone`` to skip this for a single invocation even when configured
 
+.. _upstream-worktrees:
+
+Upstream Worktrees
+~~~~~~~~~~~~~~~~~~
+
+A git worktree lets a single clone keep several branches checked out at once, in
+separate directories sharing one object store. That makes it possible to develop
+against a fork *and* its upstream without cloning the upstream separately.
+
+List a repo in ``upstream_worktree`` to have ``dbx clone`` create one:
+
+.. code-block:: toml
+
+   [repo.groups.django]
+   upstream_worktree = ["django"]
+
+Cloning then produces a sibling directory checked out on the upstream default
+branch, under a branch named ``upstream-<default branch>`` so it cannot collide
+with a same-named branch tracking ``origin``:
+
+.. code-block:: text
+
+   base_dir/django/django/            # fork clone, on its preferred branch
+   base_dir/django/django-upstream/   # worktree, on upstream-main
+
+Manage worktrees for any repo with ``dbx worktree``:
+
+.. code-block:: bash
+
+   dbx worktree add <repo> --upstream        # upstream default branch
+   dbx worktree add <repo> <branch>          # an existing branch, alongside the current one
+   dbx worktree add <repo> <branch> -u       # an upstream branch
+   dbx worktree list <repo>                  # every checkout (* marks the primary clone)
+   dbx worktree remove <repo> [<label>]      # defaults to the `upstream` worktree
+
+**Notes:**
+
+- Requires an ``upstream`` remote; on clone this comes from the ``upstream`` config key
+- Worktree directories are named ``<repo>-<label>``, where ``label`` defaults to the branch name with ``/`` replaced by ``-``
+- A branch can only be checked out in one worktree at a time; ``dbx worktree add`` reports git's refusal rather than moving it
+- ``dbx remove`` unregisters worktrees via ``git worktree remove`` and removes them before the clone they belong to
+
+Which commands see worktrees
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Commands that only read are happy to include worktrees; commands that write to
+a checkout skip them:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Command
+     - Worktrees
+     - Why
+   * - ``dbx status``, ``dbx log``, ``dbx branch``
+     - included
+     - Read-only, and seeing the upstream checkout's state is useful
+   * - ``dbx sync``
+     - skipped
+     - Rebasing a worktree onto upstream and force-pushing it to ``origin`` would push upstream's history into the fork
+   * - ``dbx switch -g <group>``
+     - skipped
+     - A branch can only be checked out in one worktree at a time, so a bulk switch would fail or move a checkout in use
+   * - ``dbx install -g <group>``
+     - skipped
+     - A worktree shares its clone's package name; installing it would replace the clone's editable install in the group venv
+
+``dbx sync`` refuses a worktree even when you name one explicitly, because the
+force-push is not recoverable. ``dbx switch <worktree> <branch>`` is allowed —
+it is reversible, and git refuses on its own if the branch is checked out
+elsewhere.
+
 .. _config-driven-upstream:
 
 Config-Driven Upstream Remotes
@@ -428,6 +501,7 @@ Per-group keys of note:
 - ``upstream`` — upstream remote URLs added automatically on clone (see :ref:`config-driven-upstream`)
 - ``upstream_branch`` — upstream branch override for ``dbx sync`` (see :ref:`config-driven-upstream`)
 - ``sync_after_clone`` — list of repo names to automatically ``dbx sync`` immediately after cloning (see :ref:`sync-after-clone`)
+- ``upstream_worktree`` — list of repo names that get an upstream git worktree created on clone (see :ref:`upstream-worktrees`)
 - ``install_extras``, ``install_groups`` — default extras / dependency groups installed by ``dbx install``
 - ``install_dirs`` — sub-directory paths for repos that contain multiple packages
 - ``build_commands`` — shell commands run before installation (e.g. a Rust or CMake build)
diff --git a/src/dbx_python_cli/cli.py b/src/dbx_python_cli/cli.py
index 748c6c0..bd050f4 100644
--- a/src/dbx_python_cli/cli.py
+++ b/src/dbx_python_cli/cli.py
@@ -25,6 +25,7 @@
     switch,
     sync,
     test,
+    worktree,
 )
 
 
@@ -77,6 +78,7 @@ def get_help_text():
 app.add_typer(switch.app, name="switch")
 app.add_typer(sync.app, name="sync")
 app.add_typer(test.app, name="test")
+app.add_typer(worktree.app, name="worktree")
 
 
 def version_callback(value: bool):
diff --git a/src/dbx_python_cli/commands/clone.py b/src/dbx_python_cli/commands/clone.py
index d01d30b..96f3967 100644
--- a/src/dbx_python_cli/commands/clone.py
+++ b/src/dbx_python_cli/commands/clone.py
@@ -5,6 +5,7 @@
 
 import typer
 
+from dbx_python_cli.commands.worktree import create_upstream_worktree
 from dbx_python_cli.utils import repo
 from dbx_python_cli.utils.repo import (
     get_group_dir,
@@ -13,6 +14,8 @@
     get_upstream_url,
     is_flat_mode,
     should_sync_after_clone,
+)
+from dbx_python_cli.utils.repo import (
     switch_to_branch as _switch_to_branch,
 )
 
@@ -770,6 +773,24 @@ def clone_callback(
                             repo_path, repo_name, config_group, config, verbose
                         )
 
+                    # Create the upstream worktree if configured, so the fork
+                    # and its upstream can both be worked on from this clone.
+                    if clone_success and repo.should_create_upstream_worktree(
+                        config, config_group, repo_name
+                    ):
+                        wt_ok, wt_message = create_upstream_worktree(
+                            repo_path, repo_name, config_group, config, verbose
+                        )
+                        if wt_ok:
+                            typer.echo(
+                                f"  🌿 {repo_name}: upstream worktree at {wt_message}"
+                            )
+                        else:
+                            typer.echo(
+                                f"  ⚠️  {repo_name}: upstream worktree skipped ({wt_message})",
+                                err=True,
+                            )
+
                     # Track successful clone for auto-install
                     if clone_success:
                         cloned_repos.append(
diff --git a/src/dbx_python_cli/commands/install.py b/src/dbx_python_cli/commands/install.py
index 21f2c36..5e7804a 100644
--- a/src/dbx_python_cli/commands/install.py
+++ b/src/dbx_python_cli/commands/install.py
@@ -494,7 +494,11 @@ def install_callback(
                     )
                     raise typer.Exit(1)
 
-                group_repos = [r for r in all_repos if r["group"] == grp]
+                # Worktrees share their clone's package name; installing one would
+                # replace the primary checkout's editable install in the group venv.
+                group_repos = [
+                    r for r in all_repos if r["group"] == grp and not r.get("worktree")
+                ]
                 if not group_repos:
                     typer.echo(
                         f"❌ Error: No repositories found in group '{grp}'", err=True
@@ -509,7 +513,11 @@ def install_callback(
 
             # Show options for all groups
             for grp in groups:
-                group_repos = [r for r in all_repos if r["group"] == grp]
+                # Worktrees share their clone's package name; installing one would
+                # replace the primary checkout's editable install in the group venv.
+                group_repos = [
+                    r for r in all_repos if r["group"] == grp and not r.get("worktree")
+                ]
 
                 if len(groups) > 1:
                     typer.echo(f"{'#' * 60}")
@@ -676,7 +684,11 @@ def install_callback(
                 typer.echo(f"❌ Error: Group '{grp}' not found in {base_dir}", err=True)
                 raise typer.Exit(1)
 
-            group_repos = [r for r in all_repos if r["group"] == grp]
+            # Worktrees share their clone's package name; installing one would
+            # replace the primary checkout's editable install in the group venv.
+            group_repos = [
+                r for r in all_repos if r["group"] == grp and not r.get("worktree")
+            ]
             if not group_repos:
                 typer.echo(
                     f"❌ Error: No repositories found in group '{grp}'", err=True
@@ -696,7 +708,11 @@ def install_callback(
 
         for grp in groups:
             group_path = get_group_dir(base_dir, grp, flat)
-            group_repos = [r for r in all_repos if r["group"] == grp]
+            # Worktrees share their clone's package name; installing one would
+            # replace the primary checkout's editable install in the group venv.
+            group_repos = [
+                r for r in all_repos if r["group"] == grp and not r.get("worktree")
+            ]
 
             if len(groups) > 1:
                 typer.echo(f"\n{'#' * 60}")
diff --git a/src/dbx_python_cli/commands/remove.py b/src/dbx_python_cli/commands/remove.py
index 2038f8b..0376b67 100644
--- a/src/dbx_python_cli/commands/remove.py
+++ b/src/dbx_python_cli/commands/remove.py
@@ -8,6 +8,7 @@
 import typer
 
 from dbx_python_cli.utils import repo
+from dbx_python_cli.utils.worktree import prune_worktrees, remove_worktree
 
 app = typer.Typer(
     help="Remove repositories or repository groups",
@@ -180,13 +181,32 @@ def remove_callback(
     failed_count = 0
 
     typer.echo()
+    # Remove worktrees before their primary clones: `git worktree remove` needs
+    # the clone's .git directory, and deleting the clone first would strand the
+    # worktree with a dangling gitdir pointer.
+    repos_to_remove = sorted(
+        repos_to_remove, key=lambda r: not r.get("worktree", False)
+    )
     for repo_info in repos_to_remove:
         repo_path = Path(repo_info["path"])
         try:
-            if verbose:
-                typer.echo(f"[verbose] Removing directory: {repo_path}")
-
-            shutil.rmtree(repo_path)
+            if repo_info.get("worktree"):
+                if verbose:
+                    typer.echo(f"[verbose] Removing worktree: {repo_path}")
+                # --force: the confirmation prompt above is the safety gate, and
+                # git otherwise refuses whenever the worktree is dirty.
+                ok, message = remove_worktree(
+                    repo_path, repo_path, force=True, verbose=verbose
+                )
+                if not ok:
+                    raise RuntimeError(message)
+            else:
+                if verbose:
+                    typer.echo(f"[verbose] Removing directory: {repo_path}")
+                # Drop registrations for worktrees removed above so the clone's
+                # metadata is consistent if anything later inspects it.
+                prune_worktrees(repo_path, verbose=verbose)
+                shutil.rmtree(repo_path)
             typer.echo(f"✅ Removed {repo_info['name']} ({repo_info['group']})")
             removed_count += 1
         except Exception as e:
diff --git a/src/dbx_python_cli/commands/switch.py b/src/dbx_python_cli/commands/switch.py
index 0588c9f..3c708ad 100644
--- a/src/dbx_python_cli/commands/switch.py
+++ b/src/dbx_python_cli/commands/switch.py
@@ -120,9 +120,13 @@ def switch_callback(
             typer.echo(f"Available groups: {', '.join(groups.keys())}", err=True)
             raise typer.Exit(1)
 
-        # Find all repos in the group
+        # Find all repos in the group. Worktrees are excluded: a branch can only
+        # be checked out in one worktree at a time, so a bulk switch would either
+        # fail on them or move a checkout the user is working in.
         all_repos = find_all_repos(base_dir, config)
-        group_repos = [r for r in all_repos if r["group"] == group]
+        group_repos = [
+            r for r in all_repos if r["group"] == group and not r.get("worktree")
+        ]
 
         if not group_repos:
             typer.echo(
diff --git a/src/dbx_python_cli/commands/sync.py b/src/dbx_python_cli/commands/sync.py
index 6e6f3bf..9d105c5 100644
--- a/src/dbx_python_cli/commands/sync.py
+++ b/src/dbx_python_cli/commands/sync.py
@@ -10,6 +10,7 @@
 
 from dbx_python_cli.utils import repo
 from dbx_python_cli.utils.output import paginate_output, should_use_pager
+from dbx_python_cli.utils.repo import is_worktree
 
 app = typer.Typer(
     help="Sync repositories with upstream",
@@ -710,7 +711,8 @@ def sync_callback(
     )
 
     def _enrich(repo_list):
-        """Attach upstream_branch from config to each repo_info dict."""
+        """Drop worktrees, then attach upstream_branch from config to each repo."""
+        repo_list = [r for r in repo_list if not r.get("worktree")]
         for r in repo_list:
             r["upstream_branch"] = get_upstream_branch(config, r["group"], r["name"])
         return repo_list
@@ -956,6 +958,14 @@ def _sync_repository(
     Returns:
         "synced", "skipped", "failed", or "dry_run"
     """
+    # Worktrees track a branch of the clone they belong to (typically an upstream
+    # branch). Rebasing one onto upstream and force-pushing it to origin would
+    # push upstream's history into the fork, so sync never touches them; sync the
+    # primary clone instead.
+    if is_worktree(repo_path):
+        typer.echo(f"⏭️  Skipping {repo_name} (worktree)")
+        return "skipped"
+
     if dry_run:
         typer.echo(f"🔍 Checking {repo_name}")
     else:
diff --git a/src/dbx_python_cli/commands/worktree.py b/src/dbx_python_cli/commands/worktree.py
new file mode 100644
index 0000000..697ed93
--- /dev/null
+++ b/src/dbx_python_cli/commands/worktree.py
@@ -0,0 +1,216 @@
+"""Manage git worktrees so one clone can serve fork and upstream development."""
+
+import typer
+
+from dbx_python_cli.utils.repo import (
+    find_repo_by_name,
+    get_base_dir,
+    get_config,
+    is_flat_mode,
+)
+from dbx_python_cli.utils.worktree import (
+    UPSTREAM_LABEL,
+    add_worktree,
+    branch_to_label,
+    get_remote_head_branch,
+    get_worktree_dir,
+    has_remote,
+    list_worktrees,
+    remove_worktree,
+)
+
+app = typer.Typer(
+    help="Manage git worktrees for a repository",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _resolve_repo(repo_name, config, verbose):
+    """Locate a cloned repo by name, reporting and exiting when it is missing."""
+    base_dir = get_base_dir(config)
+    repo = find_repo_by_name(repo_name, base_dir, config)
+    if not repo:
+        typer.echo(f"❌ Repository '{repo_name}' not found in {base_dir}", err=True)
+        raise typer.Exit(1)
+    if repo.get("worktree"):
+        typer.echo(
+            f"❌ '{repo_name}' is itself a worktree. Run this against the primary clone.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    if verbose:
+        typer.echo(f"  [verbose] Repo path: {repo['path']}")
+    return repo, base_dir
+
+
+def create_upstream_worktree(repo_path, repo_name, group, config, verbose=False):
+    """Create the ``<repo>-upstream`` worktree for a freshly cloned fork.
+
+    Shared with ``dbx clone`` so the ``upstream_worktree`` config key and the
+    ``dbx worktree add --upstream`` flag behave identically.
+
+    The worktree checks out a local branch named ``upstream-<default branch>``
+    rather than the bare default branch name, so it cannot collide with a
+    same-named branch already tracking ``origin`` in the fork.
+
+    Args:
+        repo_path: Path to the primary clone
+        repo_name: Repository name
+        group: Group the repo belongs to
+        config: Configuration dictionary
+        verbose: Print git invocations
+
+    Returns:
+        tuple: ``(ok, message)`` — *message* explains the failure when not ok.
+    """
+    if not has_remote(repo_path, "upstream"):
+        return False, "no 'upstream' remote configured"
+
+    upstream_branch = get_remote_head_branch(repo_path, "upstream", verbose=verbose)
+    if not upstream_branch:
+        return False, "could not determine the upstream default branch"
+
+    base_dir = get_base_dir(config)
+    flat = is_flat_mode(config)
+    worktree_path = get_worktree_dir(
+        base_dir, group, repo_name, label=UPSTREAM_LABEL, flat=flat
+    )
+    if worktree_path.exists():
+        return False, f"{worktree_path} already exists"
+
+    local_branch = f"{UPSTREAM_LABEL}-{branch_to_label(upstream_branch)}"
+    ok, message = add_worktree(
+        repo_path,
+        worktree_path,
+        local_branch,
+        start_point=f"upstream/{upstream_branch}",
+        verbose=verbose,
+    )
+    if not ok:
+        return False, message
+    return True, f"{worktree_path} on {local_branch} (upstream/{upstream_branch})"
+
+
+@app.command("add")
+def worktree_add(
+    ctx: typer.Context,
+    repo_name: str = typer.Argument(..., help="Repository to add a worktree to"),
+    branch: str = typer.Argument(
+        None,
+        help="Branch to check out. Omit with --upstream to use the upstream default branch.",
+    ),
+    upstream: bool = typer.Option(
+        False,
+        "--upstream",
+        "-u",
+        help="Create a worktree tracking the upstream remote's default branch",
+    ),
+    label: str = typer.Option(
+        None,
+        "--label",
+        "-l",
+        help="Directory suffix for the worktree (defaults to the branch name)",
+    ),
+):
+    """Add a worktree so another branch is checked out alongside the main clone."""
+    verbose = ctx.obj.get("verbose", False) if ctx.obj else False
+    config = get_config()
+
+    if not upstream and not branch:
+        typer.echo("❌ Provide a branch, or pass --upstream.", err=True)
+        raise typer.Exit(1)
+
+    repo, base_dir = _resolve_repo(repo_name, config, verbose)
+
+    if upstream and not branch:
+        ok, message = create_upstream_worktree(
+            repo["path"], repo["name"], repo["group"], config, verbose
+        )
+        if not ok:
+            typer.echo(f"❌ {repo_name}: {message}", err=True)
+            raise typer.Exit(1)
+        typer.echo(f"✅ {repo_name}: worktree added at {message}")
+        return
+
+    # Explicit branch: create it from upstream when --upstream is combined with
+    # a branch name, otherwise check out the existing local/remote branch.
+    start_point = None
+    if upstream:
+        if not has_remote(repo["path"], "upstream"):
+            typer.echo(f"❌ {repo_name}: no 'upstream' remote configured", err=True)
+            raise typer.Exit(1)
+        start_point = f"upstream/{branch}"
+
+    worktree_path = get_worktree_dir(
+        base_dir,
+        repo["group"],
+        repo["name"],
+        label=label or branch_to_label(branch),
+        flat=is_flat_mode(config),
+    )
+    if worktree_path.exists():
+        typer.echo(f"❌ {repo_name}: {worktree_path} already exists", err=True)
+        raise typer.Exit(1)
+
+    ok, message = add_worktree(
+        repo["path"], worktree_path, branch, start_point=start_point, verbose=verbose
+    )
+    if not ok:
+        typer.echo(f"❌ {repo_name}: {message}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"✅ {repo_name}: worktree added at {worktree_path} on {branch}")
+
+
+@app.command("list")
+def worktree_list(
+    ctx: typer.Context,
+    repo_name: str = typer.Argument(..., help="Repository to list worktrees for"),
+):
+    """List the worktrees attached to a repository."""
+    verbose = ctx.obj.get("verbose", False) if ctx.obj else False
+    config = get_config()
+    repo, _ = _resolve_repo(repo_name, config, verbose)
+
+    worktrees = list_worktrees(repo["path"], verbose=verbose)
+    if not worktrees:
+        typer.echo(f"No worktrees found for {repo_name}")
+        return
+
+    typer.echo(f"Worktrees for {repo_name}:")
+    for entry in worktrees:
+        marker = "  " if entry["path"] != repo["path"] else "* "
+        branch = entry["branch"] or f"detached at {(entry['head'] or '')[:8]}"
+        typer.echo(f"{marker}{entry['path']}  [{branch}]")
+
+
+@app.command("remove")
+def worktree_remove(
+    ctx: typer.Context,
+    repo_name: str = typer.Argument(..., help="Repository the worktree belongs to"),
+    label: str = typer.Argument(
+        UPSTREAM_LABEL,
+        help="Directory suffix of the worktree to remove (default: upstream)",
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Remove even with uncommitted changes"
+    ),
+):
+    """Remove a worktree and its registration in the primary clone."""
+    verbose = ctx.obj.get("verbose", False) if ctx.obj else False
+    config = get_config()
+    repo, base_dir = _resolve_repo(repo_name, config, verbose)
+
+    worktree_path = get_worktree_dir(
+        base_dir, repo["group"], repo["name"], label=label, flat=is_flat_mode(config)
+    )
+    if not worktree_path.exists():
+        typer.echo(f"❌ {repo_name}: no worktree at {worktree_path}", err=True)
+        raise typer.Exit(1)
+
+    ok, message = remove_worktree(
+        repo["path"], worktree_path, force=force, verbose=verbose
+    )
+    if not ok:
+        typer.echo(f"❌ {repo_name}: {message}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"✅ {repo_name}: removed worktree {worktree_path}")
diff --git a/src/dbx_python_cli/config.toml b/src/dbx_python_cli/config.toml
index a0cb520..d5ac5d1 100644
--- a/src/dbx_python_cli/config.toml
+++ b/src/dbx_python_cli/config.toml
@@ -172,6 +172,10 @@ repos = [
 no_fork = ["django"]
 # Automatically sync with upstream immediately after cloning
 sync_after_clone = ["django-mongodb-backend"]
+# Create a sibling `<repo>-upstream` git worktree after cloning, so the fork
+# and its upstream can both be developed from a single clone (one object store,
+# two working trees). The worktree checks out `upstream-<default branch>`.
+upstream_worktree = ["django"]
 
 # Upstream remote URL for fork repos (added as `upstream` remote on clone)
 # Use this when the group contains forks that need to track the original repo.
diff --git a/src/dbx_python_cli/utils/repo.py b/src/dbx_python_cli/utils/repo.py
index d2116fd..48b172a 100644
--- a/src/dbx_python_cli/utils/repo.py
+++ b/src/dbx_python_cli/utils/repo.py
@@ -2,10 +2,10 @@
 
 import os
 import subprocess
-import tomllib
-from pathlib import Path
 from collections import defaultdict
+from pathlib import Path
 
+import tomllib
 import typer
 
 
@@ -60,6 +60,15 @@ def get_repo_dir(base_dir, group, repo_name, flat=False):
     return base_dir / repo_name if flat else base_dir / group / repo_name
 
 
+def is_worktree(path):
+    """Return True if *path* is a linked git worktree rather than a primary clone.
+
+    Git marks a linked worktree by writing ``.git`` as a *file* holding a
+    ``gitdir:`` pointer; a primary clone has ``.git`` as a directory.
+    """
+    return (Path(path) / ".git").is_file()
+
+
 def get_projects_dir(base_dir, flat=False):
     """Return the directory where Django projects live.
 
@@ -390,6 +399,34 @@ def get_upstream_branch(config, group_name, repo_name, current_branch=None):
     return value
 
 
+def should_create_upstream_worktree(config, group_name, repo_name):
+    """Check whether a repo should get an upstream worktree created on clone.
+
+    When enabled, ``dbx clone`` adds a sibling worktree checked out on the
+    upstream remote's default branch, so a fork can be developed against its
+    upstream from a single clone (one object store, two working trees).
+
+    Configure in ``[repo.groups.<group>]`` as a list of repo names:
+
+    .. code-block:: toml
+
+        [repo.groups.django]
+        upstream_worktree = ["django"]
+
+    Args:
+        config: Configuration dictionary
+        group_name: Name of the group (e.g., 'django')
+        repo_name: Name of the repository (e.g., 'django')
+
+    Returns:
+        bool: True if an upstream worktree should be created after cloning
+    """
+    groups = get_repo_groups(config)
+    if group_name not in groups:
+        return False
+    return repo_name in groups[group_name].get("upstream_worktree", [])
+
+
 def should_sync_after_clone(config, group_name, repo_name):
     """Check whether a repository should be synced with upstream right after cloning.
 
@@ -732,10 +769,24 @@ def find_all_repos(base_dir, config=None):
                 continue
             if (repo_dir / ".git").exists():
                 group = repo_to_group.get(repo_dir.name, "")
-                repos.append({"name": repo_dir.name, "path": repo_dir, "group": group})
+                repos.append(
+                    {
+                        "name": repo_dir.name,
+                        "path": repo_dir,
+                        "group": group,
+                        "worktree": is_worktree(repo_dir),
+                    }
+                )
             elif (repo_dir / "manage.py").exists():
                 # Django projects: identified by manage.py, live directly in base_dir
-                repos.append({"name": repo_dir.name, "path": repo_dir, "group": ""})
+                repos.append(
+                    {
+                        "name": repo_dir.name,
+                        "path": repo_dir,
+                        "group": "",
+                        "worktree": False,
+                    }
+                )
         return repos
 
     # Grouped layout: base_dir/<group>/<repo>
@@ -750,6 +801,7 @@ def find_all_repos(base_dir, config=None):
                                 "name": repo_dir.name,
                                 "path": repo_dir,
                                 "group": group_dir.name,
+                                "worktree": is_worktree(repo_dir),
                             }
                         )
                     # Also check if it's a project (has pyproject.toml but no .git)
@@ -763,6 +815,7 @@ def find_all_repos(base_dir, config=None):
                                 "name": repo_dir.name,
                                 "path": repo_dir,
                                 "group": "projects",
+                                "worktree": False,
                             }
                         )
     return repos
diff --git a/src/dbx_python_cli/utils/worktree.py b/src/dbx_python_cli/utils/worktree.py
new file mode 100644
index 0000000..ca37afe
--- /dev/null
+++ b/src/dbx_python_cli/utils/worktree.py
@@ -0,0 +1,268 @@
+"""Git worktree helpers.
+
+A worktree lets a single clone have more than one branch checked out at once,
+each in its own directory but sharing one object store.  This is what makes it
+possible to develop against both a fork and its upstream from one ``dbx clone``:
+the primary checkout stays on the fork branch (``origin``) while a sibling
+worktree tracks the upstream default branch, with no second fetch and no
+duplicated history.
+
+Layout mirrors the repo layout from :mod:`dbx_python_cli.utils.repo`, with the
+worktree as a sibling of its primary checkout:
+
+- Grouped: ``base_dir/<group>/<repo>-<label>``
+- Flat:    ``base_dir/<repo>-<label>``
+"""
+
+import subprocess
+from pathlib import Path
+
+import typer
+
+from dbx_python_cli.utils.repo import get_repo_dir, is_worktree
+
+#: Directory-name suffix used when a worktree is created for the upstream remote.
+UPSTREAM_LABEL = "upstream"
+
+#: Re-exported so callers only need one import for worktree handling.
+__all__ = [
+    "UPSTREAM_LABEL",
+    "add_worktree",
+    "branch_to_label",
+    "get_remote_head_branch",
+    "get_worktree_dir",
+    "has_remote",
+    "is_worktree",
+    "list_worktrees",
+    "local_branch_exists",
+    "prune_worktrees",
+    "remove_worktree",
+]
+
+
+def get_worktree_dir(base_dir, group, repo_name, label=UPSTREAM_LABEL, flat=False):
+    """Return the directory a worktree for *repo_name* should live in.
+
+    Args:
+        base_dir: Base directory for clones
+        group: Group name (ignored in flat mode)
+        repo_name: Name of the primary repo (e.g. ``django``)
+        label: Suffix distinguishing the worktree (e.g. ``upstream``)
+        flat: True when repos live directly under base_dir
+
+    Returns:
+        Path: e.g. ``base_dir/django/django-upstream``
+    """
+    return get_repo_dir(base_dir, group, f"{repo_name}-{label}", flat=flat)
+
+
+def branch_to_label(branch):
+    """Turn a branch name into a filesystem-safe directory suffix.
+
+    Branch names may contain ``/`` (``stable/6.1.x``), which would otherwise
+    create nested directories.
+
+    Args:
+        branch: Branch name
+
+    Returns:
+        str: Suffix safe to append to a directory name
+    """
+    return branch.replace("/", "-")
+
+
+def list_worktrees(repo_path, verbose=False):
+    """List the worktrees attached to the clone at *repo_path*.
+
+    The primary checkout is included; it is the entry whose path equals
+    *repo_path* and for which :func:`is_worktree` is False.
+
+    Args:
+        repo_path: Path to any checkout of the repository
+        verbose: Print the underlying git invocation
+
+    Returns:
+        list: Dicts with ``path`` (Path), ``branch`` (str or None, detached
+        HEAD yields None), ``head`` (str or None) and ``bare`` (bool) keys.
+        Empty if *repo_path* is not a git repository.
+    """
+    if verbose:
+        typer.echo(f"  [verbose] git -C {repo_path} worktree list --porcelain")
+
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "worktree", "list", "--porcelain"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return []
+
+    worktrees = []
+    current = None
+    for line in result.stdout.splitlines():
+        if line.startswith("worktree "):
+            if current is not None:
+                worktrees.append(current)
+            current = {
+                "path": Path(line[len("worktree ") :]),
+                "branch": None,
+                "head": None,
+                "bare": False,
+            }
+        elif current is None:
+            continue
+        elif line.startswith("HEAD "):
+            current["head"] = line[len("HEAD ") :]
+        elif line.startswith("branch "):
+            # Porcelain reports the full ref: refs/heads/<branch>
+            ref = line[len("branch ") :]
+            current["branch"] = (
+                ref[len("refs/heads/") :] if ref.startswith("refs/heads/") else ref
+            )
+        elif line == "bare":
+            current["bare"] = True
+
+    if current is not None:
+        worktrees.append(current)
+    return worktrees
+
+
+def get_remote_head_branch(repo_path, remote="upstream", verbose=False):
+    """Return the default branch of *remote*, or None if it cannot be determined.
+
+    Reads the cached ``refs/remotes/<remote>/HEAD`` symbolic ref first (set by
+    ``git clone`` / ``git remote add`` + ``fetch``) and falls back to asking the
+    remote directly, which also repairs the local ref for later calls.
+    """
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "symbolic-ref", f"refs/remotes/{remote}/HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        # refs/remotes/upstream/main -> main
+        return result.stdout.strip().split(f"refs/remotes/{remote}/", 1)[-1]
+
+    if verbose:
+        typer.echo(f"  [verbose] {remote}/HEAD not set, querying remote")
+
+    # set-head asks the remote and writes the ref; then re-read it.
+    subprocess.run(
+        ["git", "-C", str(repo_path), "remote", "set-head", remote, "--auto"],
+        capture_output=True,
+        text=True,
+    )
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "symbolic-ref", f"refs/remotes/{remote}/HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().split(f"refs/remotes/{remote}/", 1)[-1]
+    return None
+
+
+def has_remote(repo_path, remote):
+    """Return True if *repo_path* has a remote named *remote*."""
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "remote"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return False
+    return remote in result.stdout.split()
+
+
+def local_branch_exists(repo_path, branch):
+    """Return True if *branch* exists as a local branch in *repo_path*."""
+    result = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repo_path),
+            "show-ref",
+            "--verify",
+            "--quiet",
+            f"refs/heads/{branch}",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def add_worktree(repo_path, worktree_path, branch, start_point=None, verbose=False):
+    """Create a worktree for *branch* at *worktree_path*.
+
+    When *start_point* is given and *branch* does not exist locally, the branch
+    is created from *start_point* (e.g. ``upstream/main``) with ``-b``.  When the
+    branch already exists it is simply checked out into the new worktree; git
+    refuses if it is already checked out elsewhere, which is reported as a
+    failure rather than worked around.
+
+    Args:
+        repo_path: Path to an existing checkout of the repository
+        worktree_path: Directory to create
+        branch: Local branch name to check out in the worktree
+        start_point: Ref to create *branch* from when it does not exist yet
+        verbose: Stream git output instead of capturing it
+
+    Returns:
+        tuple: ``(ok, message)`` where *ok* is a bool and *message* is git's
+        error output when *ok* is False, otherwise an empty string.
+    """
+    cmd = ["git", "-C", str(repo_path), "worktree", "add"]
+    if start_point and not local_branch_exists(repo_path, branch):
+        cmd += ["-b", branch, str(worktree_path), start_point]
+    else:
+        cmd += [str(worktree_path), branch]
+
+    if verbose:
+        typer.echo(f"  [verbose] {' '.join(cmd)}")
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        return False, (result.stderr or result.stdout).strip()
+    return True, ""
+
+
+def remove_worktree(repo_path, worktree_path, force=False, verbose=False):
+    """Remove the worktree at *worktree_path*.
+
+    Uses ``git worktree remove`` so the registration in ``.git/worktrees`` is
+    cleaned up too; deleting the directory outright would leave a stale entry
+    that blocks re-creating the worktree later.
+
+    Args:
+        repo_path: Path to another checkout of the same repository
+        worktree_path: Worktree directory to remove
+        force: Remove even when the worktree has uncommitted changes
+        verbose: Stream git output instead of capturing it
+
+    Returns:
+        tuple: ``(ok, message)`` as in :func:`add_worktree`.
+    """
+    cmd = ["git", "-C", str(repo_path), "worktree", "remove"]
+    if force:
+        cmd.append("--force")
+    cmd.append(str(worktree_path))
+
+    if verbose:
+        typer.echo(f"  [verbose] {' '.join(cmd)}")
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        return False, (result.stderr or result.stdout).strip()
+    return True, ""
+
+
+def prune_worktrees(repo_path, verbose=False):
+    """Drop registrations for worktree directories that no longer exist."""
+    if verbose:
+        typer.echo(f"  [verbose] git -C {repo_path} worktree prune")
+    subprocess.run(
+        ["git", "-C", str(repo_path), "worktree", "prune"],
+        capture_output=True,
+        text=True,
+    )
diff --git a/tests/test_worktree_command.py b/tests/test_worktree_command.py
new file mode 100644
index 0000000..e0f40d3
--- /dev/null
+++ b/tests/test_worktree_command.py
@@ -0,0 +1,302 @@
+"""Tests for the worktree command module and worktree utilities."""
+
+import subprocess
+from unittest.mock import patch
+
+import pytest
+from typer.testing import CliRunner
+
+from dbx_python_cli.cli import app
+from dbx_python_cli.utils.repo import is_worktree, should_create_upstream_worktree
+from dbx_python_cli.utils.worktree import (
+    add_worktree,
+    branch_to_label,
+    get_remote_head_branch,
+    get_worktree_dir,
+    has_remote,
+    list_worktrees,
+    local_branch_exists,
+    remove_worktree,
+)
+
+runner = CliRunner()
+
+
+def _git(*args, cwd):
+    """Run a git command, raising on failure."""
+    return subprocess.run(
+        ["git", *args], cwd=str(cwd), check=True, capture_output=True, text=True
+    )
+
+
+@pytest.fixture
+def fork_and_upstream(tmp_path):
+    """Build a real fork clone with an ``upstream`` remote in ``base_dir/django``.
+
+    Worktree behaviour depends on git's own bookkeeping (``.git`` as a file,
+    ``.git/worktrees`` registrations, refusing a branch checked out twice), so
+    these tests drive real repositories rather than mocking subprocess.
+    """
+    base_dir = tmp_path / "repos"
+    group_dir = base_dir / "django"
+    group_dir.mkdir(parents=True)
+
+    origin = tmp_path / "origin.git"
+    _git("init", "-q", "--bare", str(origin), cwd=tmp_path)
+
+    seed = tmp_path / "seed"
+    _git("clone", "-q", str(origin), str(seed), cwd=tmp_path)
+    _git("commit", "-q", "--allow-empty", "-m", "init", cwd=seed)
+    _git("push", "-q", "origin", "HEAD:main", cwd=seed)
+
+    fork = group_dir / "django"
+    _git("clone", "-q", str(origin), str(fork), cwd=tmp_path)
+    _git("remote", "add", "upstream", str(origin), cwd=fork)
+    _git("fetch", "-q", "upstream", cwd=fork)
+
+    return {"base_dir": base_dir, "fork": fork, "group_dir": group_dir}
+
+
+@pytest.fixture
+def config(fork_and_upstream):
+    """Config pointing at the fixture's base_dir with the django group."""
+    return {
+        "repo": {
+            "base_dir": str(fork_and_upstream["base_dir"]),
+            "groups": {
+                "django": {
+                    "repos": ["git@github.com:mongodb-forks/django.git"],
+                    "upstream_worktree": ["django"],
+                }
+            },
+        }
+    }
+
+
+# --- utils/worktree.py -------------------------------------------------------
+
+
+def test_get_worktree_dir_grouped(tmp_path):
+    assert get_worktree_dir(tmp_path, "django", "django") == (
+        tmp_path / "django" / "django-upstream"
+    )
+
+
+def test_get_worktree_dir_flat(tmp_path):
+    assert get_worktree_dir(tmp_path, "django", "django", flat=True) == (
+        tmp_path / "django-upstream"
+    )
+
+
+def test_get_worktree_dir_custom_label(tmp_path):
+    assert get_worktree_dir(tmp_path, "django", "django", label="6-1") == (
+        tmp_path / "django" / "django-6-1"
+    )
+
+
+def test_branch_to_label_flattens_slashes():
+    assert branch_to_label("stable/6.1.x") == "stable-6.1.x"
+    assert branch_to_label("main") == "main"
+
+
+def test_has_remote(fork_and_upstream):
+    fork = fork_and_upstream["fork"]
+    assert has_remote(fork, "upstream") is True
+    assert has_remote(fork, "nope") is False
+
+
+def test_get_remote_head_branch(fork_and_upstream):
+    assert get_remote_head_branch(fork_and_upstream["fork"], "upstream") == "main"
+
+
+def test_get_remote_head_branch_unknown_remote(fork_and_upstream):
+    assert get_remote_head_branch(fork_and_upstream["fork"], "missing") is None
+
+
+def test_local_branch_exists(fork_and_upstream):
+    fork = fork_and_upstream["fork"]
+    assert local_branch_exists(fork, "main") is True
+    assert local_branch_exists(fork, "does-not-exist") is False
+
+
+def test_add_and_remove_worktree(fork_and_upstream):
+    fork = fork_and_upstream["fork"]
+    path = fork_and_upstream["group_dir"] / "django-upstream"
+
+    ok, message = add_worktree(fork, path, "upstream-main", start_point="upstream/main")
+    assert ok, message
+    assert path.exists()
+    # A linked worktree has .git as a file, not a directory.
+    assert is_worktree(path) is True
+    assert is_worktree(fork) is False
+
+    branches = {w["path"].name: w["branch"] for w in list_worktrees(fork)}
+    assert branches == {"django": "main", "django-upstream": "upstream-main"}
+
+    ok, message = remove_worktree(fork, path)
+    assert ok, message
+    assert not path.exists()
+    assert [w["path"].name for w in list_worktrees(fork)] == ["django"]
+
+
+def test_add_worktree_rejects_branch_checked_out_elsewhere(fork_and_upstream):
+    """git refuses to check out `main` twice; the failure is surfaced, not hidden."""
+    fork = fork_and_upstream["fork"]
+    path = fork_and_upstream["group_dir"] / "django-main"
+
+    ok, message = add_worktree(fork, path, "main")
+    assert ok is False
+    assert "main" in message
+    assert not path.exists()
+
+
+def test_list_worktrees_on_non_repo(tmp_path):
+    assert list_worktrees(tmp_path) == []
+
+
+# --- config ------------------------------------------------------------------
+
+
+def test_should_create_upstream_worktree(config):
+    assert should_create_upstream_worktree(config, "django", "django") is True
+    assert should_create_upstream_worktree(config, "django", "other") is False
+    assert should_create_upstream_worktree(config, "missing-group", "django") is False
+
+
+# --- dbx worktree ------------------------------------------------------------
+
+
+def test_worktree_add_upstream(config, fork_and_upstream):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        result = runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+
+    assert result.exit_code == 0, result.output
+    assert "worktree added" in result.output
+    assert (fork_and_upstream["group_dir"] / "django-upstream").exists()
+
+
+def test_worktree_add_upstream_twice_fails(config, fork_and_upstream):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+        result = runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+
+    assert result.exit_code == 1
+    assert "already exists" in result.output
+
+
+def test_worktree_add_requires_branch_or_upstream(config):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        result = runner.invoke(app, ["worktree", "add", "django"])
+
+    assert result.exit_code == 1
+    assert "--upstream" in result.output
+
+
+def test_worktree_add_unknown_repo(config):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        result = runner.invoke(app, ["worktree", "add", "nope", "--upstream"])
+
+    assert result.exit_code == 1
+    assert "not found" in result.output
+
+
+def test_worktree_add_without_upstream_remote(config, fork_and_upstream):
+    _git("remote", "remove", "upstream", cwd=fork_and_upstream["fork"])
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        result = runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+
+    assert result.exit_code == 1
+    assert "upstream" in result.output
+
+
+def test_worktree_list(config, fork_and_upstream):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+        result = runner.invoke(app, ["worktree", "list", "django"])
+
+    assert result.exit_code == 0, result.output
+    assert "django-upstream" in result.output
+    assert "upstream-main" in result.output
+
+
+def test_worktree_remove(config, fork_and_upstream):
+    path = fork_and_upstream["group_dir"] / "django-upstream"
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+        assert path.exists()
+        result = runner.invoke(app, ["worktree", "remove", "django"])
+
+    assert result.exit_code == 0, result.output
+    assert not path.exists()
+
+
+def test_worktree_remove_missing(config):
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        result = runner.invoke(app, ["worktree", "remove", "django"])
+
+    assert result.exit_code == 1
+    assert "no worktree" in result.output
+
+
+def test_worktree_commands_reject_a_worktree_as_target(config, fork_and_upstream):
+    """`django-upstream` is a worktree, not a clone, so it is not a valid target."""
+    with patch("dbx_python_cli.commands.worktree.get_config", return_value=config):
+        runner.invoke(app, ["worktree", "add", "django", "--upstream"])
+        result = runner.invoke(app, ["worktree", "list", "django-upstream"])
+
+    assert result.exit_code == 1
+    assert "is itself a worktree" in result.output
+
+
+# --- worktrees are excluded from mutating bulk commands ----------------------
+
+
+def test_sync_skips_a_worktree(config, fork_and_upstream):
+    """Rebasing a worktree onto upstream and force-pushing would corrupt the fork."""
+    from dbx_python_cli.commands.sync import _sync_repository
+
+    path = fork_and_upstream["group_dir"] / "django-upstream"
+    ok, message = add_worktree(
+        fork_and_upstream["fork"], path, "upstream-main", start_point="upstream/main"
+    )
+    assert ok, message
+
+    with patch("dbx_python_cli.commands.sync.subprocess.run") as mock_run:
+        status = _sync_repository(path, "django-upstream")
+
+    assert status == "skipped"
+    # The guard must short-circuit before any git command runs.
+    mock_run.assert_not_called()
+
+
+def test_sync_does_not_skip_a_primary_clone(fork_and_upstream):
+    from dbx_python_cli.commands.sync import _sync_repository
+
+    with patch("dbx_python_cli.commands.sync.subprocess.run") as mock_run:
+        mock_run.return_value.returncode = 0
+        mock_run.return_value.stdout = ""
+        mock_run.return_value.stderr = ""
+        _sync_repository(fork_and_upstream["fork"], "django", dry_run=True)
+
+    assert mock_run.called
+
+
+def test_switch_group_skips_worktrees(config, fork_and_upstream):
+    """A bulk switch must not touch worktrees; git allows one checkout per branch."""
+    add_worktree(
+        fork_and_upstream["fork"],
+        fork_and_upstream["group_dir"] / "django-upstream",
+        "upstream-main",
+        start_point="upstream/main",
+    )
+
+    with (
+        patch("dbx_python_cli.commands.switch.get_config", return_value=config),
+        patch("dbx_python_cli.commands.switch._run_git_switch") as mock_switch,
+    ):
+        result = runner.invoke(app, ["switch", "-g", "django", "main"])
+
+    assert result.exit_code == 0, result.output
+    switched = [call.args[1] for call in mock_switch.call_args_list]
+    assert switched == ["django"]
+    assert "django-upstream" not in switched

From 4740112580e710a49b58f5903080e3f940ca08ec Mon Sep 17 00:00:00 2001
From: Jeffrey 'Alex' Clark <alex.clark@mongodb.com>
Date: Tue, 25 Aug 2026 15:18:39 -0400
Subject: [PATCH 2/3] test(worktree): give the git fixture an identity so CI
 can commit

CI runners have no global git user.name/user.email, so the fixture's
seed commit failed with exit 128 ("Author identity unknown") and errored
all 19 tests that build a real repository. Supply the identity through
GIT_AUTHOR_*/GIT_COMMITTER_* in the environment, which keeps it scoped
to these tests instead of writing to the developer's global config, and
force commit.gpgsign=false so a developer's global signing config cannot
prompt or fail here either.

Verified by running the suite with HOME, GIT_CONFIG_GLOBAL and
GIT_CONFIG_SYSTEM stripped, which reproduces the CI failure without the
fix and passes with it.
---
 tests/test_worktree_command.py | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/tests/test_worktree_command.py b/tests/test_worktree_command.py
index e0f40d3..7837e73 100644
--- a/tests/test_worktree_command.py
+++ b/tests/test_worktree_command.py
@@ -1,5 +1,6 @@
 """Tests for the worktree command module and worktree utilities."""
 
+import os
 import subprocess
 from unittest.mock import patch
 
@@ -22,10 +23,31 @@
 runner = CliRunner()
 
 
+# CI runners have no global git identity, so commits fail with exit 128 unless
+# one is supplied. Setting it in the environment keeps it scoped to these tests
+# rather than writing to the developer's global config.
+_GIT_ENV = {
+    **os.environ,
+    "GIT_AUTHOR_NAME": "dbx tests",
+    "GIT_AUTHOR_EMAIL": "dbx-tests@example.com",
+    "GIT_COMMITTER_NAME": "dbx tests",
+    "GIT_COMMITTER_EMAIL": "dbx-tests@example.com",
+    # A developer's global commit.gpgsign would otherwise prompt or fail here.
+    "GIT_CONFIG_COUNT": "1",
+    "GIT_CONFIG_KEY_0": "commit.gpgsign",
+    "GIT_CONFIG_VALUE_0": "false",
+}
+
+
 def _git(*args, cwd):
     """Run a git command, raising on failure."""
     return subprocess.run(
-        ["git", *args], cwd=str(cwd), check=True, capture_output=True, text=True
+        ["git", *args],
+        cwd=str(cwd),
+        check=True,
+        capture_output=True,
+        text=True,
+        env=_GIT_ENV,
     )
 
 

From e633d9908c1983fa0c6787ca0fcb639451c6d438 Mon Sep 17 00:00:00 2001
From: Jeffrey 'Alex' Clark <alex.clark@mongodb.com>
Date: Tue, 25 Aug 2026 15:22:36 -0400
Subject: [PATCH 3/3] test(worktree): pin the fixture's initial branch to main

The CI runners set init.defaultBranch=master. The fixture created the
bare origin with the machine default and then pushed HEAD:main, leaving
the bare repo's HEAD pointing at an unborn `master` while the only real
branch was `main`. upstream/HEAD was therefore unresolvable and
get_remote_head_branch returned None, failing 8 tests.

Pass --initial-branch=main so the branch name is pinned rather than
inherited. Reproduced locally with a global config setting
init.defaultBranch=master: 8 failures without this change (the same 8
CI reported), 24 passing with it.
---
 tests/test_worktree_command.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/test_worktree_command.py b/tests/test_worktree_command.py
index 7837e73..1f2181a 100644
--- a/tests/test_worktree_command.py
+++ b/tests/test_worktree_command.py
@@ -63,8 +63,12 @@ def fork_and_upstream(tmp_path):
     group_dir = base_dir / "django"
     group_dir.mkdir(parents=True)
 
+    # --initial-branch pins the name rather than inheriting the machine's
+    # init.defaultBranch, which is `master` on the CI runners. Without it the
+    # bare repo's HEAD points at an unborn `master` while the only real branch
+    # is `main`, so upstream/HEAD cannot be resolved.
     origin = tmp_path / "origin.git"
-    _git("init", "-q", "--bare", str(origin), cwd=tmp_path)
+    _git("init", "-q", "--bare", "--initial-branch=main", str(origin), cwd=tmp_path)
 
     seed = tmp_path / "seed"
     _git("clone", "-q", str(origin), str(seed), cwd=tmp_path)