Git Repo Sync 使用文档

Git Repo Sync 是一个基于 Bun + TypeScript 的 Git 仓库单向同步工具。它用于把多个源仓库的所有分支同步到对应的目标仓库，适合代码备份、跨平台镜像、内外网仓库同步、迁移过渡等场景。

当前版本支持手动立即同步、错过计划时间后的补同步、同步状态查看。daemon 常驻模式目前是预留命令，生产环境定时运行建议先使用 Windows 计划任务、Linux cron 或 CI/CD 调度。

功能说明

• 单向同步：只从 sourceRepo 同步到 targetRepo。
• 多仓库配置：一个配置文件中可以维护多组同步任务。
• 全分支同步：同步源仓库下所有 refs/heads/* 分支。
• 可选同步 tags：通过 syncTags 控制是否同步 refs/tags/*。
• 可选强制推送：通过 allowForcePush 控制是否覆盖目标仓库同名分支或 tag。
• 可选删除目标多余分支：通过 deleteMissingBranches 控制源仓库删除分支后是否同步删除目标仓库分支。
• 补同步：计划时间已过且当天未成功同步时，run-once 会自动执行一次。
• 状态与日志：每个仓库独立记录状态文件、日志文件和锁文件。

环境要求

请先确认本机已经安装：

• Git
• Bun
• 可访问源仓库和目标仓库的 Git 凭证，例如 SSH key、Git 凭证管理器或 CI/CD 注入的凭证

验证命令：

git --version
bun --version

安装依赖：

bun install

快速开始

1. 复制配置模板：

cp config/config.example.yaml config/config.local.yaml

Windows PowerShell 可以使用：

Copy-Item config/config.example.yaml config/config.local.yaml

2. 修改 config/config.local.yaml：

defaults:
  scheduleTime: "09:00"
  timezone: "Asia/Shanghai"
  syncAllBranches: true
  syncTags: true
  allowForcePush: false
  deleteMissingBranches: false
  syncOnMissedSchedule: true
  maxRetries: 3
  retryIntervalSeconds: 60
  gitCommandTimeoutSeconds: 1800
  runtimeDir: ./runtime

repositories:
  - id: my-project
    description: My project mirror
    sourceRepo: [email protected]:team/my-project.git
    targetRepo: [email protected]:team/my-project.git

3. 手动执行一次同步：

bun run src/cli/index.ts sync now --config config/config.local.yaml

也可以使用 package.json 中的脚本：

bun run sync sync now --config config/config.local.yaml

4. 查看同步状态：

bun run src/cli/index.ts status --config config/config.local.yaml

命令说明

立即同步

bun run src/cli/index.ts sync now --config config/config.local.yaml

行为：

• 逐个读取配置中的 repositories。
• 如果本地缓存仓库不存在，执行 git clone --mirror <sourceRepo> <cacheDir>。
• 如果缓存仓库已存在，更新 origin 地址并执行 git fetch --prune origin。
• 推送所有源分支到目标仓库。
• 如果 syncTags: true，推送所有 tags 到目标仓库。
• 如果 deleteMissingBranches: true，删除目标仓库中源仓库已不存在的分支。
• 每次运行会在 runtime/runs/ 下生成一份 sync-now-*.jsonl 汇总结果。

补同步检查

bun run src/cli/index.ts run-once --config config/config.local.yaml

行为：

• 读取每个仓库的状态文件。
• 如果当前时间已经到达或晚于 scheduleTime，且当天还没有成功完成计划同步，则执行同步。
• 同步成功后，更新 lastScheduledDateCompleted 为当天日期。
• 如果还没到计划时间，或当天已经完成计划同步，则跳过。

这个命令适合交给 Windows 计划任务、Linux cron 或 CI/CD 周期性调用。

查看状态

bun run src/cli/index.ts status --config config/config.local.yaml

输出每个仓库的状态 JSON，包含：

• lastSuccessfulSyncAt：最近一次成功同步时间。
• lastScheduledDateCompleted：最近一次完成计划同步的日期。
• lastResult：最近一次运行结果，可能是 success、failure 或 never。
• lastError：最近一次失败原因。
• branches：最近一次成功同步时，各分支对应的提交 hash。
• tags：最近一次成功同步时，各 tag 对应的 hash。

常驻模式

bun run src/cli/index.ts daemon --config config/config.local.yaml

当前版本会返回提示并退出：daemon mode is reserved for phase 2。请先使用 run-once 配合系统调度。

定时运行示例

Windows 计划任务

建议让计划任务每天在计划时间之后执行一次，例如配置里是 09:00，计划任务可以设置为 09:05。

程序：

bun

参数：

run src/cli/index.ts run-once --config config/config.local.yaml

起始目录：

D:\Coding_agent\git_repo_sync

如果希望更稳妥，也可以让计划任务每 30 分钟执行一次 run-once。工具会通过状态文件判断当天是否已经完成计划同步，避免重复补跑。

Linux cron

每天 09:05 执行：

5 9 * * * cd /path/to/git_repo_sync && bun run src/cli/index.ts run-once --config config/config.local.yaml

每 30 分钟检查一次：

*/30 * * * * cd /path/to/git_repo_sync && bun run src/cli/index.ts run-once --config config/config.local.yaml

运行数据目录

默认运行数据写入 ./runtime：

runtime/
  cache/   本地 mirror 缓存仓库
  state/   每个仓库的同步状态 JSON
  logs/    每个仓库的运行日志 JSONL
  locks/   防止同一仓库并发同步的锁文件
  runs/       sync now 的批量运行结果 JSONL

具体目录由配置文件中的 runtimeDir、cacheDir、stateFile、logFile、lockFile 决定。

凭证建议

不要把明文密码或 token 提交到配置文件中。

推荐方式：

• 使用 SSH 地址和部署专用 SSH key。
• 使用 Git Credential Manager。
• 在 CI/CD 或服务器环境中通过环境变量、密钥管理系统注入凭证。
• 如果必须使用 HTTP token，建议只写在本地未提交的 config/config.local.yaml 中，并确认 .gitignore 已忽略该文件。

工具运行 Git 命令时会设置 GIT_TERMINAL_PROMPT=0，因此凭证缺失时不会停下来等待交互输入，而是直接失败并记录错误。

常见问题

推送失败或提示 non-fast-forward

通常是目标仓库已有与源仓库不一致的历史。处理方式：

• 如果目标仓库只是镜像或备份，可以把该仓库配置为 allowForcePush: true。
• 如果目标仓库有人直接提交，不建议开启强推，需要先人工确认目标仓库差异。

目标仓库残留了源仓库已删除的分支

默认 deleteMissingBranches: false，工具不会删除目标仓库多余分支。若目标仓库需要严格保持与源仓库一致，可以配置：

deleteMissingBranches: true

开启前请确认目标仓库不是人工协作仓库。

不想同步 tags

在单个仓库配置中覆盖：

syncTags: false

run-once 没有执行同步

检查以下几点：

• 当前时间是否已经晚于 scheduleTime。
• timezone 是否配置正确。
• 状态文件中的 lastScheduledDateCompleted 是否已经是当天日期。
• syncOnMissedSchedule 是否为 true。

本地缓存损坏

如果某个仓库缓存损坏，可以停止任务后删除该仓库对应的 cacheDir，下一次同步会重新 git clone --mirror。

只删除确认属于本工具的缓存目录，避免误删其他仓库。

开发与测试

运行测试：

bun test

类型检查：

bun run typecheck

集成测试会创建本地临时 bare 仓库，并执行真实 Git 命令。