multi-workspace 3.2.12__tar.gz → 3.2.13__tar.gz

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: multi-workspace
-Version: 3.2.12
+Version: 3.2.13
 Summary: Multi
 Project-URL: Repository, https://github.com/gabemontague/multi
 Project-URL: Issues, https://github.com/gabemontague/multi/issues

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.2.12'
-__version_tuple__ = version_tuple = (3, 2, 12)
+__version__ = version = '3.2.13'
+__version_tuple__ = version_tuple = (3, 2, 13)
 
 __commit_id__ = commit_id = None

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/branch.py

@@ -3,8 +3,13 @@ from pathlib import Path
 
 import click
 
+from multi.cli_helpers import common_command_wrapper
 from multi.errors import GitError
-from multi.git_helpers import describe_head
+from multi.git_helpers import (
+    describe_head,
+    expected_branch_description,
+    expected_branch_for_repo,
+)
 from multi.paths import Paths
 from multi.repos import load_repos
 
@@ -36,27 +41,17 @@ def report_branches(paths: Paths) -> bool:
             all_match = False
             logger.warning(f"{repo.name}: (missing — run `multi sync`)")
             continue
-        expected_branch = repo.fixed_branch or root_branch
+        expected_branch = expected_branch_for_repo(repo, root_branch)
         if branch == expected_branch:
             logger.info(f"{repo.name}: {branch}")
         else:
             all_match = False
-            if repo.fixed_branch:
-                expectation = f"fixed branch {expected_branch}"
-            else:
-                expectation = f"root branch {root_branch}"
+            expectation = expected_branch_description(repo, root_branch)
             logger.warning(f"{repo.name}: {branch} (expected {expectation})")
     return all_match
 
 
-@click.command(name="branch")
-def branch_cmd() -> None:
-    """Show the current branch of the root repo and every sub-repo.
-
-    Read-only: unlike `multi set-branch` and `multi git`, this works with
-    dirty working trees, mismatched branches, and detached HEADs.
-    Exits with an error status when repos are not on their expected branches.
-    """
+def _check_branch_alignment() -> None:
     paths = Paths(Path.cwd())
     if not report_branches(paths):
         raise GitError(
@@ -64,3 +59,24 @@ def branch_cmd() -> None:
             "Run `multi sync` to clone missing repos, or `multi set-branch` "
             "(with clean working trees) to fix branch mismatches."
         )
+
+
+@click.group(name="branch", invoke_without_command=True)
+@click.pass_context
+def branch_cmd(ctx: click.Context) -> None:
+    """Show branch state and expected-branch alignment.
+
+    Running `multi branch` is kept as the backwards-compatible spelling for
+    `multi branch check`.
+    """
+    if ctx.invoked_subcommand is None:
+        _check_branch_alignment()
+
+
+@click.command(name="check")
+def branch_check_cmd() -> None:
+    """Check that repos are on their expected branches."""
+    _check_branch_alignment()
+
+
+branch_cmd.add_command(common_command_wrapper(branch_check_cmd))

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/cli_helpers.py

@@ -67,7 +67,7 @@ def common_command_wrapper(command_to_wrap: click.Command) -> click.Command:
             if ctx.invoked_subcommand is not None:
                 return result
 
-        # After commands, check that all sub-repos are on the same branch as the root repo.
+        # After commands, check that all sub-repos are on their expected branch.
         # Some commands (like doctor) intentionally run even when no workspace is initialized.
         if command_to_wrap.name in COMMANDS_WITHOUT_WORKSPACE_BRANCH_CHECK:
             return result

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/git_helpers.py

@@ -1,6 +1,6 @@
 import logging
 from pathlib import Path
-from typing import Tuple
+from typing import Any, Tuple
 
 import git
 from git.exc import InvalidGitRepositoryError, NoSuchPathError
@@ -11,6 +11,31 @@ from multi.paths import Paths
 logger = logging.getLogger(__name__)
 
 
