# mgit-cli

**Repository Path**: marco_projects/mgit-cli

## Basic Information

- **Project Name**: mgit-cli
- **Description**: 用户在开发中采用「单 Workspace 多项目」开发模式，同一工作空间下包含多个独立目录的前端、后端工程，每个工程均为独立 Git 仓库。当前需手动逐个切换仓库执行 Git 操作，效率低下，因此开发一款本地专用 CLI 工具，实现对这些 Git 仓库的统一、批量管理，适配日常开发工作流。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-05
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# git-multi-cli

一款用于多仓库 Git 管理的 CLI 工具，专为「单 Workspace 多项目」开发模式设计。

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## 功能特性

- **分支查询** - 快速查看所有仓库的当前分支
- **状态查询** - 一目了然查看各仓库工作区状态，支持显示文件清单
- **批量添加** - 批量添加文件到暂存区
- **批量切换** - 批量切换分支，支持创建新分支
- **批量提交** - 支持提交全部或仅 staged 文件，支持 Dry-run 预览
- **批量拉取** - 自动检测默认分支，避免硬编码 `master`
- **批量推送** - 一键推送多个仓库代码
- **操作回滚** - 快速撤销最近一次提交（soft reset，保留修改到暂存区）
- **并发控制** - 智能控制并发数，提高效率同时避免资源竞争
- **多层级配置** - 支持命令行参数覆盖

## 安装

### 全局安装（推荐）

```bash
npm install -g git-multi-cli
```

### 项目本地安装

```bash
npm install git-multi-cli
```

## 快速开始

### 1. 进入 Workspace 目录

```bash
cd your-workspace/
```

### 2. 使用 mgit 命令

```bash
# 全局安装后直接使用
mgit <command> [options]

# 或使用 npx
npx git-multi-cli <command> [options]
```

### 3. 常用命令示例

```bash
# 查看所有仓库分支
mgit branch

# 查看所有仓库状态
mgit status

# 批量添加文件
mgit add

# 批量提交代码
mgit commit -m "feat: 添加新功能"

# 批量拉取代码
mgit pull

# 批量推送代码
mgit push
```

运行 `mgit --help` 查看完整帮助信息。

## 命令行使用

### 基本用法

```bash
# 显示帮助
mgit --help

# 指定 Workspace 路径
mgit -w /path/to/workspace <command>

# 指定配置文件
mgit --config /path/to/config.json <command>

# 显示版本
mgit --version
```

### 子命令

#### `branch` - 查看仓库分支

查看所有仓库的当前分支：

```bash
# 查看所有仓库分支
mgit branch

# 指定工作空间
mgit branch -w /path/to/workspace

# 指定仓库
mgit branch -r repo1,repo2
```

#### `status` - 查看仓库状态

查看所有仓库的工作区状态：

```bash
# 查看所有仓库状态
mgit status

# 指定工作空间
mgit status -w /path/to/workspace

# 指定仓库
mgit status -r repo1,repo2
```

#### `add` - 批量添加文件

批量添加文件到暂存区：

```bash
# 添加所有修改文件
mgit add

# 添加指定文件
mgit add src/index.js src/utils.js

# Dry-run 预览
mgit add --dry-run

# 指定仓库
mgit add -r repo1,repo2

# 设置并发数
mgit add -c 3
```

#### `checkout` - 批量切换分支

批量切换多个仓库的分支：

```bash
# 切换到指定分支（分支必须已存在）
mgit checkout main

# 创建并切换到新分支
mgit checkout feature-branch -b

# Dry-run 预览
mgit checkout develop --dry-run

# 指定仓库
mgit checkout main -r repo1,repo2

# 设置并发数
mgit checkout main -c 3
```

选项：
- `-b, --create` - 如果分支不存在则创建新分支
- `-d, --dry-run` - 预览模式，不实际执行
- `-c, --concurrency <num>` - 设置并发数（默认 5）

#### `commit` - 批量提交代码

批量提交多个仓库的修改：

```bash
# 提交所有修改
mgit commit "feat: 添加新功能"

# 仅提交已暂存的文件
mgit commit "fix: 修复 bug" -s

# Dry-run 预览
mgit commit "docs: 更新文档" -d

# 指定仓库
mgit commit "refactor: 重构代码" -r repo1,repo2
```

选项：
- `-s, --staged` - 仅提交已暂存的文件
- `-d, --dry-run` - 预览模式，不实际执行

#### `pull` - 批量拉取代码

批量拉取多个仓库的代码：

```bash
# 拉取当前分支
mgit pull

# 拉取指定分支
mgit pull main

# Dry-run 预览
mgit pull -d

# 指定仓库
mgit pull -r repo1,repo2

# 设置并发数
mgit pull -c 3
```

