GitFerry

gitferry

v0.4.2 已发布。 npm 包 · v0.4.2 发布说明和下载 · MCP Registry

适用于隔离网络仓库的便携式 Git 更改包。 在一台机器上，将尚未推送的提交、暂存/未暂存的更改和未跟踪文件打包成一个可共享文件——将其带过网络隔离区（通过 USB、安全文件传输、电子邮件或用网络摄像头扫描二维码）——在另一台机器上验证并应用到同一仓库。无需共享远程服务，无需网络，也无需同步。

machine A (has your changes)          machine B (same repo, no sync)
┌─────────────────────────┐           ┌─────────────────────────┐
│ $ gitferry pack         │  ──────▶  │ $ gitferry apply        │
│   → repo-main-a1b2c3d   │  USB /    │   ✓ checksums verified  │
│     .gitferry           │  scp /    │   ✓ same repo confirmed │
│                         │  email    │   ✓ 2 commits replayed  │
│  commits + worktree     │           │   ✓ staged/unstaged     │
│  + untracked, checksummed│          │     state restored      │
└─────────────────────────┘           └─────────────────────────┘

请参阅 SCENARIOS.md，了解适用的所有场景——隔离网络环境、客户现场工作、WIP 交接、离线审查等。请参阅 INSTALL.md，了解如何在其他设备上离线安装。

快速安装 MCP（Claude Code）：运行 claude mcp add --transport stdio gitferry -- npx --yes [email protected] gitferry-mcp，然后重启客户端，并确认出现 pack_changes、inspect_bundle 和 apply_bundle 工具。Codex、VS Code、JSON 配置和离线设置请参阅下文的 MCP 服务。

为什么不直接用 git format-patch / git bundle？

可以——gitferry 底层使用了它们。原生 Git 无法提供的功能包括：

• 未跟踪文件也会一并传输（遵循 .gitignore）——git diff 永远无法看到这些文件
• 保留暂存与未暂存状态——另一端的索引状态与原来一致
• 在仓库受影响之前进行验证：校验每个文件的 sha256 和、检查同一仓库指纹（根提交）、检查基准提交、检查工作区是否干净
• 两端各用一个命令，而不是执行一系列 format-patch/diff/am/apply 操作
• 安全处理二进制文件（跟踪文件使用 --binary 补丁，未跟踪文件使用原始字节）
• 纯 Git 后备方案：包是标准 Git 补丁的 zip 文件——使用 --portable 打包后，只装有 Git 和 unzip 的机器也能手动应用（每个包内都附有说明；默认的精简格式需要先用 Node 的单行命令解包）

安装

需要 Node.js 22 或更高版本和 Git 2.32 或更高版本。从 npm 安装已发布的 CLI 和 MCP 服务：

npm install -g [email protected]
gitferry --version

如果仅使用 MCP，可跳过全局安装，改用 MCP 服务中的固定版本 npx 配置。

安装与注册 MCP 是两个独立步骤。 安装 npm 包后，便可在终端使用 gitferry 和 gitferry-mcp。注册服务则是告诉 Codex、Claude Code 或其他 MCP 客户端如何启动它。使用 npx 时，客户端会在首次启动时下载固定版本的软件包，因此无需全局安装。阅读本 README 或仅安装软件包，并不会注册服务。

封闭环境（无 npm）

从公开的 v0.4.2 发布页面下载 gitferry.cjs、gitferry-mcp.cjs 和 SHA256SUMS。这些独立文件包含其 JavaScript 依赖项；将它们传输到装有 Node 和 Git 的离线机器上。校验和验证及设置说明，请参阅 INSTALL.md。

从源码检出构建相同的独立可执行文件：

npm run bundle                 # → dist/gitferry.cjs + dist/gitferry-mcp.cjs
node dist/gitferry.cjs pack    # runs without any install or node_modules

用法

在有更改的机器上