+def expected_branch_for_repo(repo: Any, workspace_branch: str | None) -> str | None:
+    """Return the branch a sub-repo should be on.
+
+    This is the fixed-branch invariant for Multi workspaces: a repo's
+    ``fixedBranch`` config wins, otherwise it follows the workspace branch.
+    Commands that need branch expectations should use this helper instead of
+    reading ``repo.fixed_branch`` directly.
+    """
+    fixed_branch = getattr(repo, "fixed_branch", None)
+    if fixed_branch is not None:
+        return fixed_branch
+    return workspace_branch
+
+
+def repo_uses_fixed_branch(repo: Any) -> bool:
+    return getattr(repo, "fixed_branch", None) is not None
+
+
+def expected_branch_description(repo: Any, workspace_branch: str | None) -> str:
+    expected_branch = expected_branch_for_repo(repo, workspace_branch)
+    if repo_uses_fixed_branch(repo):
+        return f"fixed branch {expected_branch}"
+    return f"root branch {workspace_branch}"
+
+
 def is_git_repo_root(repo_path: Path) -> bool:
     git_metadata_path = repo_path / ".git"
     if not git_metadata_path.exists():
@@ -70,13 +95,10 @@ def check_all_on_same_branch(paths: Paths, raise_error: bool = True) -> bool:
     root_branch = describe_head(paths.root_dir)
     repo_branches = [(repo, describe_head(repo.path)) for repo in load_repos(paths)]
     for repo, branch in repo_branches:
-        expected_branch = repo.fixed_branch or root_branch
+        expected_branch = expected_branch_for_repo(repo, root_branch)
         if branch != expected_branch:
             if raise_error:
