GitFerry

gitferry

v0.4.2 is released. npm package · v0.4.2 release and downloads · MCP Registry

Portable git-change bundles for air-gapped repos. Pack your unpushed commits, staged/unstaged changes, and untracked files into a single shareable file on one machine — carry it across the air gap (USB, secure file transfer, email, or QR codes across a webcam) — validate and apply it to the same repo on another machine. No shared remote, no network, no sync required.

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 │ └─────────────────────────┘ └─────────────────────────┘

See SCENARIOS.md for every situation this is built for — air-gapped environments, client-site work, WIP handoffs, offline review, and more. See INSTALL.md for offline installation on other devices.

Quick MCP install (Claude Code): claude mcp add --transport stdio gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp, then restart your client and confirm the pack_changes, inspect_bundle, and apply_bundle tools appear. Codex, VS Code, JSON config, and offline setup are in MCP server below.

Why not just git format-patch / git bundle?

You can — gitferry *uses* them under the hood. What raw git doesn't give you:

• Untracked files travel too (respecting .gitignore) — git diff never sees them
• Staged vs unstaged state is preserved — your index looks the same on the other side
• Validation before anything touches the repo: sha256 checksums of every file, same-repository fingerprint check (root commits), base-commit check, clean-tree check
• One command each way instead of a multi-step format-patch/diff/am/apply choreography
• Binary-safe (--binary patches for tracked files, verbatim bytes for untracked)
• Plain-git fallback: the bundle is a zip of standard git patches — pack with --portable and a machine with only git + unzip applies it by hand (instructions are inside every bundle; the compact default needs node's one-liner to unwrap first)

Install

Requires Node.js 22 or newer and Git 2.32 or newer. Install the published CLI and MCP server from npm:

npm install -g gitferry@0.4.2

gitferry --version

For MCP-only use, skip the global install and use the pinned npx configuration in MCP server.

Installation and MCP registration are separate steps. Installing the npm package makes gitferry and gitferry-mcp available in your terminal. Registering the server tells Codex, Claude Code, or another MCP client how to launch it. With npx, the client downloads the pinned package on first launch, so a global install is optional. Reading this README or installing the package alone does not register the server.

Closed environments (no npm)

Download gitferry.cjs, gitferry-mcp.cjs, and SHA256SUMS from the public v0.4.2 release. These standalone files include their JavaScript dependencies; transfer them to the offline machine with Node and Git. See INSTALL.md for checksum verification and setup.

To build the same standalone executables from a source checkout:

npm run bundle                 # → dist/gitferry.cjs + dist/gitferry-mcp.cjs

node dist/gitferry.cjs pack # runs without any install or node_modules

Usage

On the machine with changes

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

The interactive picker only appears in a terminal; in scripts (no TTY) pack takes everything unless --only or --no-* flags say otherwise. Selections mean: all = commits + staged + unstaged + untracked · uncommitted = everything except commits · staged = index edits only · unstaged = worktree edits + untracked · committed = unpushed commits only · repo = a snapshot of every tracked file as it is on disk (no history) — apply seeds a bare directory or syncs an existing checkout, skipping identical files and touching drifted ones only with --force.

On the receiving machine

gitferry inspect changes.gitferry      # verify + preview, touches nothing

gitferry apply changes.gitferry --dry-run gitferry apply changes.gitferry

No transfer channel at all? Beam it over QR

When even USB is off the table, the screen itself is the channel: one machine plays the bundle as a looping sequence of QR codes, the other watches with any webcam.

# 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

Every QR frame carries its chunk number / total plus a transfer id, so the receiver knows exactly which pieces it still needs — it shows the missing numbers live and keeps collecting as the loop repeats (order doesn't matter; missed frames come around again). The file is only written once every numbered chunk arrived and the whole-file sha256 matches, so a completed read is proof nothing was skipped or corrupted. Both pages live on 127.0.0.1; no network between the machines is used or needed.

Point the sender's webcam back at the receiver and the loop gets smart. The read page displays a small progress QR of its own (tiny payload, high error correction, so it scans easily). If the show --browser machine also has a camera watching the receiver's screen, then after each loop the sender re-shows only the chunks that are still missing, dropping from the first-loop rate (default 4 fps) to a slower retry rate (default 1 fps, --retry-fps) so the stragglers are easy to catch — and stops automatically once the receiver's code says *complete*. No camera on the sender's side? Everything simply loops at full speed like before.

Throughput is roughly chunk × fps: defaults give ~0.3 KB/s in the terminal, ~0.6 KB/s in the browser, ~1.8 KB/s with --color — meant for patch-sized bundles, not megabyte piles (pack --no-untracked helps keep them small). The default is deliberately a coarse, easy-scan code (150 bytes ≈ QR version 8, 49×49 modules): webcams reading another screen fail on fine modules long before they fail on frame count. Raise --chunk (up to 2900) if your camera and screens are good.

Applying

Apply order: commits (git am -3, full author/date/message preserved) → staged patch (index + worktree) → unstaged patch (worktree only) → untracked files (never overwrites existing files unless --force).

On conflicts you get standard git conflict markers and clear instructions (git am --continue / --abort, .rej files as last resort) — application is not transactional, so review the error and recovery instructions before continuing.

Flags

MCP server

GitFerry runs locally over stdio. Your MCP client starts the process, and it works with repositories on that same machine. No GitFerry account, API key, hosted service, or source upload is required. URL-only MCP clients need a separate bridge and cannot connect directly to this local server.

Register with the CLI for your client (requires Codex CLI or Claude Code, respectively):

# Codex

codex mcp add gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp codex mcp get gitferry

Claude Code

claude mcp add --transport stdio gitferry -- npx --yes --package=gitferry@0.4.2 gitferry-mcp claude mcp get gitferry

Choose your client's registration command, reconnect or start a new session, and verify that pack_changes, inspect_bundle, and apply_bundle are available. mcp get confirms the saved configuration; tool discovery in the connected client confirms the server is working. See Codex setup for the TOML alternative and agent-assisted installation to delegate setup.

Use this configuration for the published 0.4.2 package in clients that accept mcpServers JSON. The explicit executable matters because this package supplies both a CLI and an MCP server:

{

"mcpServers": { "gitferry": { "command": "npx", "args": ["--yes", "--package=gitferry@0.4.2", "gitferry-mcp"] } } }

For a source checkout, build with npm ci && npm run bundle and use:

{

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

If you installed the package globally, the server command is gitferry-mcp. For a downloaded offline bundle, point node directly at /absolute/path/to/gitferry-mcp.cjs. See client setup for Codex, Claude Code, and VS Code examples and Windows launch instructions.

Use absolute paths. Start with: *“Pack the uncommitted changes in /absolute/path/to/repo into /absolute/path/to/transfer.gitferry.”* On the receiving machine: *“Inspect this bundle, then dry