multi-workspace 3.0.0__py3-none-any.whl

multi/__init__.py

@@ -0,0 +1 @@
+

multi/__main__.py

@@ -0,0 +1,4 @@
+from multi.cli import main
+
+if __name__ == "__main__":
+    main()

multi/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '3.0.0'
+__version_tuple__ = version_tuple = (3, 0, 0)
+
+__commit_id__ = commit_id = None

multi/cli.py

@@ -0,0 +1,45 @@
+import click
+
+from multi._version import __version__
+from multi.cli_helpers import common_command_wrapper
+from multi.git_run import git_cmd
+from multi.git_set_branch import set_branch_cmd
+from multi.init import init_cmd
+from multi.sync import sync_cmd
+
+
+def print_version(ctx, param, value):
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(f"multi (multi-sync) {__version__}")
+    ctx.exit()
+
+
+@click.group()
+@click.option(
+    "--version",
+    is_flag=True,
+    callback=print_version,
+    expose_value=False,
+    is_eager=True,
+    help="Show the version and exit.",
+)
+def main():
+    """VS Code Multi - Manage multiple Git repositories in VS Code.
+
+    This CLI tool enables seamless work across multiple Git repositories within VS Code.
+    Key features:
+    - Synchronize Git operations across root and sub-repositories
+    - Merge .vscode configurations (launch.json, tasks.json, settings.json)
+    - Manage consistent branch states across all repositories
+    """
+    pass
+
+
+main.add_command(common_command_wrapper(set_branch_cmd))
+main.add_command(common_command_wrapper(sync_cmd))
+main.add_command(common_command_wrapper(git_cmd))
+main.add_command(common_command_wrapper(init_cmd))
+
+if __name__ == "__main__":
+    main()

multi/cli_helpers.py

@@ -0,0 +1,79 @@
+import functools
+import logging
+import sys
+import traceback
+from pathlib import Path
+
+import click
+
+from multi.errors import GitError
+from multi.git_helpers import check_all_on_same_branch
+from multi.logging import configure_logging
+from multi.paths import Paths
+
+
+def common_command_wrapper(command_to_wrap: click.Command) -> click.Command:
+    """
+    Wraps an existing Click command to add common functionality:
+    - A --verbose option for detailed logging.
+    - Standardized error handling and logging.
+    This function modifies the command_to_wrap in-place.
+    """
+    original_callback = command_to_wrap.callback
+    if not original_callback:
+        # This should generally not happen if command_to_wrap is created via @click.command
+        raise ValueError(
+            f"Command '{command_to_wrap.name or 'Unnamed'}' has no callback to wrap."
+        )
+
+    @functools.wraps(original_callback)
+    def new_wrapped_callback(**kwargs):
+        # Pop the verbose flag. It's added by this wrapper to the command's params.
+        # Click will pass it in kwargs to this new_callback.
+        verbose_value = kwargs.pop("verbose", False)
+
+        # Configure logging based on verbosity
+        log_level = logging.DEBUG if verbose_value else logging.INFO
+        configure_logging(level=log_level)
+
+        exit_code = None
+        try:
+            # Call the original command's callback with its intended kwargs
+            return original_callback(**kwargs)
+        except Exception as e:
+            logger = logging.getLogger(__name__)  # Get logger after configuration
+            logger.error(str(e))  # This will use the emoji formatter
+            if verbose_value:
+                # For verbose mode, also print traceback directly to stderr
+                click.secho("\nDebug traceback:", fg="yellow", err=True)
+                click.secho(traceback.format_exc(), fg="yellow", err=True)
+            exit_code = 1
+
+        # After every command, check that all sub-repos are on the same branch as the root repo
+        try:
+            paths = Paths(Path.cwd())
+            check_all_on_same_branch(paths=paths, raise_error=True)
+        except GitError as e:
+            click.secho(e.args[0], fg="red", err=True)
+
+        if exit_code is not None:
+            sys.exit(exit_code)
+
+    # Replace the command's callback with our new wrapped version
+    command_to_wrap.callback = new_wrapped_callback
+
+    # Add the --verbose option to the command's parameters, if not already present
+    # This ensures the `verbose` kwarg is available in new_wrapped_callback
+    if not any(
+        isinstance(p, click.Option) and p.name == "verbose"
+        for p in command_to_wrap.params
+    ):
+        verbose_option = click.Option(
+            ["--verbose"],
+            is_flag=True,
+            help="Enable verbose output.",
+            # expose_value=True is default, making 'verbose' a kwarg to the callback
+        )
+        command_to_wrap.params.append(verbose_option)
+
+    return command_to_wrap  # Return the modified command

