专业的 Git 分支同步工具，支持上游仓库同步、多分支管理和智能合并策略。
- 🔄 智能同步: 自动检测并同步上游、origin 和本地分支
- 🌿 多分支支持: 支持 dev、test、main 等多分支工作流
- 🛡️ 安全检查: 预检测冲突，避免意外的合并问题
- 🎯 交互式操作: 友好的用户界面和确认提示
- 📊 详细状态: 完整的 Git 状态报告和同步建议
- ⚡ 高性能: 优化的 Git 操作，减少不必要的网络请求
npm install -g @git-tools/sync-clinpm install --save-dev @git-tools/sync-cli# 同步 dev 分支（默认）
git-sync sync
# 同步指定分支
git-sync sync --branch=main
# 仅检查状态，不执行同步
git-sync sync --check-only
# 强制同步（跳过某些安全检查）
git-sync sync --force
# 自动暂存工作区更改
git-sync sync --stash# 显示详细 Git 状态
git-sync status
# 简短状态输出
git-sync status --short
# JSON 格式输出
git-sync status --json# 交互式配置向导
git-sync setup
# 直接配置上游仓库
git-sync setup --upstream=https://github.com/original/repo.git# 显示所有配置
git-sync config --list
# 获取配置值
git-sync config --get user.name
# 设置配置值
git-sync config --set user.name "Your Name"# 清理已合并的分支
git-sync clean --branches
# 清理 Git 缓存
git-sync clean --cache
# 预览清理操作
git-sync clean --dry-run### sync 命令参数
- `-b, --branch <branch>`: 目标分支 (默认: dev)
- `-c, --check-only`: 仅检查状态，不执行同步
- `-f, --force`: 强制执行，跳过某些检查
- `-s, --stash`: 自动暂存未提交的更改
- `--no-fetch`: 跳过 fetch 操作
- `--no-push`: 跳过 push 操作
- `--dry-run`: 模拟执行，显示将要执行的操作
### status 命令参数
- `-s, --short`: 简短输出
- `--json`: 以 JSON 格式输出
### setup 命令参数
- `--upstream <url>`: 上游仓库 URL
- `--interactive`: 交互式配置 (默认)
- `--reset`: 重置现有配置
## 🔧 在项目中使用
### package.json 脚本
```json
{
"scripts": {
"sync": "git-sync sync",
"sync:dev": "git-sync sync --branch=dev",
"sync:test": "git-sync sync --branch=test",
"sync:check": "git-sync sync --check-only",
"git:status": "git-sync status",
"git:setup": "git-sync setup"
}
}
```import { GitSyncCLI } from "@git-tools/sync-cli";
const syncTool = new GitSyncCLI({
branch: "dev",
force: false,
verbose: true,
});
// 执行同步
await syncTool.sync();
// 检查状态
await syncTool.status();
// 初始化配置
await syncTool.setup();- 环境检查: 验证 Git 仓库、工作区状态
- 获取更新: 从所有远程仓库获取最新更新
- 上游同步: 合并上游仓库的更新
- 分支同步: 同步当前分支与远程分支
- 多分支处理: 根据需要同步其他相关分支
- 推送更新: 将合并后的更改推送到远程
- dev 分支: 开发主分支，从上游同步，合并到 test
- test 分支: 测试分支，从 dev 合并更新
- main/master 分支: 生产分支，通常受保护
- Git 仓库完整性检查
- 工作区状态验证
- 分支存在性确认
- 远程仓库连通性测试
- 合并前冲突预测
- 冲突文件详细报告
- 安全合并策略选择
- 自动暂存工作区更改
- 合并失败时自动回滚
- 操作历史记录
git-sync status输出包含：
- Git 环境信息
- 仓库基本信息
- 工作区状态
- 分支同步状态
- 远程仓库配置
- 同步建议
git-sync status --json适用于自动化脚本和 CI/CD 集成。
name: Sync Branches
on:
schedule:
- cron: "0 9 * * 1-5" # 工作日每天 9:00
workflow_dispatch:
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: "18"
- name: Install git-sync-cli
run: npm install -g @git-tools/sync-cli
- name: Configure Git
run: |
git config --global user.name "GitHub Actions"
git config --global user.email "actions@github.com"
- name: Sync branches
run: git-sync sync --force --branch=devsync-branches:
stage: sync
script:
- npm install -g @git-tools/sync-cli
- git config --global user.name "GitLab CI"
- git config --global user.email "ci@example.com"
- git-sync setup --upstream=$UPSTREAM_REPO --non-interactive
- git-sync sync --force
only:
- schedules工具会读取标准的 Git 配置：
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global core.editor "code --wait"在项目根目录创建 .git-sync.config.js：
export default {
defaultBranch: "main",
protectedBranches: ["main", "master", "production"],
syncStrategy: "merge", // merge, rebase, squash
autoCleanup: true,
hooks: {
beforeSync: async (context) => {
console.log("开始同步...");
},
afterSync: async (context) => {
console.log("同步完成！");
},
},
};问题: fatal: not a git repository
解决: 确保在 Git 仓库目录中执行命令
问题: error: Your local changes would be overwritten
解决: 使用 --stash 参数或手动提交/暂存更改
问题: fatal: 'upstream' does not appear to be a git repository
解决: 运行 git-sync setup 配置上游仓库
# 开启调试输出
git-sync sync --debug
# 使用环境变量
DEBUG=git-sync:* git-sync sync# 详细输出
git-sync sync --verbose
# 静默模式
git-sync sync --quiet欢迎贡献代码！请查看 贡献指南。
# 克隆项目
git clone https://github.com/your-org/git-sync-cli.git
cd git-sync-cli
# 安装依赖
npm install
# 运行测试
npm test
# 构建项目
npm run build
# 本地开发
npm run devMIT License. 查看 LICENSE 文件了解详情。
查看 CHANGELOG.md 了解详细的版本更新信息。