multi-workspace 3.0.0__tar.gz

multi_workspace-3.0.0/.gitignore

@@ -0,0 +1,185 @@
+CLAUDE.md
+.data/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.gha
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+# .vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+staticfiles
+
+.env
+_version.py

multi_workspace-3.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Gabriel Montague
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

multi_workspace-3.0.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: multi-workspace
+Version: 3.0.0
+Summary: Multi
+Project-URL: Repository, https://github.com/gabemontague/multi
+Project-URL: Issues, https://github.com/gabemontague/multi/issues
+Author-email: Gabe Montague <gabemontague@outlook.com>
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: click>=8.3.1
+Requires-Dist: gitpython>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6.9.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: ruff>=0.11.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# multi
+
+`multi` is the best way to work with VS Code/Cursor on multiple Git repos at once. It is an alternative to [multi-root workspaces](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces) that offers more flexibility and control. With `multi`, you can gain control over how tasks, debug runnables, and various IDE and linter settings are combined from multiple project repos ("sub-repos") located in the same folder.
+
+Features:
+
+- Generates files in your root `.vscode` folder from sub-repo `launch.json`, `tasks.json`, and `settings.json` files.
+- Generates `CLAUDE.md` files from Cursor rules.
+
+## Installation
+
+### Using `pipx`:
+
+- Install [pipx](https://github.com/pypa/pipx)
+- Run `pipx install multi-sync`
+
+### Using `uv`
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Run `uv tool install multi-sync`
+
+## Getting started
+
+To get started, create a new workspace directory that will house all your related repos and run:
+
+```
+multi init
+```
+
+When prompted, paste in the URLs of all the repositories you want to have in your workspace. You can optionally specify descriptions of what they do, which will be used to create a new repo-directories.mdc Cursor/Claude rule.
+
+It is recommended you also install the [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=montaguegabe.multi-sync) that automatically keeps your project synced when edits are made to synced files. To manually sync, you can run `multi sync`.

multi_workspace-3.0.0/README.md

@@ -0,0 +1,32 @@
+# multi
+
+`multi` is the best way to work with VS Code/Cursor on multiple Git repos at once. It is an alternative to [multi-root workspaces](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces) that offers more flexibility and control. With `multi`, you can gain control over how tasks, debug runnables, and various IDE and linter settings are combined from multiple project repos ("sub-repos") located in the same folder.
+
+Features:
+
+- Generates files in your root `.vscode` folder from sub-repo `launch.json`, `tasks.json`, and `settings.json` files.
+- Generates `CLAUDE.md` files from Cursor rules.
+
+## Installation
+
+### Using `pipx`:
+
+- Install [pipx](https://github.com/pypa/pipx)
+- Run `pipx install multi-sync`
+
+### Using `uv`
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Run `uv tool install multi-sync`
+
+## Getting started
+
+To get started, create a new workspace directory that will house all your related repos and run:
+
+```
+multi init
+```
+
+When prompted, paste in the URLs of all the repositories you want to have in your workspace. You can optionally specify descriptions of what they do, which will be used to create a new repo-directories.mdc Cursor/Claude rule.
+
+It is recommended you also install the [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=montaguegabe.multi-sync) that automatically keeps your project synced when edits are made to synced files. To manually sync, you can run `multi sync`.

multi_workspace-3.0.0/multi/__init__.py

@@ -0,0 +1 @@
+

multi_workspace-3.0.0/multi/__main__.py

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

multi_workspace-3.0.0/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_workspace-3.0.0/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_workspace-3.0.0/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_workspace-3.0.0/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_workspace-3.0.0/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_workspace-3.0.0/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))