multi/errors.py

@@ -0,0 +1,22 @@
+class NoRepositoriesError(Exception):
+    pass
+
+
+class GitError(Exception):
+    pass
+
+
+class RepoNotCleanError(GitError):
+    pass
+
+
+class RulesError(Exception):
+    pass
+
+
+class RuleParseError(RulesError):
+    pass
+
+
+class RulesNotCombinableError(RulesError):
+    pass

multi/git_helpers.py

@@ -0,0 +1,109 @@
+import logging
+from pathlib import Path
+from typing import Tuple
+
+import git
+from git.exc import InvalidGitRepositoryError
+
+from multi.errors import GitError, RepoNotCleanError
+from multi.paths import Paths
+
+logger = logging.getLogger(__name__)
+
+
+def is_git_repo_root(repo_path: Path) -> bool:
+    # Will fail for submodules and worktrees, but these aren't used by us
+    return (repo_path / ".git").is_dir()
+
+
+def get_current_branch(repo_path: Path) -> str:
+    """Get the current branch name of a git repository."""
+    try:
+        repo = git.Repo(repo_path)
+        return repo.active_branch.name
+    except InvalidGitRepositoryError as e:
+        logger.error("Failed to determine current branch")
+        raise GitError("Failed to determine current branch") from e
+    except TypeError:
+        # Detached HEAD state - active_branch raises TypeError
+        return "HEAD"
+
+
+def check_all_on_same_branch(paths: Paths, raise_error: bool = True) -> bool:
+    """Validate that all repositories are on the same branch."""
+    from multi.repos import load_repos
+
+    root_branch = get_current_branch(paths.root_dir)
+    repo_branches = [
+        (repo, get_current_branch(repo.path)) for repo in load_repos(paths)
+    ]
+    for repo, branch in repo_branches:
+        if branch != root_branch:
+            if raise_error:
+                raise GitError(
+                    f"Repository {repo.name} is not on the same branch as the root repository.  Please fix.  {repo.name}: {branch}, Root: {root_branch}"
+                )
+            return False
+    return True
+
+
+def check_repo_is_clean(repo_path: Path, raise_error: bool = True) -> bool:
+    # Check if this is a git repository
+    if not is_git_repo_root(repo_path):
+        raise GitError(
+            f"{repo_path} is not a git repository or has not been initialized properly (no .git folder)"
+        )
+
+    # Make sure we have a clean working directory
+    try:
+        repo = git.Repo(repo_path)
+        # is_dirty checks for modified/staged files, untracked_files checks for new files
+        is_clean = not repo.is_dirty(untracked_files=True)
+    except InvalidGitRepositoryError as e:
+        logger.error("Failed to check working directory status")
+        raise GitError("Failed to check working directory status") from e
+
+    if not is_clean:
+        if raise_error:
+            raise RepoNotCleanError(
+                f"Working directory is not clean in {repo_path}. Please commit or stash changes first."
+            )
+        return False
+    return True
+
+
+def check_all_repos_are_clean(paths: Paths, raise_error: bool = True) -> bool:
+    """Check if all repositories are clean."""
+    from multi.repos import load_repos
+
+    # Check root repo
+    if not check_repo_is_clean(paths.root_dir, raise_error):
+        return False
+
+    # Check sub-repos
+    return all(
+        check_repo_is_clean(repo.path, raise_error) for repo in load_repos(paths)
+    )
+
+
+def check_branch_existence(repo_path: Path, branch_name: str) -> Tuple[bool, bool]:
+    try:
+        repo = git.Repo(repo_path)
+    except InvalidGitRepositoryError as e:
+        logger.error("Failed to check if branch exists")
+        raise GitError("Failed to check if branch exists") from e
+
+    # Check if branch exists locally
+    exists_locally = branch_name in [head.name for head in repo.heads]
+
+    # Check if branch exists remotely
+    try:
+        remote_refs = [ref.name for ref in repo.remotes.origin.refs]
+        exists_remotely = f"origin/{branch_name}" in remote_refs
+    except Exception:
+        logger.debug(
+            f"Could not check remote branches in {repo_path}, assuming branch doesn't exist remotely"
+        )
+        exists_remotely = False
+
+    return exists_locally, exists_remotely

