gitmux 0.1.0__tar.gz

gitmux-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gitmux-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.pyc
+.venv/
+.idea

gitmux-0.1.0/DESIGN.md

@@ -0,0 +1,96 @@
+# gitmux - Design Document
+
+## Overview
+
+gitmux 是一个 Python CLI 工具，通过 YAML 配置文件管理多个 git 仓库，支持批量 git 操作、分组管理、前后置 hook、并行/串行执行模式。
+
+## Architecture
+
+```
+src/gitmux/
+├── cli.py          # Typer CLI 入口，子命令定义
+├── config.py       # YAML 配置加载/验证/保存
+├── models.py       # 数据模型（Repo, Group, Hook, Template）
+├── executor.py     # 命令执行引擎（串行/并行）
+├── git_ops.py      # Git 操作封装
+├── hooks.py        # Hook 执行逻辑
+└── output.py       # 输出格式化（Rich 表格、进度条）
+```
+
+## Configuration Format
+
+```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
+        hooks:
+          post_pull:
+            - pip install -r requirements.txt
+        branches:
+          prod: "auth-plan-*"
+          dev: "auth-dev-main"
+  frontend:
+    repos:
+      - name: web-app
+        url: git@github.com:user/web-app.git
+        template: node-app
+```
+
+## CLI Commands
+
+```
+gitmux init                          # 初始化配置文件
+gitmux add <url> --group=<group>     # 添加仓库
+gitmux remove <name>                 # 移除仓库
+gitmux list                          # 列出所有仓库
+gitmux status [--group=<group>]      # 状态总览
+gitmux clone [--group=<group>]       # 克隆未克隆的仓库
+gitmux fetch [--group=<group>] [--branches] [--parallel]
+gitmux pull [--group=<group>] [--branch=<alias|alias:latest|alias:value>] [--parallel]
+gitmux push [--group=<group>] [--parallel]
+gitmux exec <command> [--group=<group>] [--parallel]
+gitmux group list
+gitmux group create <name>
+gitmux group remove <name>
+```
+
+## Execution Flow
+
+1. 用户执行命令
+2. 查找配置文件：`--config` 指定 → 当前目录 `.gitmux.yaml` → `~/.gitmux.yaml`
+3. 加载配置，解析目标仓库列表（按 --group 过滤）
+3. 判断串行/并行模式
+4. 对每个仓库执行：pre-hook → git 操作 → post-hook
+5. 输出结果
+
+### Hook 错误处理
+- pre-hook 失败 → 中断该仓库的 git 操作
+- post-hook 失败 → 标记仓库失败
+
+### 输出模式
+- 串行：实时输出，显示当前仓库名和执行步骤
+- 并行：Rich 进度条，完成后汇总（成功/失败/详情）
+
+## Technical Stack
+- CLI: Typer
+- Terminal UI: Rich
+- Config: PyYAML
+- Parallelism: concurrent.futures.ThreadPoolExecutor
+- Git: subprocess
+- Testing: pytest
+- Build: hatchling

gitmux-0.1.0/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.

gitmux-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,190 @@
+# 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/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitmux"
+version = "0.1.0"
+description = "Manage multiple git repositories with ease"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Ryan" }]
+keywords = ["git", "multi-repo", "cli", "devtools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "typer>=0.15.4",
+    "rich>=13.9.4",
+    "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.4",
+    "pytest-mock==3.14.0",
+    "ruff==0.11.12",
+]
+
+[project.scripts]
+gitmux = "gitmux.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/ryan/gitmux"
+Repository = "https://github.com/ryan/gitmux"
+Issues = "https://github.com/ryan/gitmux/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitmux"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["gitmux"]

gitmux-0.1.0/src/gitmux/__init__.py

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