GitFerry

gitferry

v0.4.2 がリリースされました。 npm パッケージ · v0.4.2 のリリースとダウンロード · MCP Registry

ネットワークから隔離されたリポジトリ向けの、ポータブルな Git 変更バンドルです。 あるマシンで、未プッシュのコミット、ステージ済み／未ステージの変更、未追跡ファイルを、共有可能な1つのファイルにまとめます。ネットワークから隔離された環境を越えて（USB、安全なファイル転送、メール、またはウェブカメラを介したQRコードなどで）持ち運び、別のマシンにある同じリポジトリで検証して適用できます。共有リモート、ネットワーク、同期は不要です。

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

このツールが想定するすべての状況（ネットワークから隔離された環境、クライアント先での作業、WIP の引き継ぎ、オフラインレビューなど）については、SCENARIOS.md をご覧ください。他のデバイスへのオフラインインストールについては、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 チェックサム、同一リポジトリのフィンガープリント確認（ルートコミット）、ベースコミット確認、クリーンツリー確認
• それぞれ片道1コマンドで済みます。複数手順の format-patch／diff／am／apply を組み合わせる必要はありません
• バイナリに対応しています（追跡対象ファイルには --binary パッチ、未追跡ファイルにはバイト列をそのまま使用）
• 通常の Git による代替手段があります：バンドルは標準の Git パッチを格納した zip ファイルです。--portable を指定して作成すれば、Git と unzip だけがインストールされたマシンでも、手順に従って手動で適用できます（手順はすべてのバンドルに含まれています。デフォルトのコンパクト形式では、最初に展開するための Node.js のワンライナーが必要です）

インストール

Node.js 22 以降およびGit 2.32 以降が必要です。公開済みの CLI と MCP サーバーを npm からインストールします。

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.js と 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 なし）では、--only または --no-* フラグで指定しない限り、pack はすべてを対象にします。選択肢の意味は次のとおりです。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バイト ≈ 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	gitとunzipのみを使える環境向けの通常のZIPバンドル（約30％大きくなります）
--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 で保存済みの設定を確認でき、接続したクライアントでツールを検出できればサーバーが動作しています。TOML を使う方法についてはCodex のセットアップを、セットアップを任せる方法についてはエージェントによるインストールを参照してください。

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、および include フラグ
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、2 つのリポジトリを使った手順については DEMO.md、メンテナー向けのリリース手順については PUBLISHING.md を参照してください。公開レジストリでの識別子：io.github.mayank1307/gitferry。

エージェントによるインストール

ターミナルと設定にアクセスできる状態で、これを 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 が利用可能であることを確認してください。再起動または新しいセッションが必要な場合は、何をすべきかを伝え、その後にツールが検出できることを確認してください。

エージェントは、依頼されて必要なアクセス権を与えられれば、セットアップを実行できます。登録後、npx によってパッケージが自動的にダウンロードされます。クライアントの承認と再接続は、クライアントの通常の動作に従います。

バンドル形式

.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 を付けて pack してください。コンパクトなデフォルト形式も、node があればどのマシンでも展開できます（ワンライナーはバンドル内の README.txt に記載されています）。

注意事項と制限

• パック対象範囲内のマージコミットは format-patch によってフラット化されます。pack は警告を表示します。直線的なブランチを使うか、別の --base を指定してください。
• 再適用されたコミットには新しい sha が割り当てられます（内容と作成者は同じで、コミッターが変わります）。これは git am では通常の動作です。
• 変更バンドルにはリポジトリ履歴の共有が必要です（ルートコミットのフィンガープリントで検証されます）。スナップショットバンドルは空のディレクトリにも適用できます。
• 適用するマシンには git ≥ 2.32 が必要です。

安全性と信頼

バンドルにはソースコード、コミットメッセージ、場合によっては未追跡のシークレットが含まれます。共有する前に、選択内容と保存先を確認してください。.gitignore は無視対象の未追跡ファイルを除外しますが、Git ですでに追跡されているシークレットは削除しません。チェックサムは破損を検出しますが、送信者の身元や信頼性を検証するものではありません。信頼できるソースからのバンドルのみを適用してください。

サーバーは、起動したプロセスが持つファイルシステム権限で動作します。信頼できるクライアントでのみ設定し、通常のユーザーとして実行してください。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