multi/git_run.py

@@ -0,0 +1,59 @@
+import logging
+import subprocess
+from pathlib import Path
+from typing import List
+
+import click
+
+from multi.errors import GitError
+from multi.git_helpers import check_all_on_same_branch
+from multi.paths import Paths
+from multi.repos import load_repos
+
+logger = logging.getLogger(__name__)
+
+
+def run_git_command(repo_path: Path, git_args: List[str]) -> None:
+    """Run a git command in the specified repository."""
+    command_str = " ".join(git_args)
+    logger.info(f"Running 'git {command_str}' in {repo_path}")
+
+    cmd = ["git"] + git_args
+    try:
+        outputs = subprocess.run(
+            cmd,
+            cwd=repo_path,
+            check=check,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        logger.info(f"Output from {repo_path}:\n{outputs}")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to run git command in {repo_path}")
+        raise GitError(f"Failed to run git command in {repo_path}") from e
+
+
+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
+    check_all_on_same_branch(raise_error=True)
+
+    # Run in root repo first
+    run_git_command(paths.root_dir, git_args)
+
+    # Then run in all sub-repos
+    for repo in load_repos(paths.settings):
+        run_git_command(repo.path, git_args)
+
+
+@click.command(name="git")
+@click.argument("git_args", nargs=-1, required=True)
+def git_cmd(git_args: tuple[str, ...]) -> None:
+    """Run a git command across all repositories.
+
+    GIT_ARGS: The git command and arguments to run (e.g. 'pull' or 'checkout main')
+
+    Example: multi git pull
+             multi git checkout -b feature/new-branch
+    """
+    run_git_in_all_repos(list(git_args))

multi/git_set_branch.py

@@ -0,0 +1,66 @@
+import logging
+from pathlib import Path
+
+import click
+import git
+
+from multi.errors import GitError
+from multi.git_helpers import (
+    check_all_on_same_branch,
+    check_all_repos_are_clean,
+    check_branch_existence,
+)
+from multi.paths import Paths
+from multi.repos import load_repos
+
+logger = logging.getLogger(__name__)
+
+
+def create_and_switch_branch(
+    repo_path: Path, branch_name: str, allow_create: bool = True
+) -> None:
+    """Create a branch if it doesn't exist and switch to it."""
+    repo = git.Repo(repo_path)
+
+    # Check if branch exists locally or remotely
+    exists_locally, exists_remotely = check_branch_existence(repo_path, branch_name)
+
+    if exists_locally or exists_remotely:
+        logger.info(f"Branch '{branch_name}' already exists in {repo_path}")
+        repo.git.checkout(branch_name)
+    else:
+        if not allow_create:
+            raise GitError(
+                f"Branch '{branch_name}' does not exist in {repo_path}.  Normally we would create a new branch, but you started with different repos checked out to different branches, so there is no base branch to create from."
+            )
+        # Create a new branch from current HEAD
+        repo.create_head(branch_name).checkout()
+    logger.info(f"✅ Switched to branch '{branch_name}' in {repo_path}")
+
+
+def set_branch_in_all_repos(root_dir: Path, branch_name: str) -> None:
+    paths = Paths(root_dir)
+    check_all_repos_are_clean(paths=paths, raise_error=True)
+    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."
+        )
+
+    create_and_switch_branch(
+        paths.root_dir, branch_name, allow_create=all_on_same_branch
+    )
+    for repo in load_repos(paths=paths):
+        create_and_switch_branch(
+            repo.path, branch_name, allow_create=all_on_same_branch
+        )
+
+
+@click.command(name="set-branch")
+@click.argument("branch_name")
+def set_branch_cmd(branch_name: str) -> None:
+    """Create and switch to a branch in all repositories.
+
+    BRANCH_NAME: Name of the branch to create and switch to
+    """
+    set_branch_in_all_repos(root_dir=Path.cwd(), branch_name=branch_name)