gitferry pack                          # asks what should travel (Enter = uncommitted); base = merge-base with upstream
gitferry pack --only staged            # skip the question: all | uncommitted | staged | unstaged | committed | repo
gitferry pack --only repo              # whole-repo snapshot: every tracked file as-is — seed/sync another machine
gitferry pack --base origin/main       # explicit base
gitferry pack -o changes.gitferry --no-untracked

交互式选择器只会在终端中出现；在脚本中（无 TTY），pack 会打包所有内容，除非使用 --only 或 --no-* 标志指定其他选项。选择项含义：all = 提交 + 已暂存 + 未暂存 + 未跟踪 · uncommitted = 除提交以外的所有内容 · staged = 仅索引中的编辑 · unstaged = 工作树中的编辑 + 未跟踪文件 · committed = 仅尚未推送的提交 · repo = 磁盘上所有跟踪文件的快照（无历史记录）——应用时会为裸目录填充内容，或同步现有检出；跳过相同文件，只有使用 --force 时才会修改有差异的文件。

在接收机器上

gitferry inspect changes.gitferry      # verify + preview, touches nothing
gitferry apply changes.gitferry --dry-run
gitferry apply changes.gitferry

完全没有传输通道？用 QR 码传过去

如果连 USB 都无法使用，屏幕本身就是通道：一台机器将数据包循环显示为一系列 QR 码，另一台用任意摄像头读取。

# machine A (sender)
gitferry show changes.gitferry             # QR loop right in the terminal
gitferry show changes.gitferry --browser   # bigger + denser, in a local browser page
gitferry show changes.gitferry --color     # experimental: 3x density, 3 chunks per image in R/G/B

# machine B (receiver) — point its webcam at A's screen
gitferry read                              # opens a local camera page, reassembles the bundle
gitferry apply changes.gitferry

每个 QR 画面都包含分块编号 / 总数以及传输 ID，因此接收端确切知道还需要哪些分块——它会实时显示缺失的编号，并在循环重复时持续收集（顺序无关紧要；漏掉的画面会再次出现）。只有在所有编号的分块都已收到且整个文件的 sha256 校验值匹配后，才会写入文件，因此完成后的 read 就证明没有遗漏或损坏任何内容。两个页面都运行在 127.0.0.1 上，两台机器之间不会也无需使用网络。

将发送端的摄像头对准接收端，循环显示就会变得智能。 read 页面会显示一个小型的进度 QR 码（载荷很小、纠错能力很强，因此容易扫描）。如果运行 show --browser 的机器也有摄像头对着接收端的屏幕，那么每轮循环结束后，发送端只会重新显示仍然缺失的分块，并将速度从首轮速率（默认为 4 fps）降到较慢的重试速率（默认为 1 fps，--retry-fps），让剩余的分块更容易被捕获——一旦接收端的代码显示已完成，就会自动停止。发送端没有摄像头？那就和之前一样，始终以全速循环显示。

吞吐量大致为 chunk × fps：默认设置在终端中约为 0.3 KB/s，在浏览器中约为 0.6 KB/s，使用 --color 时约为 1.8 KB/s——适合补丁大小的数据包，不适合成堆的兆字节文件（pack --no-untracked 有助于缩小数据包）。默认采用有意设计的粗颗粒、易扫描代码（150 bytes ≈ QR 版本 8，49×49 个模块）：摄像头读取另一个屏幕时，遇到细小模块问题的速度远快于遇到画面数量过多的问题。如果摄像头和屏幕性能不错，可以提高 --chunk（最高 2900）。

应用

应用顺序：提交（git am -3，完整保留作者、日期和消息）→ 已暂存补丁（索引 + 工作树）→ 未暂存补丁（仅工作树）→ 未跟踪文件（除非指定 --force，否则不会覆盖现有文件）。

发生冲突时，你会看到标准的 git 冲突标记和清晰的说明（git am --continue / --abort，最后才使用 .rej 文件）——应用过程不是事务性的，因此继续之前请先查看错误和恢复说明。

