BundleWatcher

BundleWatcher 是一个跨平台 Git Bundle CLI，用于在联网电脑与无法访问远程仓库的电脑之间传递提交。

它通过 project key 识别项目，不依赖 remote URL；生成的文件是标准 Git .bundle，可使用 U 盘或其他方式传输。

环境要求

• Node.js 20+
• Git
• macOS、Linux 或 Windows

安装

从 npm 全局安装：

npm install --global bundle-watcher
bw --version

从源码安装：

npm install
npm run build
npm install --global .

配置文件

配置按电脑分别保存。文件名为 config.json，默认路径如下：

| 系统 | 路径 | | ------- | ---------------------------------------------------------------------------------------------- | | macOS | ~/Library/Application Support/BundleWatcher/config.json | | Windows | %APPDATA%\BundleWatcher\config.json | | Linux | $XDG_CONFIG_HOME/bundlewatcher/config.json，未设置时为 ~/.config/bundlewatcher/config.json |

也可以通过 BUNDLEWATCHER_HOME 指定配置目录：

BUNDLEWATCHER_HOME=/custom/path bw config path

此时配置文件为 /custom/path/config.json。使用 bw config path 可以查看实际路径；首次读取配置时会自动创建文件。

格式

{
  "version": 1,
  "outputDirectory": null,
  "removeExistingBundles": true,
  "scanPaths": [
    "/received/bundles"
  ],
  "repositories": [
    {
      "projectKey": "order-service",
      "displayName": "order-service",
      "repoPath": "/offline/order-service",
      "remote": "origin",
      "branchMap": {
        "master": "main"
      }
    }
  ]
}

字段说明：

• version：配置版本，当前为 1。
• outputDirectory：bw pack 和 bw fetch 的默认输出目录；不配置时使用当前目录。联网电脑通常设置为传输目录，例如 /transfer/bundles。
• removeExistingBundles：bw pack 生成 bundle 前是否删除输出目录中同一项目、同一分支的旧 bundle，默认 true；设置为 false 可保留旧 bundle。为保留 prerequisite 链，bw fetch 的增量 bundle 不会自动删除旧包。
• scanPaths：bw apply 扫描的目录，只扫描直接子文件，不递归扫描。
• repositories：本地仓库映射。
  • projectKey：项目标识，两台电脑必须一致。
  • repoPath：目标电脑上的本地 Git 仓库或空目录路径；空目录会在首次应用全量 bundle 时初始化。
  • remote：对应的本地 remote，默认是 origin。
  • branchMap：可选的来源分支到目标分支映射，未配置时使用同名分支。

也可以使用命令管理配置：

mkdir -p /offline/order-service
bw repo add /offline/order-service --project order-service
bw scan add /received/bundles
bw config output /transfer/bundles

最小使用示例

完成一次配置后，日常使用 bw fetch、bw pack 和 bw apply。

假设：

• 联网电脑仓库：/work/order-service
• 目标电脑仓库：/offline/order-service
• project key：order-service
• Bundle 传输目录：联网电脑 /transfer/bundles，目标电脑 /received/bundles

1. 联网电脑生成 Bundle

同步仓库中已有本地分支配置的全部 upstream，并生成用于更新 remote-tracking refs 的 Bundle：

bw fetch --repo /work/order-service --project order-service

如果需要传递联网电脑上的本地提交：

bw pack --repo /work/order-service --project order-service

生成的 .bundle 文件会保存到配置中的 outputDirectory。

2. 传输文件

将生成的 .bundle 文件复制到目标电脑的 /received/bundles。

3. 目标电脑应用 Bundle

bw apply

bw apply 会扫描配置中的目录，找到匹配项目并以 fast-forward 方式应用 Bundle。应用成功或安全跳过后，文件会被自动删除；损坏、分叉或无法匹配的文件会被保留。

目标映射也可以指向一个已存在的空目录。首次应用 bw pack --all 生成的全量 bundle 时，BundleWatcher 会使用 bundle 的目标分支初始化 Git 仓库、检出文件，并创建对应的 remote-tracking ref。增量 bundle 与 bw fetch bundle 不会初始化空目录；如果只有这些 bundle，需先传入并应用全量 bundle。

常用用法

bw fetch

获取仓库内已有本地分支所配置的全部 upstream，并将有变化的 remote-tracking refs 合并为一个 bundle。它不会合并、切换或修改本地分支。

bw fetch

执行时，bw fetch 会先快照各 upstream 当前已存在的 remote-tracking tip，再执行 git fetch，并把这些 fetch 前 tip 作为本次增量 bundle 的 prerequisite；不会在仓库中持久化 tip 状态。新配置的 upstream 会尝试复用本次 fetch 前其他 upstream tip 的共同祖先。目标电脑需要按顺序应用前序增量包，因此 bw fetch 会保留它们。若任一变化分支没有可靠的共同历史或发生非 fast-forward 改写，生成的单个 bundle 会包含完整历史；不过为保证安全，bw apply 对已经分叉的 remote-tracking ref 仍会拒绝自动覆盖。未配置完整 upstream 的本地分支，以及远程已不存在其 upstream 分支的配置，都会被忽略。所有 upstream 均无变化时不会生成 bundle。

bw pack

默认打包当前分支相对 remote-tracking 分支新增的本地提交，不修改工作区。

bw pack
bw pack --all  # 打包当前分支全部历史，并包含当前分支 upstream 的最新 remote-tracking 进度
bw pack -b     # 打包从 git checkout -b 创建当前分支后新增的提交

bw pack --all 可以用于创建空目录目标仓库所需的全量 bundle。

bw apply

扫描配置目录中的 .bundle，根据 projectKey 找到目标仓库并安全应用。可用 bw inspect <file.bundle> 查看单个 Bundle 的信息。

License

MIT