workferry

离线工作区变更摆渡工具 —— 把一份 Git 工作区的未提交变更（增、删、改、重命名、未跟踪文件与目录）打包成单个 tar.gz，带到另一台机器上原样应用。

解决什么问题

在无法联网、无法访问远程仓库（remote）的环境下，两台机器之间同步代码通常只能靠 U 盘、内网文件传输等手段。Git 内置命令并不覆盖这个场景：

| 内置命令 | 局限 | | ----------------------------- | ---------------------------------------------- | | git bundle | 只能打包已提交的历史，不含工作区未提交变更 | | git format-patch + git am | 提交级补丁，且要求双方有共同基线 | | git diff + git apply | 不处理未跟踪文件、二进制文件，删除语义弱 |

workferry 补上的正是这块空白：当前工作区的完整状态快照——包括还没 git add 的文件、未跟踪的目录、删除和重命名——都能被打包并原样还原。

特性

• 支持增、删、改、重命名、未跟踪文件与未跟踪目录（递归）
• 支持在仓库任意子目录中执行，自动以仓库根为基准收集与应用变更
• 基于 tar + manifest.json，包内容透明可检查
• apply 前先解压到临时目录，校验 manifest 与包内文件完整性，全部通过后才写入，不污染目标工作区
• 目标工作区不干净时拒绝执行，防止误覆盖
• 支持指定基线提交打包（--base），包含该提交本身的改动及其后到工作区的全部变更
• 构建产物为零依赖单文件，拷到任何有 Node.js 的机器即可运行

安装

npm i -g workferry

使用

打包变更（源机器）

workferry pack [输出.tar.gz]

收集当前工作区相对 HEAD 的全部变更并打包。默认输出 <目录名>-changes.tar.gz（在仓库子目录中执行时以仓库根目录名命名），文件落在执行时所在目录。

# 指定项目目录与输出文件
workferry pack --dir ~/project changes.tar.gz

# 以某个提交为起点，打包该提交（含）到当前工作区的全部变更（含未提交）
workferry pack --dir ~/project --base HEAD~3 changes.tar.gz

应用变更（目标机器）

workferry apply <输入.tar.gz>

在目标 Git 仓库目录（或其任意子目录）下执行，按 manifest 依次落地新增/修改文件、执行删除、完成重命名。

workferry apply --dir ~/project changes.tar.gz

apply 要求目标工作区干净（无未提交修改），请先提交或 stash。应用完成后运行 git status 检查并提交。

包内文件缺失（如包被有意裁剪）时 apply 默认整体拒绝；确认后可使用 --force 跳过缺失的变更，应用其余变更。

选项一览

| 选项 | 说明 | | ----------------- | --------------------------------------------- | | --dir <目录> | 指定项目目录，可为仓库内任意子目录（默认当前目录） | | --base <commit> | 仅 pack：指定基线提交，打包该提交（含）到当前工作区的全部变更（含未提交） | | --force | 仅 apply：包内文件缺失时跳过对应变更强制应用（默认整体拒绝） | | -h, --help | 显示帮助 | | -v, --version | 显示版本 |

工作原理

1. pack：通过 git status --porcelain -z（或 git diff --name-status -z）收集变更清单，把涉及的文件复制到临时目录、写入 manifest.json（记录每项操作类型与路径），最后打包为 tar.gz。
2. apply：先把包解压到临时目录，校验 manifest.json 并预检包内文件是否齐全（缺失则整体拒绝，不做任何写入），再把文件复制到目标工作区，最后按清单执行删除与重命名清理。临时目录随流程清理，不会在工作区留下 manifest.json。

局限性

• 依赖目标机器上的 git 与 tar 命令。
• 仅单向搬运（pack → apply），不是双向同步工具。