gitmux 0.1.0__py3-none-any.whl

gitmux/__init__.py

@@ -0,0 +1,3 @@
+"""gitmux - Manage multiple git repositories with ease."""
+
+__version__ = "0.1.0"

gitmux/cli.py

@@ -0,0 +1,535 @@
+"""gitmux CLI entry point."""
+
+from pathlib import Path
+
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.table import Table
+
+from gitmux import __version__
+from gitmux.config import DEFAULT_CONFIG_PATH, find_config, load_config, save_config, validate_config
+from gitmux.models import GitmuxConfig, GroupConfig, RepoConfig
+
+app = typer.Typer(name="gitmux", help="Manage multiple git repositories with ease.", no_args_is_help=True)
+group_app = typer.Typer(name="group", help="Manage repository groups.")
+app.add_typer(group_app, name="group")
+
+console = Console()
+
+CONFIG_OPT = typer.Option(None, "--config", "-c", help="Path to config file.")
+
+
+def _load(config_path: Path | None) -> GitmuxConfig:
+    path = Path(config_path) if config_path else find_config()
+    if not path.exists():
+        rprint(f"[red]Config not found: {path}[/]\nRun [bold]gitmux init[/] first.")
+        raise typer.Exit(1)
+    cfg = load_config(path)
+    errors = validate_config(cfg)
+    if errors:
+        for e in errors:
+            rprint(f"[red]Config error:[/] {e}")
+        raise typer.Exit(1)
+    return cfg
+
+
+def _save(config: GitmuxConfig, config_path: Path | None) -> None:
+    save_config(config, Path(config_path) if config_path else find_config())
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        rprint(f"gitmux [bold green]{__version__}[/]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-v",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Manage multiple git repositories with ease."""
+
+
+@app.command()
+def init(
+    workspace: str = typer.Option("~/projects", prompt="Workspace directory"),
+    global_: bool = typer.Option(False, "--global", "-g", help="Create global config at ~/.gitmux.yaml"),
+) -> None:
+    """Initialize a new .gitmux.yaml configuration file."""
+    path = DEFAULT_CONFIG_PATH if global_ else Path.cwd() / ".gitmux.yaml"
+    if path.exists():
+        overwrite = typer.confirm(f"{path} already exists. Overwrite?", default=False)
+        if not overwrite:
+            raise typer.Exit()
+    cfg = GitmuxConfig(workspace=workspace)
+    save_config(cfg, path)
+    rprint(f"[green]Config created:[/] {path}")
+
+
+@app.command()
+def add(
+    url: str = typer.Argument(..., help="Git repository URL."),
+    group: str = typer.Option("default", "--group", "-g", help="Group to add the repo to."),
+    name: str | None = typer.Option(None, "--name", "-n", help="Repo name (default: derived from URL)."),
+    template: str | None = typer.Option(None, "--template", "-t", help="Hook template to use."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Add a repository to the configuration."""
+    cfg = _load(config)
+    repo_name = name or url.rstrip("/").split("/")[-1].removesuffix(".git")
+    if cfg.find_repo(repo_name):
+        rprint(f"[red]Repo '{repo_name}' already exists.[/]")
+        raise typer.Exit(1)
+
+    grp = cfg.find_group(group)
+    if not grp:
+        grp = GroupConfig(name=group)
+        cfg.groups.append(grp)
+        rprint(f"[dim]Created group:[/] {group}")
+
+    if template and template not in cfg.templates:
+        rprint(f"[red]Template '{template}' not found.[/]")
+        raise typer.Exit(1)
+
+    repo = RepoConfig(name=repo_name, url=url, template=template)
+    grp.repos.append(repo)
+    _save(cfg, config)
+    rprint(f"[green]Added[/] {repo_name} to group '{group}'")
+
+
+@app.command()
+def remove(
+    name: str = typer.Argument(..., help="Repository name to remove."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Remove a repository from the configuration."""
+    cfg = _load(config)
+    result = cfg.find_repo(name)
+    if not result:
+        rprint(f"[red]Repo '{name}' not found.[/]")
+        raise typer.Exit(1)
+    repo, grp = result
+    grp.repos.remove(repo)
+    _save(cfg, config)
+    rprint(f"[green]Removed[/] {name} from group '{grp.name}'")
+
+
+@app.command(name="list")
+def list_repos(
+    group: str | None = typer.Option(None, "--group", "-g", help="Filter by group."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """List all configured repositories."""
+    cfg = _load(config)
+    table = Table(title="Repositories")
+    table.add_column("Group", style="cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("URL")
+    table.add_column("Path")
+    table.add_column("Template", style="dim")
+
+    for grp in cfg.groups:
+        if group and grp.name != group:
+            continue
+        for repo in grp.repos:
+            path = str(cfg.get_repo_path(repo, grp))
+            table.add_row(grp.name, repo.name, repo.url, path, repo.template or "")
+
+    console.print(table)
+
+
+# --- Group subcommands ---
+
+
+DEFAULT_GROUP = "default"
+
+
+def _get_repos(cfg: GitmuxConfig, target: str | None, all_: bool, group: str | None = None) -> list[tuple]:
+    """Resolve target repos.
+
+    - target = "name" → find repo in default group
+    - target = "group/name" → find repo in specified group
+    - --group = operate on entire group
+    - --all = all repos
+    - nothing = error
+    """
+    if target:
+        if "/" in target:
+            group_name, repo_name = target.split("/", 1)
+        else:
+            group_name, repo_name = DEFAULT_GROUP, target
+        grp = cfg.find_group(group_name)
+        if not grp:
+            rprint(f"[red]Group '{group_name}' not found.[/]")
+            raise typer.Exit(1)
+        for repo in grp.repos:
+            if repo.name == repo_name:
+                return [(repo, grp)]
+        rprint(f"[red]Repo '{repo_name}' not found in group '{group_name}'.[/]")
+        raise typer.Exit(1)
+    if group:
+        grp = cfg.find_group(group)
+        if not grp:
+            rprint(f"[red]Group '{group}' not found.[/]")
+            raise typer.Exit(1)
+        return [(r, grp) for r in grp.repos]
+    if all_:
+        return cfg.all_repos()
+    rprint("[red]Please specify a repo, --group, or --all.[/]")
+    raise typer.Exit(1)
+
+
+@app.command()
+def clone(
+    target: str | None = typer.Argument(None, help="Repo name or group/repo."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Operate on entire group."),
+    all_: bool = typer.Option(False, "--all", "-a", help="Operate on all repositories."),
+    parallel: bool = typer.Option(False, "--parallel", "-p", help="Run in parallel."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Clone repositories that haven't been cloned yet."""
+    from gitmux import git_ops
+    from gitmux.executor import run_parallel, run_serial
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_, group)
+
+    def do_clone(repo, grp, c):
+        path = c.get_repo_path(repo, grp)
+        if path.exists():
+            return git_ops.GitResult(True, "Already cloned", "skip")
+        return git_ops.clone(repo.url, path)
+
+    (run_parallel if parallel else run_serial)(cfg, repos, do_clone, "Clone")
+
+
+@app.command()
+def fetch(
+    target: str | None = typer.Argument(None, help="Repo name or group/repo."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Operate on entire group."),
+    all_: bool = typer.Option(False, "--all", "-a", help="Operate on all repositories."),
+    parallel: bool = typer.Option(False, "--parallel", "-p", help="Run in parallel."),
+    show_branches: bool = typer.Option(False, "--branches", help="Show remote branches after fetch."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Fetch latest remote data for repositories."""
+    from gitmux import git_ops
+    from gitmux.executor import run_parallel as run_par
+    from gitmux.executor import run_serial
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_, group)
+
+    def do_fetch(repo, grp, c):
+        path = c.get_repo_path(repo, grp)
+        if not path.exists():
+            return git_ops.GitResult(False, f"Not cloned: {path}", "git fetch")
+        result = git_ops.fetch(path)
+        if result.success and show_branches:
+            branches = git_ops.list_remote_branches(path, "*")
+            result = git_ops.GitResult(True, "\n".join(branches) if branches else "(no remote branches)", result.command)
+        return result
+
+    (run_par if parallel else run_serial)(cfg, repos, do_fetch, "Fetch")
+
+
+@app.command()
+def pull(
+    target: str | None = typer.Argument(None, help="Repo name or group/repo."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Operate on entire group."),
+    all_: bool = typer.Option(False, "--all", "-a", help="Operate on all repositories."),
+    branch: str | None = typer.Option(None, "--branch", "-b", help="Branch alias, e.g. 'dev', 'prod:latest', 'prod:~20260520', 'prod:20260524'."),
+    parallel: bool = typer.Option(False, "--parallel", "-p", help="Run in parallel."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Pull latest changes for repositories."""
+    from gitmux import git_ops
+    from gitmux.executor import run_parallel as run_par
+    from gitmux.executor import run_serial
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_, group)
+
+    # Parse --branch flag: "name" or "name:value"
+    branch_alias: str | None = None
+    branch_value: str | None = None
+    if branch:
+        if ":" in branch:
+            branch_alias, branch_value = branch.split(":", 1)
+        else:
+            branch_alias = branch
+
+    def do_pull(repo, grp, c):
+        path = c.get_repo_path(repo, grp)
+        if not path.exists():
+            return git_ops.GitResult(False, f"Not cloned: {path}", "git pull")
+
+        if not branch_alias:
+            return git_ops.pull(path)
+
+        # Resolve branch from config
+        if branch_alias not in repo.branches:
+            return git_ops.GitResult(
+                False, f"Branch alias '{branch_alias}' not configured", "branch resolve"
+            )
+
+        pattern = repo.branches[branch_alias]
+        is_pattern = "*" in pattern
+
+        if branch_value is None:
+            # gitmux pull --branch dev → must be fixed
+            if is_pattern:
+                return git_ops.GitResult(
+                    False,
+                    f"'{branch_alias}' is a pattern ({pattern}), use --branch {branch_alias}:latest or --branch {branch_alias}:<value>",
+                    "branch resolve",
+                )
+            target = pattern
+        elif branch_value == "latest":
+            # gitmux pull --branch prod:latest → must be pattern
+            if not is_pattern:
+                return git_ops.GitResult(
+                    False,
+                    f"'{branch_alias}' is a fixed branch ({pattern}), use --branch {branch_alias} directly",
+                    "branch resolve",
+                )
+            fetch_result = git_ops.fetch(path)
+            if not fetch_result.success:
+                return fetch_result
+            matches = git_ops.list_remote_branches(path, pattern)
+            if not matches:
+                return git_ops.GitResult(False, f"No remote branch matching '{pattern}'", "branch resolve")
+            target = matches[0]  # sorted by committerdate, newest first
+        elif branch_value.startswith("~"):
+            # gitmux pull --branch prod:~20260520 → find latest branch with date <= 20260520
+            if not is_pattern:
+                return git_ops.GitResult(
+                    False,
+                    f"'{branch_alias}' is a fixed branch ({pattern}), use --branch {branch_alias} directly",
+                    "branch resolve",
+                )
+            date_str = branch_value[1:]
+            # Normalize to 6-digit date for comparison (YYMMDD)
+            if len(date_str) == 8:
+                date_str = date_str[2:]
+            fetch_result = git_ops.fetch(path)
+            if not fetch_result.success:
+                return fetch_result
+            matches = git_ops.list_remote_branches(path, pattern)
+            if not matches:
+                return git_ops.GitResult(False, f"No remote branch matching '{pattern}'", "branch resolve")
+            # Extract date from branch names and find <= date_str
+            import re as _re
+            candidates = []
+            for m in matches:
+                found = _re.search(r"(\d{6})", m)
+                if found and found.group(1) <= date_str:
+                    candidates.append(m)
+            if not candidates:
+                return git_ops.GitResult(
+                    False,
+                    f"No branch matching '{pattern}' with date <= {date_str} (found: {matches[:5]})",
+                    "branch resolve",
+                )
+            target = candidates[0]  # already sorted by committerdate newest first
+        else:
+            # gitmux pull --branch prod:20260524 → replace * with value
+            if not is_pattern:
+                return git_ops.GitResult(
+                    False,
+                    f"'{branch_alias}' is a fixed branch ({pattern}), use --branch {branch_alias} directly",
+                    "branch resolve",
+                )
+            target = pattern.replace("*", branch_value)
+
+        # Fetch if not already done
+        if branch_value != "latest":
+            fetch_result = git_ops.fetch(path)
+            if not fetch_result.success:
+                return fetch_result
+
+        # Checkout and pull
+        checkout_result = git_ops.checkout(path, target)
+        if not checkout_result.success:
+            return git_ops.GitResult(False, f"Checkout failed: {checkout_result.output}", f"git checkout {target}")
+
+        pull_result = git_ops.pull(path)
+        msg = f"[{target}] {pull_result.output}"
+        return git_ops.GitResult(pull_result.success, msg, pull_result.command)
+
+    (run_par if parallel else run_serial)(cfg, repos, do_pull, "Pull")
+
+
+
+@app.command()
+def push(
+    target: str | None = typer.Argument(None, help="Repo name or group/repo."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Operate on entire group."),
+    all_: bool = typer.Option(False, "--all", "-a", help="Operate on all repositories."),
+    parallel: bool = typer.Option(False, "--parallel", "-p", help="Run in parallel."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Push local commits for repositories."""
+    from gitmux import git_ops
+    from gitmux.executor import run_parallel, run_serial
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_, group)
+
+    def do_push(repo, grp, c):
+        path = c.get_repo_path(repo, grp)
+        if not path.exists():
+            return git_ops.GitResult(False, f"Not cloned: {path}", "git push")
+        return git_ops.push(path)
+
+    (run_parallel if parallel else run_serial)(cfg, repos, do_push, "Push")
+
+
+@app.command(name="exec")
+def exec_cmd(
+    command: str = typer.Argument(..., help="Shell command to execute in each repo."),
+    target: str | None = typer.Option(None, "--target", "-t", help="Repo name or group/repo."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Operate on entire group."),
+    all_: bool = typer.Option(False, "--all", "-a", help="Operate on all repositories."),
+    parallel: bool = typer.Option(False, "--parallel", "-p", help="Run in parallel."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Execute an arbitrary command in each repository directory."""
+    import subprocess
+
+    from gitmux.executor import run_parallel, run_serial
+    from gitmux.git_ops import GitResult
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_, group)
+
+    def do_exec(repo, grp, c):
+        path = c.get_repo_path(repo, grp)
+        if not path.exists():
+            return GitResult(False, f"Directory not found: {path}", command)
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                cwd=path,
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            output = (result.stdout + result.stderr).strip()
+            return GitResult(result.returncode == 0, output, command)
+        except subprocess.TimeoutExpired:
+            return GitResult(False, "Command timed out (120s)", command)
+
+    (run_parallel if parallel else run_serial)(cfg, repos, do_exec, "Exec")
+
+
+@app.command()
+def status(
+    target: str | None = typer.Argument(None, help="Repo name or group/repo. Shows all if omitted."),
+    group: str | None = typer.Option(None, "--group", "-g", help="Filter by group."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Show status overview of all repositories."""
+    from gitmux import git_ops
+
+    cfg = _load(config)
+    repos = _get_repos(cfg, target, all_=not target and not group, group=group)
+
+    table = Table(title="Repository Status")
+    table.add_column("Group", style="cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("Branch")
+    table.add_column("Status")
+    table.add_column("Ahead/Behind")
+    table.add_column("Last Commit", style="dim", max_width=40)
+
+    for repo, grp in repos:
+        path = cfg.get_repo_path(repo, grp)
+        if not path.exists():
+            table.add_row(grp.name, repo.name, "-", "[red]Not cloned[/]", "-", "-")
+            continue
+
+        branch_result = git_ops.current_branch(path)
+        branch = branch_result.output if branch_result.success else "?"
+
+        status_result = git_ops.status(path)
+        if status_result.success:
+            state = "[green]Clean[/]" if not status_result.output else "[yellow]Dirty[/]"
+        else:
+            state = "[red]Error[/]"
+
+        ahead, behind = git_ops.ahead_behind(path)
+        ab = ""
+        if ahead:
+            ab += f"[green]↑{ahead}[/]"
+        if behind:
+            ab += f"[red]↓{behind}[/]"
+        if not ab:
+            ab = "[dim]—[/]"
+
+        commit = git_ops.last_commit(path)
+        table.add_row(grp.name, repo.name, branch, state, ab, commit)
+
+    console.print(table)
+
+
+# --- Group subcommands ---
+
+
+@group_app.command(name="list")
+def group_list(config: Path | None = CONFIG_OPT) -> None:
+    """List all groups."""
+    cfg = _load(config)
+    if not cfg.groups:
+        rprint("[dim]No groups configured.[/]")
+        return
+    table = Table(title="Groups")
+    table.add_column("Name", style="cyan bold")
+    table.add_column("Repos", justify="right")
+    for grp in cfg.groups:
+        table.add_row(grp.name, str(len(grp.repos)))
+    console.print(table)
+
+
+@group_app.command(name="create")
+def group_create(
+    name: str = typer.Argument(..., help="Group name."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Create a new group."""
+    cfg = _load(config)
+    if cfg.find_group(name):
+        rprint(f"[red]Group '{name}' already exists.[/]")
+        raise typer.Exit(1)
+    cfg.groups.append(GroupConfig(name=name))
+    _save(cfg, config)
+    rprint(f"[green]Created group:[/] {name}")
+
+
+@group_app.command(name="remove")
+def group_remove(
+    name: str = typer.Argument(..., help="Group name."),
+    force: bool = typer.Option(False, "--force", "-f", help="Remove even if group has repos."),
+    config: Path | None = CONFIG_OPT,
+) -> None:
+    """Remove a group."""
+    cfg = _load(config)
+    grp = cfg.find_group(name)
+    if not grp:
+        rprint(f"[red]Group '{name}' not found.[/]")
+        raise typer.Exit(1)
+    if grp.repos and not force:
+        rprint(f"[red]Group '{name}' has {len(grp.repos)} repos.[/] Use --force to remove.")
+        raise typer.Exit(1)
+    cfg.groups.remove(grp)
+    _save(cfg, config)
+    rprint(f"[green]Removed group:[/] {name}")

gitmux/config.py

@@ -0,0 +1,131 @@
+"""Configuration loading, saving, and validation."""
+
+from pathlib import Path
+
+import yaml
+
+from gitmux.models import GitmuxConfig, GroupConfig, HookConfig, RepoConfig
+
+DEFAULT_CONFIG_PATH = Path.home() / ".gitmux.yaml"
+LOCAL_CONFIG_NAME = ".gitmux.yaml"
+
+
+def find_config() -> Path:
+    """Find config file: current dir → home dir."""
+    local = Path.cwd() / LOCAL_CONFIG_NAME
+    if local.exists():
+        return local
+    return DEFAULT_CONFIG_PATH
+
+
+def _parse_hooks(data: dict | None) -> HookConfig:
+    if not data:
+        return HookConfig()
+    return HookConfig(
+        pre_clone=data.get("pre_clone", []),
+        post_clone=data.get("post_clone", []),
+        pre_pull=data.get("pre_pull", []),
+        post_pull=data.get("post_pull", []),
+        pre_push=data.get("pre_push", []),
+        post_push=data.get("post_push", []),
+    )
+
+
+def _parse_repo(data: dict) -> RepoConfig:
+    return RepoConfig(
+        name=data["name"],
+        url=data["url"],
+        path=data.get("path"),
+        template=data.get("template"),
+        hooks=_parse_hooks(data.get("hooks")),
+        branches=data.get("branches") or {},
+    )
+
+
+def load_config(path: Path | None = None) -> GitmuxConfig:
+    """Load and parse gitmux config from YAML file."""
+    path = path or DEFAULT_CONFIG_PATH
+    if not path.exists():
+        return GitmuxConfig()
+
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+
+    templates = {}
+    for name, hook_data in (data.get("templates") or {}).items():
+        templates[name] = _parse_hooks(hook_data)
+
+    groups = []
+    for group_name, group_data in (data.get("groups") or {}).items():
+        repos = [_parse_repo(r) for r in (group_data.get("repos") or [])]
+        groups.append(GroupConfig(name=group_name, repos=repos))
+
+    return GitmuxConfig(
+        workspace=data.get("workspace", "~/projects"),
+        templates=templates,
+        groups=groups,
+    )
+
+
+def _hooks_to_dict(hooks: HookConfig) -> dict | None:
+    d = {}
+    for key in ("pre_clone", "post_clone", "pre_pull", "post_pull", "pre_push", "post_push"):
+        val = getattr(hooks, key)
+        if val:
+            d[key] = val
+    return d or None
+
+
+def save_config(config: GitmuxConfig, path: Path | None = None) -> None:
+    """Save gitmux config to YAML file."""
+    path = path or DEFAULT_CONFIG_PATH
+    data: dict = {"workspace": config.workspace}
+
+    if config.templates:
+        data["templates"] = {}
+        for name, hooks in config.templates.items():
+            data["templates"][name] = _hooks_to_dict(hooks) or {}
+
+    if config.groups:
+        data["groups"] = {}
+        for group in config.groups:
+            repos = []
+            for repo in group.repos:
+                r: dict = {"name": repo.name, "url": repo.url}
+                if repo.path:
+                    r["path"] = repo.path
+                if repo.template:
+                    r["template"] = repo.template
+                hooks_dict = _hooks_to_dict(repo.hooks)
+                if hooks_dict:
+                    r["hooks"] = hooks_dict
+                if repo.branches:
+                    r["branches"] = repo.branches
+                repos.append(r)
+            data["groups"][group.name] = {"repos": repos}
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+
+def validate_config(config: GitmuxConfig) -> list[str]:
+    """Validate config, return list of error messages."""
+    errors = []
+    repo_names: set[str] = set()
+    group_names: set[str] = set()
+
+    for group in config.groups:
+        if group.name in group_names:
+            errors.append(f"Duplicate group name: {group.name}")
+        group_names.add(group.name)
+
+        for repo in group.repos:
+            if repo.name in repo_names:
+                errors.append(f"Duplicate repo name: {repo.name}")
+            repo_names.add(repo.name)
+
+            if repo.template and repo.template not in config.templates:
+                errors.append(f"Repo '{repo.name}' references unknown template: {repo.template}")
+
+    return errors

gitmux/executor.py

@@ -0,0 +1,125 @@
+"""Execution engine for git operations (serial and parallel)."""
+
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn
+
+from gitmux.git_ops import GitResult
+from gitmux.hooks import resolve_hooks, run_hooks
+from gitmux.models import GitmuxConfig, GroupConfig, RepoConfig
+from gitmux.output import console, print_error, print_header, print_step, print_success
+
+
+@dataclass
+class RepoResult:
+    repo_name: str
+    success: bool
+    message: str
+
+
+def _execute_one(
+    repo: RepoConfig,
+    group: GroupConfig,
+    config: GitmuxConfig,
+    operation: Callable[[RepoConfig, GroupConfig, GitmuxConfig], GitResult],
+    op_name: str,
+) -> RepoResult:
+    """Execute pre-hook → operation → post-hook for a single repo."""
+    path = config.get_repo_path(repo, group)
+    hooks = resolve_hooks(repo, config)
+    pre_cmds = getattr(hooks, f"pre_{op_name.lower()}", [])
+    post_cmds = getattr(hooks, f"post_{op_name.lower()}", [])
+
+    # Pre-hook
+    if pre_cmds and path.exists():
+        hook_result = run_hooks(pre_cmds, path, label=f"pre-{op_name.lower()}")
+        if not hook_result.success:
+            return RepoResult(repo.name, False, f"Pre-hook failed: {hook_result.failed_command}\n{hook_result.output}")
+
+    # Git operation
+    git_result = operation(repo, group, config)
+    if not git_result.success:
+        return RepoResult(repo.name, False, git_result.output)
+
+    # Post-hook
+    if post_cmds and path.exists():
+        hook_result = run_hooks(post_cmds, path, label=f"post-{op_name.lower()}")
+        if not hook_result.success:
+            return RepoResult(repo.name, False, f"Post-hook failed: {hook_result.failed_command}\n{hook_result.output}")
+
+    return RepoResult(repo.name, True, git_result.output)
+
+
+def run_serial(
+    config: GitmuxConfig,
+    repos: list[tuple[RepoConfig, GroupConfig]],
+    operation: Callable[[RepoConfig, GroupConfig, GitmuxConfig], GitResult],
+    op_name: str,
+) -> list[RepoResult]:
+    """Execute an operation on repos serially with real-time output."""
+    print_header(op_name)
+    results: list[RepoResult] = []
+
+    for repo, group in repos:
+        print_step(repo.name, op_name.lower())
+        result = _execute_one(repo, group, config, operation, op_name)
+        if result.success:
+            print_success(repo.name, result.message)
+        else:
+            print_error(repo.name, result.message)
+        results.append(result)
+
+    _print_summary(results)
+    return results
+
+
+def run_parallel(
+    config: GitmuxConfig,
+    repos: list[tuple[RepoConfig, GroupConfig]],
+    operation: Callable[[RepoConfig, GroupConfig, GitmuxConfig], GitResult],
+    op_name: str,
+    max_workers: int = 4,
+) -> list[RepoResult]:
+    """Execute an operation on repos in parallel with progress bar."""
+    results: list[RepoResult] = []
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[bold]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+    ) as progress:
+        task = progress.add_task(f"{op_name}...", total=len(repos))
+
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {
+                executor.submit(_execute_one, repo, group, config, operation, op_name): repo.name
+                for repo, group in repos
+            }
+            for future in as_completed(futures):
+                result = future.result()
+                results.append(result)
+                progress.advance(task)
+
+    # Print detailed results
+    console.print()
+    for r in results:
+        if r.success:
+            console.print(f"  [bold cyan]{r.repo_name}[/] [green]✓[/]")
+        else:
+            console.print(f"  [bold cyan]{r.repo_name}[/] [red]✗[/] {r.message}")
+
+    _print_summary(results)
+    return results
+
+
+def _print_summary(results: list[RepoResult]) -> None:
+    success_count = sum(1 for r in results if r.success)
+    fail_count = len(results) - success_count
+    summary = f"\n[green]{success_count} succeeded[/]"
+    if fail_count:
+        summary += f", [red]{fail_count} failed[/]"
+    console.print(summary)

gitmux/git_ops.py

@@ -0,0 +1,103 @@
+"""Git operation wrappers using subprocess."""
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class GitResult:
+    success: bool
+    output: str
+    command: str
+
+
+def _run(args: list[str], cwd: Path | None = None) -> GitResult:
+    cmd_str = " ".join(args)
+    try:
+        result = subprocess.run(
+            args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=300,
+        )
+        output = ((result.stdout or "") + (result.stderr or "")).strip()
+        return GitResult(success=result.returncode == 0, output=output, command=cmd_str)
+    except subprocess.TimeoutExpired:
+        return GitResult(success=False, output="Command timed out (300s)", command=cmd_str)
+    except FileNotFoundError:
+        return GitResult(success=False, output="git not found in PATH", command=cmd_str)
+
+
+def clone(url: str, dest: Path) -> GitResult:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    return _run(["git", "clone", url, str(dest)])
+
+
+def pull(repo_path: Path) -> GitResult:
+    return _run(["git", "pull"], cwd=repo_path)
+
+
+def push(repo_path: Path) -> GitResult:
+    return _run(["git", "push"], cwd=repo_path)
+
+
+def status(repo_path: Path) -> GitResult:
+    return _run(["git", "status", "--porcelain"], cwd=repo_path)
+
+
+def current_branch(repo_path: Path) -> GitResult:
+    return _run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=repo_path)
+
+
+def ahead_behind(repo_path: Path) -> tuple[int, int]:
+    """Return (ahead, behind) counts relative to upstream."""
+    result = _run(["git", "rev-list", "--left-right", "--count", "HEAD...@{upstream}"], cwd=repo_path)
+    if not result.success:
+        return 0, 0
+    parts = result.output.split()
+    if len(parts) == 2:
+        return int(parts[0]), int(parts[1])
+    return 0, 0
+
+
+def last_commit(repo_path: Path) -> str:
+    result = _run(["git", "log", "-1", "--format=%s"], cwd=repo_path)
+    return result.output if result.success else ""
+
+
+def fetch(repo_path: Path) -> GitResult:
+    return _run(["git", "fetch", "--prune"], cwd=repo_path)
+
+
+def checkout(repo_path: Path, branch: str) -> GitResult:
+    """Checkout a branch. Try local first, then track remote."""
+    result = _run(["git", "checkout", branch], cwd=repo_path)
+    if not result.success and "did not match" in result.output:
+        # Try to create local branch tracking remote
+        result = _run(["git", "checkout", "-b", branch, f"origin/{branch}"], cwd=repo_path)
+    return result
+
+
+def list_remote_branches(repo_path: Path, pattern: str) -> list[str]:
+    """List remote branches matching a glob pattern, sorted by committerdate (newest first)."""
+    import fnmatch
+
+    result = _run(
+        ["git", "branch", "-r", "--sort=-committerdate", "--format=%(refname:short)"],
+        cwd=repo_path,
+    )
+    if not result.success:
+        return []
+
+    branches = []
+    for line in result.output.splitlines():
+        line = line.strip()
+        # Remove origin/ prefix for matching
+        branch_name = line.removeprefix("origin/")
+        if fnmatch.fnmatch(branch_name, pattern):
+            branches.append(branch_name)
+    return branches

gitmux/hooks.py

@@ -0,0 +1,59 @@
+"""Hook execution and template merging logic."""
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from gitmux.models import GitmuxConfig, HookConfig, RepoConfig
+from gitmux.output import console
+
+
+@dataclass
+class HookResult:
+    success: bool
+    failed_command: str | None = None
+    output: str = ""
+
+
+def resolve_hooks(repo: RepoConfig, config: GitmuxConfig) -> HookConfig:
+    """Merge template hooks with repo-level hooks. Repo-level overrides template."""
+    if not repo.template:
+        return repo.hooks
+
+    template = config.templates.get(repo.template)
+    if not template:
+        return repo.hooks
+
+    # For each hook type, use repo's if non-empty, else template's
+    merged = HookConfig()
+    for field in ("pre_clone", "post_clone", "pre_pull", "post_pull", "pre_push", "post_push"):
+        repo_val = getattr(repo.hooks, field)
+        template_val = getattr(template, field)
+        setattr(merged, field, repo_val if repo_val else template_val)
+    return merged
+
+
+def run_hooks(commands: list[str], cwd: Path, label: str = "") -> HookResult:
+    """Execute a list of hook commands sequentially in the given directory."""
+    if not commands:
+        return HookResult(success=True)
+
+    for cmd in commands:
+        if label:
+            console.print(f"    [dim]hook ({label}):[/] {cmd}")
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            if result.returncode != 0:
+                output = (result.stdout + result.stderr).strip()
+                return HookResult(success=False, failed_command=cmd, output=output)
+        except subprocess.TimeoutExpired:
+            return HookResult(success=False, failed_command=cmd, output="Timed out (120s)")
+
+    return HookResult(success=True)

gitmux/models.py

@@ -0,0 +1,63 @@
+"""Data models for gitmux configuration."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class HookConfig:
+    pre_clone: list[str] = field(default_factory=list)
+    post_clone: list[str] = field(default_factory=list)
+    pre_pull: list[str] = field(default_factory=list)
+    post_pull: list[str] = field(default_factory=list)
+    pre_push: list[str] = field(default_factory=list)
+    post_push: list[str] = field(default_factory=list)
+
+
+@dataclass
+class RepoConfig:
+    name: str
+    url: str
+    path: str | None = None
+    template: str | None = None
+    hooks: HookConfig = field(default_factory=HookConfig)
+    branches: dict[str, str] = field(default_factory=dict)  # e.g. {"prod": "a-plan-*", "dev": "a-dev-main"}
+
+
+@dataclass
+class GroupConfig:
+    name: str
+    repos: list[RepoConfig] = field(default_factory=list)
+
+
+@dataclass
+class GitmuxConfig:
+    workspace: str = "~/projects"
+    templates: dict[str, HookConfig] = field(default_factory=dict)
+    groups: list[GroupConfig] = field(default_factory=list)
+
+    def get_repo_path(self, repo: RepoConfig, group: GroupConfig) -> Path:
+        """Resolve the local path for a repo."""
+        if repo.path:
+            return Path(repo.path).expanduser()
+        return Path(self.workspace).expanduser() / group.name / repo.name
+
+    def find_repo(self, name: str) -> tuple[RepoConfig, GroupConfig] | None:
+        for group in self.groups:
+            for repo in group.repos:
+                if repo.name == name:
+                    return repo, group
+        return None
+
+    def find_group(self, name: str) -> GroupConfig | None:
+        for group in self.groups:
+            if group.name == name:
+                return group
+        return None
+
+    def all_repos(self) -> list[tuple[RepoConfig, GroupConfig]]:
+        result = []
+        for group in self.groups:
+            for repo in group.repos:
+                result.append((repo, group))
+        return result

gitmux/output.py

@@ -0,0 +1,31 @@
+"""Output formatting for serial and parallel execution."""
+
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+# Use ASCII-safe symbols on Windows with non-UTF-8 encoding
+_OK = "[green]OK[/]" if sys.platform == "win32" else "[green]✓[/]"
+_FAIL = "[red]FAIL[/]" if sys.platform == "win32" else "[red]✗[/]"
+
+
+def print_step(repo_name: str, step: str) -> None:
+    console.print(f"  [bold cyan]{repo_name}[/] -> [dim]{step}[/]")
+
+
+def print_success(repo_name: str, output: str = "") -> None:
+    console.print(f"  [bold cyan]{repo_name}[/] {_OK}")
+    if output:
+        for line in output.splitlines():
+            console.print(f"    [dim]{line}[/]")
+
+
+def print_error(repo_name: str, error: str) -> None:
+    console.print(f"  [bold cyan]{repo_name}[/] {_FAIL} {error}")
+
+
+def print_header(title: str) -> None:
+    console.print(Panel(f"[bold]{title}[/]", expand=False))

gitmux-0.1.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: gitmux
+Version: 0.1.0
+Summary: Manage multiple git repositories with ease
+Project-URL: Homepage, https://github.com/ryan/gitmux
+Project-URL: Repository, https://github.com/ryan/gitmux
+Project-URL: Issues, https://github.com/ryan/gitmux/issues
+Author: Ryan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,devtools,git,multi-repo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.4
+Requires-Dist: typer>=0.15.4
+Provides-Extra: dev
+Requires-Dist: pytest-mock==3.14.0; extra == 'dev'
+Requires-Dist: pytest==8.3.4; extra == 'dev'
+Requires-Dist: ruff==0.11.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gitmux
+
+Manage multiple git repositories with ease. Clone, pull, push, and run commands across repos with a single command.
+
+## Features
+
+- **YAML configuration** — declarative repo management
+- **Group management** — organize repos into groups
+- **Batch git operations** — clone/pull/push across repos
+- **Pre/post hooks** — run commands before/after git operations (e.g., `npm install` after pull)
+- **Template system** — share hook configs across similar repos
+- **Parallel execution** — speed up operations with `--parallel` flag
+- **Status overview** — see all repos' git status at a glance
+- **Arbitrary command execution** — run any shell command across repos
+
+## Install
+
+```bash
+pip install gitmux
+```
+
+## Quick Start
+
+```bash
+# Initialize config in current directory
+gitmux init
+
+# Add repos (default group if --group omitted)
+gitmux add git@github.com:user/api-server.git --group backend
+gitmux add git@github.com:user/auth-service.git --group backend
+
+# Clone all repos
+gitmux clone --all
+
+# Pull a single repo
+gitmux pull backend/api-server
+
+# Pull entire group (parallel)
+gitmux pull --group backend --parallel
+
+# Check status of all repos
+gitmux status
+
+# Run command on a specific repo
+gitmux exec "git checkout main" --target backend/api-server
+```
+
+## Configuration
+
+Config file lookup order (used for both reading and writing):
+1. `--config / -c` flag (explicit path)
+2. `.gitmux.yaml` in current directory
+3. `~/.gitmux.yaml` (global fallback)
+
+```yaml
+workspace: ~/projects
+
+templates:
+  node-app:
+    post_pull:
+      - npm install
+    pre_push:
+      - npm test
+
+groups:
+  backend:
+    repos:
+      - name: api-server
+        url: git@github.com:user/api-server.git
+        template: node-app
+      - name: auth-service
+        url: git@github.com:user/auth-service.git
+        path: ~/custom/path/auth  # override default path
+        hooks:
+          post_pull:
+            - pip install -r requirements.txt
+  frontend:
+    repos:
+      - name: web-app
+        url: git@github.com:user/web-app.git
+        template: node-app
+```
+
+### Path Resolution
+
+- Default: `{workspace}/{group}/{repo_name}`
+- Override per-repo with the `path` field
+
+### Branch Management
+
+Configure named branch aliases per repo:
+
+```yaml
+repos:
+  - name: map
+    url: https://code.example.com/base/map.git
+    branches:
+      prod: "bInfinite-plan-*"    # pattern (contains *)
+      dev: "bInfinite-dev-main"   # fixed branch name
+```
+
+Usage:
+
+```bash
+gitmux pull map --branch dev           # checkout fixed branch → pull
+gitmux pull map --branch prod:latest   # fetch → find newest matching branch → checkout → pull
+gitmux pull map --branch prod:260515   # replace * → checkout bInfinite-plan-260515 → pull
+gitmux pull --group base --branch dev  # checkout fixed branch for all repos in group
+```
+
+Rules:
+- `--branch <alias>` — alias must be a fixed branch (no `*`), otherwise error
+- `--branch <alias>:latest` — alias must be a pattern (has `*`), picks newest by commit date
+- `--branch <alias>:<value>` — alias must be a pattern, replaces `*` with `<value>`
+
+### Hook System
+
+Hooks run shell commands before/after git operations:
+
+- `pre_clone`, `post_clone`
+- `pre_pull`, `post_pull`
+- `pre_push`, `post_push`
+
+**Error handling:**
+- Pre-hook failure → git operation is skipped
+- Post-hook failure → repo marked as failed
+
+**Template merging:** Repo-level hooks override template hooks per hook type.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gitmux init` | Create `.gitmux.yaml` in current dir (`--global` for `~/.gitmux.yaml`) |
+| `gitmux add <url> --group <g>` | Add a repository (group auto-created) |
+| `gitmux remove <name>` | Remove a repository |
+| `gitmux list` | List all repositories |
+| `gitmux status [target]` | Show git status overview (defaults to all) |
+| `gitmux clone <target>` | Clone unclosed repositories |
+| `gitmux fetch <target>` | Fetch remote data (`--branches` to list branches) |
+| `gitmux pull <target>` | Pull latest changes |
+| `gitmux push <target>` | Push local commits |
+| `gitmux exec <cmd>` | Run command in repos (`--target` to specify) |
+| `gitmux group list` | List groups |
+| `gitmux group create <name>` | Create a group |
+| `gitmux group remove <name>` | Remove a group |
+
+### Target Syntax
+
+```bash
+gitmux pull map           # repo 'map' in default group
+gitmux pull base/map      # repo 'map' in group 'base'
+gitmux pull --group base  # all repos in group 'base'
+gitmux pull --all         # all repos (explicit)
+gitmux pull               # error: specify target, --group, or --all
+```
+
+Note: `gitmux add <url>` without `--group` places the repo in the `default` group.
+
+### Common Options
+
+- `--group, -g` — operate on entire group
+- `--all, -a` — operate on all repositories (required for write operations without target)
+- `--parallel, -p` — run in parallel (clone/fetch/pull/push/exec)
+- `--config, -c` — custom config file path
+
+## Development
+
+```bash
+git clone https://github.com/ryan/gitmux.git
+cd gitmux
+pip install -e ".[dev]"
+pytest
+```
+
+### Code Quality
+
+Uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .          # lint
+ruff check --fix .    # auto-fix
+ruff format .         # format
+```
+
+Rules: `E`, `F`, `W`, `I` (isort), `N`, `UP` (modern Python), `B` (bugbear), `SIM`.
+
+## License
+
+MIT

gitmux-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gitmux/__init__.py,sha256=olcNLhFCvmvqLi1yPEWL762ePJCSuJ8ACrVRUepRU1w,82
+gitmux/cli.py,sha256=qz2UY4rhLrNrGaTfBTZJRoAqyRQZYd7AbiCsKdACWmg,19629
+gitmux/config.py,sha256=IEArNglEGVyztRjXBiy8b_JH0rpNlh7OJqyPFGUnrAA,4177
+gitmux/executor.py,sha256=gtq74tizisgcACyCWBrKB73sk9Qrn8qVwVgT1kTwbDg,4286
+gitmux/git_ops.py,sha256=B5SJRHngFZSSPr7H8YWNh28ls-uXB7GSZT8ArSrICf8,3244
+gitmux/hooks.py,sha256=ME5HwpCyNEyuETsu9VxzlxLEL4zi6PZHSJ7bqPIJHDE,1935
+gitmux/models.py,sha256=ygDlHFalitnl5csdUcPJMqSqJvMGEYkPVJQdy7XPojw,1971
+gitmux/output.py,sha256=PAZh2rR7BU_QzOCfVJiKUBH0-nS0X_zgg2Y1J8r5Do8,920
+gitmux-0.1.0.dist-info/METADATA,sha256=NIdTOfNqQOIpOf7g2i1PNnjHS8BZUgdg0gPmr_VfLOc,6540
+gitmux-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gitmux-0.1.0.dist-info/entry_points.txt,sha256=fzr2NC5MI3Eki1X79tl-9BCijeqD6XL_Xf24b0-FXTw,42
+gitmux-0.1.0.dist-info/licenses/LICENSE,sha256=h8B4q52QowRPNZ5rVj1Oav6nqgYIl89PIWGGh7OFZ5Y,1061
+gitmux-0.1.0.dist-info/RECORD,,

gitmux-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gitmux-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitmux = gitmux.cli:app

gitmux-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan
+
+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.