multi/ignore_files.py

@@ -0,0 +1,104 @@
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+from multi.paths import Paths
+from multi.repos import load_repos
+
+logger = logging.getLogger(__name__)
+
+
+class IgnoreFile:
+    def __init__(self, path: Path):
+        self.path = path
+        self._existing_lines: Optional[List[str]] = None
+
+    @property
+    def existing_lines(self) -> List[str]:
+        """Lazily load and cache existing lines from the file."""
+        if self._existing_lines is None:
+            self._existing_lines = self._read_lines()
+        return self._existing_lines
+
+    def _read_lines(self) -> List[str]:
+        """Read and return lines from the ignore file."""
+        if not self.path.exists():
+            return []
+        with self.path.open("r") as f:
+            return [line.strip() for line in f.readlines()]
+
+    def add_lines_if_missing(self, lines: List[str], header: str) -> None:
+        """Add lines under the specified header section, creating it if needed.
+
+        If the header exists, new lines are added under the existing section.
+        If the header doesn't exist, it's added to the bottom of the file.
+        Only lines that don't already exist in the file are added.
+        """
+        if not lines:
+            return
+
+        # Find lines that don't already exist
+        lines_to_add = [line for line in lines if line not in self.existing_lines]
+        if not lines_to_add:
+            return
+
+        existing_lines = self.existing_lines.copy()
+
+        # Try to find the header in existing content
+        try:
+            header_index = existing_lines.index(header)
+            # Find the end of this section (next header or end of file)
+            section_end = header_index + 1
+            while section_end < len(existing_lines):
+                if existing_lines[section_end].startswith("#"):
+                    break
+                section_end += 1
+            # Insert new lines after the last line in this section
+            existing_lines[section_end:section_end] = lines_to_add
+        except ValueError:
+            # Header not found, add to end of file
+            if existing_lines and existing_lines[-1] != "":
+                existing_lines.append("")  # Add blank line before new section
+            existing_lines.append(header)
+            existing_lines.extend(lines_to_add)
+
+        # Write back the updated content
+        with self.path.open("w") as f:
+            f.write("\n".join(existing_lines) + "\n")
+
+        # Update cached lines
+        self._existing_lines = existing_lines
+
+
+def update_gitignore_with_repos(paths: Paths):
+    """Ensure all repos are in gitignore entries."""
+    repos = load_repos(paths=paths)
+    repo_entries = [f"{repo.name}/" for repo in repos]
+    gitignore = IgnoreFile(paths.gitignore_path)
+    gitignore.add_lines_if_missing(repo_entries, "# Ignore repository directories")
+    logger.debug("Updated .gitignore with new repositories")
+
+
+def update_ignore_with_repos(paths: Paths):
+    """Update .ignore to allow searching in gitignored directories."""
+    repos = load_repos(paths=paths)
+    repo_entries = [f"!{repo.name}/" for repo in repos]
+    vscode_ignore = IgnoreFile(paths.vscode_ignore_path)
+    vscode_ignore.add_lines_if_missing(
+        repo_entries,
+        "# Allow us to search inside these gitignored directories",
+    )
+    logger.debug("Updated .ignore with new repositories")
+
+
+def update_gitignore_with_vscode_files(paths: Paths):
+    """Add VS Code generated configuration files to gitignore entries."""
+    vscode_entries = [
+        ".vscode/launch.json",
+        ".vscode/settings.json",
+        ".vscode/tasks.json",
+        ".vscode/extensions.json",
+    ]
+    gitignore = IgnoreFile(paths.gitignore_path)
+    gitignore.add_lines_if_missing(vscode_entries, "# Generated files")
+    logger.debug("Updated .gitignore with VS Code configuration files")