选项：
- `-d, --dry-run` - 预览模式，不实际执行
- `-c, --concurrency` - 设置并发数（默认 5）

#### `push` - 批量推送代码

批量推送多个仓库的代码：

```bash
# 推送当前分支
mgit push

# 推送到指定分支
mgit push main

# Dry-run 预览
mgit push -d

# 指定仓库
mgit push -r repo1,repo2

# 设置并发数
mgit push -c 3
```

选项：
- `-d, --dry-run` - 预览模式，不实际执行
- `-c, --concurrency` - 设置并发数（默认 5）

#### `rollback` - 回滚最近提交

回滚最近一次批量提交：

```bash
# 回滚所有仓库的最近提交
mgit rollback

# Dry-run 预览
mgit rollback -d

# 指定仓库
mgit rollback -r repo1,repo2

# 设置并发数
mgit rollback -c 3
```

选项：
- `-d, --dry-run` - 预览模式，不实际执行
- `-c, --concurrency` - 设置并发数（默认 5）

⚠️ **注意**：回滚操作使用 `--soft` 模式，会保留修改到暂存区。

### 全局选项

| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--workspace` | `-w` | 指定 Workspace 路径 | `--workspace ./projects` |
| `--config` | - | 指定配置文件路径 | `--config ./.git-multirc` |
| `--depth` | - | 扫描深度（0=单层） | `--depth 1` |
| `--help` | `-h` | 显示帮助信息 | `--help` |
| `--version` | `-v` | 显示版本号 | `--version` |

## 配置说明

### 配置层级（优先级从高到低）

1. **命令行参数** - 如 `--workspace ./projects`
2. **项目本地配置** - `.git-multirc` 或 `.git-multirc.json`
3. **用户全局配置** - `~/.git-multi-cli/config.json`
4. **内置默认配置**

### 用户全局配置

配置文件路径：`~/.git-multi-cli/config.json`

```json
{
  "workspaceRoot": "/Users/xxx/workspace",
  "ignoreDirs": ["node_modules", "dist", "build", ".git"],
  "scanDepth": 0,
  "concurrency": {
    "query": 10,
    "modify": 3
  },
  "logColor": {
    "success": "green",
    "warning": "yellow",
    "error": "red",
    "info": "blue",
    "dryRun": "cyan"
  }
}
```

### 项目本地配置

在项目根目录创建 `.git-multirc` 或 `.git-multirc.json`：

```json
{
  "scanDepth": 1,
  "ignoreDirs": ["node_modules", "dist", ".cache"],
  "concurrency": {
    "query": 5,
    "modify": 2
  }
}
```

### 配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `workspaceRoot` | string | 自动识别 | Workspace 根目录路径 |
| `ignoreDirs` | string[] | `["node_modules", "dist", "build", ".git"]` | 扫描时忽略的目录 |
| `scanDepth` | number | `0` | 扫描深度（0=单层，N=递归N层） |
| `concurrency.query` | number | `10` | 查询类操作并发数 |
| `concurrency.modify` | number | `3` | 修改类操作并发数 |
| `logColor` | object | 见上文 | 日志颜色配置 |

## 功能详解

### 查看仓库分支

查看所有仓库或指定仓库的当前分支：

```bash
# 查看所有仓库分支
mgit branch

# 指定仓库
mgit branch -r repo1,repo2
```

输出示例：
```
┌─────────────┬──────────────┐
│ 仓库名称    │ 当前分支     │
├─────────────┼──────────────┤
│ frontend    │ main         │
│ backend     │ develop      │
│ docs        │ master       │
└─────────────┴──────────────┘
```

### 查看仓库状态

查看所有仓库的工作区状态，支持颜色区分：

```bash
# 查看所有仓库状态
mgit status

# 指定仓库
mgit status -r repo1,repo2
```

输出示例：
```
✅ frontend        - 干净
⚠️  backend         - 有未提交修改
   ├─ staged:    src/config.js
   └─ unstaged:  src/api.js
✅ docs            - 干净
```

### 批量提交代码

支持三种提交模式：

- **全部修改**（默认）- 提交所有更改（staged + unstaged）
- **仅 staged** - 只提交已暂存的文件
- **Dry-run 预览** - 预览将要提交的内容

```bash
# 提交所有修改
mgit commit -m "feat: 添加新功能"

# 仅提交已暂存的文件
mgit commit -m "fix: 修复 bug" -s

# Dry-run 预览
mgit commit -m "docs: 更新文档" -d

# 指定仓库
mgit commit -m "refactor: 重构代码" -r repo1,repo2
```

### 批量拉取代码

自动检测各仓库的默认分支，无需硬编码 `master`：

```bash
# 拉取当前分支
mgit pull