-                if repo.fixed_branch:
-                    expectation = f"fixed branch {expected_branch}"
-                else:
-                    expectation = f"root branch {root_branch}"
+                expectation = expected_branch_description(repo, root_branch)
                 raise GitError(
                     f"Repository {repo.name} is not on the expected branch. "
                     f"Please fix. {repo.name}: {branch}, Expected: {expectation}"

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/git_run.py

@@ -35,7 +35,7 @@ def run_git_command(repo_path: Path, git_args: List[str]) -> None:
 
 def run_git_in_all_repos(paths: Paths, git_args: List[str]) -> None:
     """Run git command across all repositories."""
-    # First check if all repos are on the same branch
+    # First check if all repos are on their expected branch.
     check_all_on_same_branch(paths=paths, raise_error=True)
 
     # Run in root repo first
@@ -57,8 +57,8 @@ def git_cmd(git_args: tuple[str, ...]) -> None:
              multi git checkout -b feature/new-branch
              multi git branch --show-current
 
-    Requires all repositories to be on the same branch (working trees may be
-    dirty). To inspect branches when they mismatch, use `multi branch`.
+    Requires all repositories to be on their expected branch (working trees may
+    be dirty). To inspect branches when they mismatch, use `multi branch`.
     """
     paths = Paths(Path.cwd())
     if paths.settings.is_monorepo():

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/git_set_branch.py

@@ -9,6 +9,7 @@ from multi.git_helpers import (
     check_all_on_same_branch,
     check_all_repos_are_clean,
     check_branch_existence,
+    expected_branch_for_repo,
 )
 from multi.paths import Paths
 from multi.repos import load_repos
@@ -44,14 +45,15 @@ def set_branch_in_all_repos(root_dir: Path, branch_name: str) -> None:
     all_on_same_branch = check_all_on_same_branch(paths=paths, raise_error=False)
     if not all_on_same_branch:
         logger.warning(
-            "Some repos are not on the same branch as the root repo.  If the branch already exists for all repos, this command will fix the situation."
+            "Some repos are not on their expected branches. If the target branches already exist for all repos, this command will fix the situation."
         )
 
     create_and_switch_branch(
         paths.root_dir, branch_name, allow_create=all_on_same_branch
     )
     for repo in load_repos(paths=paths):
-        repo_branch_name = repo.fixed_branch or branch_name
+        repo_branch_name = expected_branch_for_repo(repo, branch_name)
+        assert repo_branch_name is not None
         create_and_switch_branch(
             repo.path, repo_branch_name, allow_create=all_on_same_branch
         )

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/ignore_files.py

@@ -55,11 +55,11 @@ class IgnoreFile:
 
 def _repo_entries(paths: Paths) -> List[str]:
     entries: List[str] = [
-        "# multi avoids git submodules; each entry has both forms: trailing slash matches directories, bare name matches symlinks/aliases.",
+        "# multi avoids git submodules; the leading slash anchors each entry to the workspace root so it never matches a nested directory of the same name (e.g. .agents/skills). The trailing-slash form matches the repo directory; the bare form matches a root symlink/alias.",
     ]
     for repo in load_repos(paths=paths):
-        entries.append(f"{repo.name}/")
-        entries.append(repo.name)
+        entries.append(f"/{repo.relative_path}/")
+        entries.append(f"/{repo.relative_path}")
     return entries
 
 
@@ -68,8 +68,8 @@ def _search_entries(paths: Paths) -> List[str]:
         "# Allow us to search inside these gitignored directories",
     ]
     for repo in load_repos(paths=paths):
-        entries.append(f"!{repo.name}/")
-        entries.append(f"!{repo.name}")
+        entries.append(f"!/{repo.relative_path}/")
+        entries.append(f"!/{repo.relative_path}")
     return entries
 
 
@@ -117,6 +117,10 @@ def remove_gitignore_entries_for_repos(paths: Paths, repo_names: List[str]) -> N
 
     entries = []
     for repo_name in repo_names:
+        # Remove both the anchored form and the legacy unanchored form so
+        # workspaces written by older multi versions migrate cleanly.
+        entries.append(f"/{repo_name}/")
+        entries.append(f"/{repo_name}")
         entries.append(f"{repo_name}/")
         entries.append(repo_name)
 
@@ -131,6 +135,10 @@ def remove_ignore_entries_for_repos(paths: Paths, repo_names: List[str]) -> None
 
     entries = []
     for repo_name in repo_names:
+        # Remove both the anchored form and the legacy unanchored form so
+        # workspaces written by older multi versions migrate cleanly.
+        entries.append(f"!/{repo_name}/")
+        entries.append(f"!/{repo_name}")
         entries.append(f"!{repo_name}/")
         entries.append(f"!{repo_name}")
 

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/remove.py

@@ -52,8 +52,13 @@ def remove_cmd(repo_name: str, delete: bool, force: bool):
     if matched_index is None:
         raise click.ClickException(f"No repo named '{repo_name}' found in multi.json.")
 
+    # Resolve the repo's on-disk location, honoring a custom "path" (nested
+    # layout); fall back to the repo name (flat layout).
+    matched_entry = repos_list[matched_index]
+    relative_path = (matched_entry.get("path") or repo_name).strip().strip("/")
+
     # Handle --delete
-    repo_path = paths.root_dir / repo_name
+    repo_path = paths.root_dir / relative_path
     if delete and repo_path.exists():
         if not force and not is_monorepo:
             # In monorepo mode there's no .git to check; in normal mode, check cleanliness
@@ -81,8 +86,8 @@ def remove_cmd(repo_name: str, delete: bool, force: bool):
 
     # Clean up ignore files (not used in monorepo mode)
     if not is_monorepo:
-        remove_gitignore_entries_for_repos(paths, [repo_name])
-        remove_ignore_entries_for_repos(paths, [repo_name])
+        remove_gitignore_entries_for_repos(paths, [relative_path])
+        remove_ignore_entries_for_repos(paths, [relative_path])
         if repo_path.exists():
             clear_subrepo_generated_file_block(repo_path)
 

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/repos.py

@@ -1,3 +1,4 @@
+from pathlib import Path, PurePosixPath
 from typing import Any, List
 
 from multi.errors import NoRepositoriesError
@@ -31,7 +32,28 @@ class Repository:
         else:
             raise ValueError("Repository must have either 'url' or 'name'")
         self.paths = paths
-        self.path = self.paths.root_dir / self.name
+
+        # Custom on-disk location, relative to the workspace root. Defaults to
+        # the repo name (a flat layout). Allows repos to live under nested
+        # directories, e.g. "path": "services/api".
+        relative_path = kwargs.pop("path", None)
+        if relative_path is None:
+            self.relative_path = self.name
+        else:
+            if not isinstance(relative_path, str):
+                raise ValueError(f"path for repository {self.name} must be a string.")
+            raw = relative_path.strip()
+            posix = PurePosixPath(raw)
+            # Reject absolute paths and parent-directory escapes before
+            # normalizing, so a leading '/' is an error rather than silently
+            # stripped.
+            if not raw or posix.is_absolute() or ".." in posix.parts:
+                raise ValueError(
+                    f"path for repository {self.name} must be a relative path "
+                    "inside the workspace (no leading '/' and no '..')."
+                )
+            self.relative_path = posix.as_posix()
+        self.path = self.paths.root_dir / Path(self.relative_path)
 
         # Set 'skip' attribute, defaulting to False if not provided in kwargs
         self.skip_vscode = kwargs.pop("skipVSCode", False)
@@ -44,6 +66,10 @@ class Repository:
 
         # Keep this repo on a fixed branch during branch synchronization.
         self.fixed_branch = kwargs.pop("fixedBranch", None)
+        if self.fixed_branch is not None and not isinstance(self.fixed_branch, str):
+            raise ValueError(
+                f"fixedBranch for repository {self.name} must be a string."
+            )
 
         install_sets = kwargs.pop("installSets", None)
         if install_sets is not None:

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/sync.py

@@ -11,7 +11,7 @@ from git.exc import GitCommandError
 from multi.bootstrap import ensure_root_git_repo, ensure_workspace_readme
 from multi.cli_helpers import common_command_wrapper
 from multi.doctor import find_nested_git_repos_in_monorepo
-from multi.git_helpers import get_current_branch
+from multi.git_helpers import expected_branch_for_repo, get_current_branch
 from multi.ignore_files import (
     update_gitignore_with_generated_files,
     update_gitignore_with_repos,
@@ -39,7 +39,7 @@ def _is_path_inside(child: Path, parent: Path) -> bool:
 def _try_symlink_repo(
     repo_config: Repository,
     paths: Paths,
-    current_branch: str | None,
+    expected_branch: str | None,
 ) -> bool:
     """Attempt to create a symlink for a repository.
 
@@ -75,18 +75,20 @@ def _try_symlink_repo(
 
     # Try to create the symlink
     try:
+        # Create any parent directories for nested custom paths.
+        os.makedirs(repo_config.path.parent, exist_ok=True)
         os.symlink(existing_path, repo_config.path)
         logger.info(f"🔗 Symlinked {repo_config.name} -> {existing_path}")
 
-        # Checkout the correct branch if needed
-        if current_branch:
+        # Checkout the expected branch if one is defined for this repo.
+        if expected_branch:
             try:
                 symlinked_repo = git.Repo(repo_config.path)
-                symlinked_repo.git.checkout(current_branch)
-                logger.debug(f"Checked out branch {current_branch} in symlinked repo")
+                symlinked_repo.git.checkout(expected_branch)
+                logger.debug(f"Checked out branch {expected_branch} in symlinked repo")
             except GitCommandError:
                 logger.warning(
-                    f"Branch {current_branch} not found in {repo_config.name}, staying on current branch."
+                    f"Branch {expected_branch} not found in {repo_config.name}, staying on current branch."
                 )
 
         return True
@@ -97,7 +99,7 @@ def _try_symlink_repo(
 
 def _clone_repo(
     repo_config: Repository,
-    current_branch: str | None,
+    expected_branch: str | None,
 ) -> None:
     """Clone a repository and checkout the appropriate branch."""
     logger.debug(f"Cloning {repo_config.name}...")
@@ -112,18 +114,21 @@ def _clone_repo(
         # workspace root gitignore already manages sub-repo paths.
         cloned_repo = git.Repo.clone_from(repo_config.url, temp_repo_path)
 
-        # Then checkout the same branch as parent repo if it exists
-        if current_branch:
+        # Then checkout the expected branch if one is defined for this repo.
+        if expected_branch:
             try:
-                cloned_repo.git.checkout(current_branch)
+                cloned_repo.git.checkout(expected_branch)
                 logger.info(
-                    f"✅ Cloned {repo_config.name} and checked out branch {current_branch}"
+                    f"✅ Cloned {repo_config.name} and checked out branch {expected_branch}"
                 )
             except GitCommandError:
                 logger.warning(
-                    f"Branch {current_branch} not found in {repo_config.name}, staying on default branch."
+                    f"Branch {expected_branch} not found in {repo_config.name}, staying on default branch."
                 )
 
+        # Create any parent directories for nested custom paths before moving
+        # the checked-out repo into place.
+        os.makedirs(repo_config.path.parent, exist_ok=True)
         shutil.move(str(temp_repo_path), str(repo_config.path))
 
 
@@ -145,6 +150,7 @@ def clone_repos(paths: Paths, ensure_on_same_branch: bool = True):
         logger.info(f"Current branch: {current_branch}")
 
     for repo_config in repos:
+        expected_branch = expected_branch_for_repo(repo_config, current_branch)
         if repo_config.path.exists():
             # Path already exists - register it and skip
             logger.debug(
@@ -154,11 +160,11 @@ def clone_repos(paths: Paths, ensure_on_same_branch: bool = True):
             continue
 
         # Try to symlink first
-        if _try_symlink_repo(repo_config, paths, current_branch):
+        if _try_symlink_repo(repo_config, paths, expected_branch):
             continue
 
         # Fall back to cloning
-        _clone_repo(repo_config, current_branch)
+        _clone_repo(repo_config, expected_branch)
 
         # Register the newly cloned repo
         register_repo(repo_config.url, repo_config.path)

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/sync_vscode_devcontainer.py

@@ -44,7 +44,7 @@ def sync_devcontainer(root_dir: Path, install_set: str | None = None) -> None:
                 if devcontainer_json:
                     devcontainer_json = prefix_repo_name_to_path_recursive(
                         devcontainer_json,
-                        repo.name,
+                        repo.relative_path,
                         resolve_relative_paths=True,
                     )
                     write_json_file(devcontainer_json_path, devcontainer_json)

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/sync_vscode_helpers.py

@@ -201,7 +201,9 @@ class VSCodeFileMerger(ABC):
             effective_repo_json, repo, source_file_display
         )
 
-        return deep_merge(merged_json, effective_repo_json, repo.name, skip_keys)
+        return deep_merge(
+            merged_json, effective_repo_json, repo.relative_path, skip_keys
+        )
 
     def _post_process_json(self, merged_json: Dict[str, Any]) -> Dict[str, Any]:
         """

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/sync_vscode_launch.py

@@ -61,7 +61,7 @@ class LaunchFileMerger(VSCodeFileMerger):
                 if isinstance(config, dict):
                     if "cwd" not in config:
                         config["cwd"] = prefix_repo_name_to_path(
-                            "${workspaceFolder}", repo.name
+                            "${workspaceFolder}", repo.relative_path
                         )
 
         # Check if repo has requiredCompounds config and mark matching compounds

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/sync_vscode_settings.py

@@ -13,9 +13,7 @@ from multi.utils import (
     write_jsonc_file,
 )
 
-LOCAL_GENERATED_SETTINGS_HEADER = (
-    "This file is generated by multi from settings.shared.json and/or settings.local.json. Do not edit directly."
-)
+LOCAL_GENERATED_SETTINGS_HEADER = "This file is generated by multi from settings.shared.json and/or settings.local.json. Do not edit directly."
 
 logger = logging.getLogger(__name__)
 
@@ -124,7 +122,7 @@ class SettingsFileMerger(VSCodeFileMerger):
 
         # Add Python paths for autocomplete
         repos = load_repos(self.paths)
-        python_paths_to_add = [repo.name for repo in repos if repo.is_python]
+        python_paths_to_add = [repo.relative_path for repo in repos if repo.is_python]
         if python_paths_to_add:
             logger.info("Adding Python paths for autocomplete")
             current_extra_paths = merged_json.setdefault(

{multi_workspace-3.2.12 → multi_workspace-3.2.13}/multi/worktree.py

@@ -13,6 +13,8 @@ from multi.git_helpers import (
     check_all_on_same_branch,
     check_all_repos_are_clean,
     check_branch_existence,
+    expected_branch_for_repo,
+    repo_uses_fixed_branch,
 )
 from multi.git_set_branch import create_and_switch_branch
 from multi.paths import Paths
@@ -177,8 +179,9 @@ def _checkout_subrepos(
 ) -> None:
     source_by_name = {repo.name: repo for repo in source_repos}
     for repo in destination_repos:
-        repo_branch_name = repo.fixed_branch or branch_name
-        if repo.fixed_branch:
+        repo_branch_name = expected_branch_for_repo(repo, branch_name)
+        assert repo_branch_name is not None
+        if repo_uses_fixed_branch(repo):
             create_and_switch_branch(
                 repo.path,
                 repo_branch_name,