标志

标志	命令	作用
--base <ref>	pack	数据包应用到的提交
--only <what>	pack	all / uncommitted / staged / unstaged / committed / repo — 非交互式选择
--no-commits / --no-worktree / --no-untracked	pack	缩减捕获的内容（可与 --only 组合）
--portable	pack	生成普通 ZIP 数据包（体积约大 30%），适用于只有 git + unzip 的目标环境
--dry-run	apply	验证并显示计划，不做任何更改
--force	apply	覆盖同一仓库、干净工作树和覆盖保护限制
-C <dir>	pack/apply	在其他目录中运行
--chunk <bytes> / --fps <n>	show	QR 载荷大小（默认 150 ≈ 版本 8 代码；提高可加快速度，降低则更容易扫描）和首轮显示速度
--retry-fps <n>	show	看到接收端的进度 QR 码后，重新循环显示缺失分块时使用的较慢速率（默认 1）
--browser / --color	show	浏览器页面显示；通过 R/G/B 通道实现实验性的 3× 密度
--no-open / --port <n>	show/read	不自动打开本地页面 / 固定其端口
-o <file> / --force	read	输出路径 / 覆盖现有文件

MCP 服务

GitFerry 在本地通过 stdio 运行。MCP 客户端会启动该进程，并与同一台计算机上的仓库交互。无需 GitFerry 帐户、API 密钥、托管服务或上传源代码。仅支持 URL 的 MCP 客户端需要单独的桥接程序，无法直接连接此本地服务。

使用适用于你客户端的 CLI 注册（分别需要 Codex CLI 或 Claude Code）：

# Codex
codex mcp add gitferry -- npx --yes [email protected] gitferry-mcp
codex mcp get gitferry

# Claude Code
claude mcp add --transport stdio gitferry -- npx --yes [email protected] gitferry-mcp
claude mcp get gitferry

选择客户端的注册命令，重新连接或启动新会话，然后确认 pack_changes、inspect_bundle 和 apply_bundle 均可用。mcp get 可确认已保存的配置；在已连接的客户端中发现工具，则可确认服务正在运行。请参阅 Codex 设置 了解 TOML 替代方案，并参阅由 Agent 协助安装以委托设置。

对于接受 mcpServers JSON 的客户端，请使用此配置来运行已发布的 0.4.2 软件包。显式指定可执行文件很重要，因为此软件包同时提供 CLI 和 MCP 服务：

{
  "mcpServers": {
    "gitferry": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "gitferry-mcp"]
    }
  }
}

对于源代码检出版本，请使用 npm ci && npm run bundle 构建，并使用：

{
  "mcpServers": {
    "gitferry": {
      "command": "node",
      "args": ["/absolute/path/to/gitferry/dist/gitferry-mcp.cjs"]
    }
  }
}

如果你全局安装了该软件包，服务命令为 gitferry-mcp。对于下载的离线软件包，请将 node 直接指向 /absolute/path/to/gitferry-mcp.cjs。请参阅客户端设置，了解 Codex、Claude Code 和 VS Code 示例及 Windows 启动说明。

工具	操作	关键参数
pack_changes	根据本地更改写入可移植软件包	cwd、可选的 output、base、only、portable 和包含标志
inspect_bundle	读取并验证软件包，但不更改仓库	bundlePath
apply_bundle	预览或将软件包应用到本地目标	cwd、bundlePath、dryRun、force、includeUntracked

请使用绝对路径。从这句提示开始：“将 /absolute/path/to/repo 中未提交的更改打包到 /absolute/path/to/transfer.gitferry。” 在接收机器上：“检查此软件包，然后对 /absolute/path/to/repo 执行试运行，并在应用前显示计划。”