# 拉取指定分支
mgit pull main

# Dry-run 预览
mgit pull -d

# 指定仓库
mgit pull -r repo1,repo2
```

### 批量推送代码

一键推送多个仓库：

```bash
# 推送当前分支
mgit push

# 推送到指定分支
mgit push main

# Dry-run 预览
mgit push -d

# 指定仓库
mgit push -r repo1,repo2
```

### 回滚最近提交

撤销最近一次批量提交操作：

```bash
# 回滚所有仓库的最近提交
mgit rollback

# Dry-run 预览
mgit rollback -d

# 指定仓库
mgit rollback -r repo1,repo2
```

⚠️ **注意**：回滚操作会丢失回滚目标之后的所有修改，请谨慎使用！

## 项目目录结构

```
your-workspace/                 # Workspace 根目录
├── frontend/               # Git 仓库 1
├── backend/                # Git 仓库 2
├── docs/                   # Git 仓库 3
├── ...                     # 其他仓库
└── .git-multirc            # 项目本地配置（可选）

~/.git-multi-cli/               # 用户配置目录
├── config.json             # 用户全局配置
├── history.json            # 操作历史（最近10次）
└── error.log               # 错误日志（保留7天）
```

## 开发指南

### 环境要求

- Node.js >= 16.0.0
- npm >= 8.0.0

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/your-username/git-multi-cli.git
cd git-multi-cli

# 安装依赖
npm install

# 运行测试
npm test

# 本地调试
npm link
mgit
```

### 目录结构

```
git-multi-cli/
├── bin/
│   └── mgit.js             # CLI 入口
├── src/
│   ├── cli/
│   │   └── renderer.js     # 交互层
│   ├── core/
│   │   └── actionManager.js # 核心控制层
│   ├── service/
│   │   ├── repoScanner.js  # 仓库扫描
│   │   └── gitService.js   # Git 操作
│   └── adapter/
│       ├── index.js        # 适配层
│       └── configLoader.js # 配置加载
├── package.json
└── README.md
```

## 异常处理

### 典型异常提示

| 场景 | 提示信息 |
|------|----------|
| 未扫描到仓库 | ❌ 未扫描到任何 Git 仓库，请确认 Workspace 目录下存在 Git 工程。 |
| 分支不存在 | ⚠️ 仓库 [xxx] 拉取失败：分支 dev 不存在，请检查分支名称。 |
| 拉取冲突 | ⚠️ 仓库 [xxx] 拉取冲突，冲突文件：src/index.js，请手动解决冲突后重新拉取。 |
| 工作区干净 | ℹ️ 仓库 [xxx] 跳过提交：工作区无任何修改。 |
| 推送失败 | ⚠️ 仓库 [xxx] 推送失败：无权限推送到远程仓库，请检查 SSH 密钥配置。 |
| 回滚失败 | ⚠️ 仓库 [xxx] 回滚失败：commit hash 不存在，可能已被强制推送覆盖。 |

### 日志文件

错误日志保存在 `~/.git-multi-cli/error.log`，保留最近 7 天的记录。

## 常见问题

### Q: 工具支持哪些操作系统？

A: 支持 Windows、macOS、Linux 三大主流操作系统。

### Q: 如何忽略特定目录？

A: 在配置文件中的 `ignoreDirs` 数组中添加目录名，如 `["node_modules", "dist", ".idea"]`。

### Q: 默认分支检测失败怎么办？

A: 工具会自动回退使用常见默认分支名（main/master）。也可以在配置中指定 `defaultPullBranch`。

### Q: 单个仓库操作失败会影响其他仓库吗？

A: 不会。单个仓库失败仅记录异常，继续执行其他仓库操作，最后统一展示所有结果。

### Q: Dry-run 模式是什么？

A: Dry-run 模式用于预览将要执行的操作（如显示哪些文件会被提交），不会真正修改仓库状态。

### Q: 如何清除操作历史？

A: 直接删除 `~/.git-multi-cli/history.json` 文件即可。

## 技术栈

- [Node.js](https://nodejs.org/) - 运行环境
- [simple-git](https://www.npmjs.com/package/simple-git) - Git 操作封装
- [inquirer](https://www.npmjs.com/package/inquirer) - 交互式命令行
- [chalk](https://www.npmjs.com/package/chalk) - 彩色日志输出
- [p-limit](https://www.npmjs.com/package/p-limit) - 并发控制
- [commander](https://www.npmjs.com/package/commander) - CLI 参数解析

## 贡献指南

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 许可证

[MIT](LICENSE) © git-multi-cli