multi-workspace 3.0.5__tar.gz → 3.2.2__tar.gz

{multi_workspace-3.0.5 → multi_workspace-3.2.2}/.gitignore

@@ -1,4 +1,5 @@
 CLAUDE.md
+AGENTS.md
 .data/
 
 # Byte-compiled / optimized / DLL files
@@ -182,4 +183,10 @@ Thumbs.db
 staticfiles
 
 .env
-_version.py
+_version.py
+
+# BEGIN multi-managed: generated-files
+# These files are generated by multi.
+CLAUDE.md
+AGENTS.md
+# END multi-managed: generated-files

multi_workspace-3.2.2/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: multi-workspace
+Version: 3.2.2
+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.12
+Requires-Dist: click>=8.3.1
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: pyyaml>=6.0.2
+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'
+Requires-Dist: zensical; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# multi
+
+`multi` is a better 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 within a root workspace folder.
+
+**[Documentation](https://multi.bighelp.ai/)**
+
+Features:
+
+- Generates files in your root `.vscode` folder from sub-repo `launch.json`, `tasks.json`, and `settings.json` files.
+- Supports optional `installSets` so installer scripts can sync only a public/runtime subset of repos.
+- Optionally generates `CLAUDE.md` and `AGENTS.md` files from tracked `AGENTS.parts/*.md` files.
+- In monorepo mode, syncs sub-repo GitHub workflows into root `.github/workflows`.
+
+## Installation
+
+### Using `pipx`:
+
+- Install [pipx](https://github.com/pypa/pipx)
+- Run `pipx install multi-workspace`
+
+### Using `uv`
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Run `uv tool install multi-workspace`
+
+## 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 can be included in generated agent instruction files when that feature is enabled.
+
+For scripts, you can also initialize non-interactively:
+
+```bash
+multi init \
+  --repo https://github.com/org/backend \
+  --repo-description "Backend API" \
+  --repo https://github.com/org/frontend \
+  --repo-description "Frontend app"
+```
+
+To create GitHub repositories first, add `--github-repo` entries. This uses `gh repo create` and defaults to private visibility:
+
+```bash
+multi init \
+  --github-repo org/backend \
+  --github-description "Backend API" \
+  --github-repo org/frontend \
+  --github-description "Frontend app"
+```
+
+For `--github-repo`, the GitHub CLI (`gh`) must already be installed and authenticated.
+
+When repository slugs are product-prefixed, `multi init` automatically writes short local directory names into `multi.json` when the slug matches the workspace name prefix. For example, in a `t-ide/` workspace, `t-ide-cli` becomes local folder `cli`.
+
+The same naming rule applies to `multi add`, so adding `https://github.com/org/t-ide-cli` inside a `t-ide/` workspace will also default to local folder `cli`.
+
+For public installer workflows, add `installSets` to repo entries and run a filtered sync:
+
+```json
+{
+  "repos": [
+    { "name": "cli", "url": "https://github.com/org/product-cli", "installSets": ["default", "dev"] },
+    { "name": "ios", "url": "git@github.com:org/product-ios.git", "installSets": ["dev"] }
+  ]
+}
+```
+
+```bash
+multi sync --install-set default
+```
+
+Running `multi sync` without `--install-set` still includes every repo. Repos without `installSets` are included in every named set.
+
+To grant or remove GitHub collaborator access across every GitHub repo in a workspace, use:
+
+```bash
+multi collaborator add octocat --permission maintain --yes
+multi collaborator add --yes
+multi collaborator remove octocat --yes
+multi collaborator recent-users
+```
+
+When the workspace root repository has a GitHub `origin`, `multi collaborator` applies the change there too.
+
+Recent collaborator usernames are saved under `~/.multi`, and `multi collaborator add` can prompt from that list when no username is supplied.
+
+If one repo fails, `multi collaborator` continues through the rest of the workspace and reports the failures at the end.
+
+It is recommended you also install the [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=montaguegabe.multi-workspace) that automatically keeps your project synced when edits are made to synced files. To manually sync, you can run `multi sync`.

multi_workspace-3.2.2/README.md

@@ -0,0 +1,94 @@
+# multi
+
+`multi` is a better 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 within a root workspace folder.
+
+**[Documentation](https://multi.bighelp.ai/)**
+
+Features:
+
+- Generates files in your root `.vscode` folder from sub-repo `launch.json`, `tasks.json`, and `settings.json` files.
+- Supports optional `installSets` so installer scripts can sync only a public/runtime subset of repos.
+- Optionally generates `CLAUDE.md` and `AGENTS.md` files from tracked `AGENTS.parts/*.md` files.
+- In monorepo mode, syncs sub-repo GitHub workflows into root `.github/workflows`.
+
+## Installation
+
+### Using `pipx`:
+
+- Install [pipx](https://github.com/pypa/pipx)
+- Run `pipx install multi-workspace`
+
+### Using `uv`
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Run `uv tool install multi-workspace`
+
+## 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 can be included in generated agent instruction files when that feature is enabled.
+
+For scripts, you can also initialize non-interactively:
+
+```bash
+multi init \
+  --repo https://github.com/org/backend \
+  --repo-description "Backend API" \
+  --repo https://github.com/org/frontend \
+  --repo-description "Frontend app"
+```
+
+To create GitHub repositories first, add `--github-repo` entries. This uses `gh repo create` and defaults to private visibility:
+
+```bash
+multi init \
+  --github-repo org/backend \
+  --github-description "Backend API" \
+  --github-repo org/frontend \
+  --github-description "Frontend app"
+```
+
+For `--github-repo`, the GitHub CLI (`gh`) must already be installed and authenticated.
+
+When repository slugs are product-prefixed, `multi init` automatically writes short local directory names into `multi.json` when the slug matches the workspace name prefix. For example, in a `t-ide/` workspace, `t-ide-cli` becomes local folder `cli`.
+
+The same naming rule applies to `multi add`, so adding `https://github.com/org/t-ide-cli` inside a `t-ide/` workspace will also default to local folder `cli`.
+
+For public installer workflows, add `installSets` to repo entries and run a filtered sync:
+
+```json
+{
+  "repos": [
+    { "name": "cli", "url": "https://github.com/org/product-cli", "installSets": ["default", "dev"] },
+    { "name": "ios", "url": "git@github.com:org/product-ios.git", "installSets": ["dev"] }
+  ]
+}
+```
+
+```bash
+multi sync --install-set default
+```
+
+Running `multi sync` without `--install-set` still includes every repo. Repos without `installSets` are included in every named set.
+
+To grant or remove GitHub collaborator access across every GitHub repo in a workspace, use:
+
+```bash
+multi collaborator add octocat --permission maintain --yes
+multi collaborator add --yes
+multi collaborator remove octocat --yes
+multi collaborator recent-users
+```
+
+When the workspace root repository has a GitHub `origin`, `multi collaborator` applies the change there too.
+
+Recent collaborator usernames are saved under `~/.multi`, and `multi collaborator add` can prompt from that list when no username is supplied.
+
+If one repo fails, `multi collaborator` continues through the rest of the workspace and reports the failures at the end.
+
+It is recommended you also install the [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=montaguegabe.multi-workspace) that automatically keeps your project synced when edits are made to synced files. To manually sync, you can run `multi sync`.

multi_workspace-3.2.2/multi/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '3.2.2'
+__version_tuple__ = version_tuple = (3, 2, 2)
+
+__commit_id__ = commit_id = None

multi_workspace-3.2.2/multi/add.py

@@ -0,0 +1,116 @@
+import json
+import logging
+import shutil
+from pathlib import Path
+
+import click
+import git
+
+from multi.paths import Paths
+from multi.repo_urls import (
+    derive_explicit_local_name,
+    derive_repo_slug_from_url,
+    normalize_repo_url,
+)
+from multi.sync import sync
+
+logger = logging.getLogger(__name__)
+
+
+@click.command(name="add")
+@click.argument("repo_url")
+@click.option("--name", default=None, help="Override directory name derived from URL")
+def add_cmd(repo_url: str, name: str | None):
+    """Add a repository to the workspace.
+
+    Appends the repo to multi.json and runs sync to clone it
+    and merge all configurations. In monorepo mode, the repo's
+    .git directory is removed after cloning so it becomes part
+    of the root repository.
+    """
+    paths = Paths(Path.cwd())
+    is_monorepo = paths.settings.is_monorepo()
+
+    # Read multi.json as raw JSON
+    with paths.multi_json_path.open("r") as f:
+        config = json.load(f)
+
+    repos_list = config.get("repos", [])
+
+    # Check for duplicate URL
+    normalized_new = normalize_repo_url(repo_url)
+    for entry in repos_list:
+        existing_url = entry.get("url", "")
+        if normalize_repo_url(existing_url) == normalized_new:
+            raise click.ClickException(
+                f"A repo with URL '{existing_url}' already exists in multi.json."
+            )
+
+    # Derive or validate name
+    auto_name = derive_explicit_local_name(
+        repo_url,
+        paths.root_dir.name,
+    )
+    slug_name = derive_repo_slug_from_url(repo_url)
+
+    existing_names = {
+        entry.get("name") or derive_repo_slug_from_url(entry.get("url", ""))
+        for entry in repos_list
+    }
+
+    if (
+        not name
+        and auto_name
+        and (
+            auto_name in existing_names
+            or (paths.root_dir / auto_name).exists()
+        )
+    ):
+        auto_name = None
+
+    repo_name = name if name else (auto_name or slug_name)
+
+    # Check for duplicate name
+    if repo_name in existing_names:
+        raise click.ClickException(
+            f"A repo with name '{repo_name}' already exists in multi.json."
+        )
+
+    # Check target directory doesn't already exist
+    target_dir = paths.root_dir / repo_name
+    if target_dir.exists():
+        raise click.ClickException(f"Directory '{repo_name}' already exists on disk.")
+
+    # In monorepo mode, clone and remove .git before writing multi.json,
+    # since sync() skips clone_repos() in monorepo mode.
+    if is_monorepo:
+        logger.info(f"Cloning {repo_name}...")
+        git.Repo.clone_from(repo_url, target_dir)
+        git_dir = target_dir / ".git"
+        if git_dir.is_dir():
+            shutil.rmtree(git_dir)
+        elif git_dir.exists() or git_dir.is_symlink():
+            git_dir.unlink()
+        logger.info(f"Cloned {repo_name} and removed .git for monorepo mode")
+
+    # Build new entry
+    new_entry: dict = {"url": repo_url}
+    if name:
+        new_entry["name"] = name
+    elif auto_name:
+        new_entry["name"] = auto_name
+
+    repos_list.append(new_entry)
+    config["repos"] = repos_list
+
+    # Write multi.json
+    with paths.multi_json_path.open("w") as f:
+        json.dump(config, f, indent=2)
+        f.write("\n")
+
+    logger.info(f"Added '{repo_name}' to multi.json")
+
+    # Run full sync to clone (non-monorepo) and merge configs
+    sync(root_dir=paths.root_dir)
+
+    logger.info(f"✅ Successfully added {repo_name}")

multi_workspace-3.2.2/multi/api.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from multi.sync import sync
+
+
+def sync_workspace(
+    root_dir: str | Path,
+    *,
+    install_set: str | None = None,
+    ensure_on_same_branch: bool = True,
+) -> None:
+    """Sync a Multi workspace from Python code."""
+    sync(
+        root_dir=Path(root_dir),
+        ensure_on_same_branch=ensure_on_same_branch,
+        install_set=install_set,
+    )