only 接受 all、uncommitted、staged、unstaged、committed 或 repo。快照模式（repo）传递当前跟踪文件的内容，而非历史记录；它可用于初始化空目录。未指定选项时，默认包含所有更改类别，与非交互式 CLI 的行为一致。工具注解会向客户端描述副作用；它们不会强制要求批准，也不会限制文件系统访问。

请参阅 INSTALL.md 了解设置和离线传输，参阅 DEMO.md 了解两个仓库的演示流程，并参阅 PUBLISHING.md 了解维护者的发布步骤。已发布的注册表标识：io.github.mayank1307/gitferry。

由 Agent 协助安装

在可访问终端和配置的 Codex 或 Claude Code 中粘贴以下内容：

使用 https://github.com/mayank1307/gitferry/blob/main/INSTALL.md，在此客户端中将 GitFerry v0.4.2 设置为本地 stdio MCP 服务。检查 Node.js 22+ 和 Git 2.32+。检查是否已注册 GitFerry，保留其他服务，并为此客户端注册固定版本的 npx 命令。全局 npm 安装为可选项。验证已保存的配置，然后确认 pack_changes、inspect_bundle 和 apply_bundle 均可用。如果需要重启或新会话，请告知我该怎么做，并在之后验证工具发现情况。

在收到请求并获得所需访问权限后，Agent 可以执行设置。注册后，软件包会通过 npx 自动下载；客户端的批准和重新连接遵循客户端的常规行为。

Bundle 格式

.gitferry 文件是一个采用以下布局的 zip 文件——默认使用 brotli 封装（GFBR 魔数 + 存储型 zip 的 brotli 流，比 deflate zip 小约 30%；pack --portable 会写入普通 zip，而 inspect/apply 会自动检测两种格式）：

manifest.json            # versioned manifest: repo fingerprint, base/head shas,
                         # content listing, sha256 of every entry
commits/00NN-*.patch     # git format-patch output (mbox — author, date, message)
worktree/staged.patch    # git diff --binary --cached
worktree/unstaged.patch  # git diff --binary
untracked/<paths>        # verbatim file bytes
README.txt               # human instructions for manual apply with plain git

其中的所有内容都经过设计，可由标准 Git 直接使用；gitferry 增加了完整性检查和一条命令即可完成的体验，但绝不使用专有编码。对于只有 git + unzip 的目标环境，请使用 --portable 打包；默认的紧凑格式仍可由任何安装了 node 的机器解包（单行命令见 Bundle 自带的 README.txt）。

说明与限制

• 打包范围内的合并提交会被 format-patch 展平——打包时会发出警告；建议使用线性分支，或选择其他 --base
• 重放后的提交会获得新的 sha（内容和作者相同，提交者不同）——这是 git am 的正常行为
• 更改 Bundle 要求共享仓库历史（通过根提交指纹进行验证）；快照 Bundle 也可以用于初始化空目录。
• 应用机器需要 git ≥ 2.32

安全与信任

Bundle 中包含源代码、提交消息，以及可能存在的未跟踪机密信息。分享前请检查所选内容和目标位置。.gitignore 会排除被忽略的未跟踪文件，但不会移除已在 Git 中跟踪的机密信息。校验和可以检测损坏，但无法验证发送者的身份或可信度。仅应用来自可信来源的 Bundle。

服务拥有启动它的进程所具备的文件系统权限。仅在可信客户端中配置，并以普通用户身份运行。force 会绕过仓库、工作区脏状态和覆盖保护。关于强制实施的限制、符号链接行为和并发边界，请参阅 SECURITY.md。

开发

源代码布局请参阅仓库架构；本地、npm 和 Docker 配置请参阅 MCP 部署。可复制的客户端配置位于 examples/mcp。

npm ci
npm run build     # tsc → dist/
npm test          # vitest: round-trip e2e on real temp repos + guard tests
npm run bundle    # fresh single-file CLI + MCP server
npm run release:check  # versions, build, tests, and isolated package smoke test