# NFS を介して Git コミットをディレクトリ構造としてマウントする（2023 年） ## 개요 (概要) 本ガイドでは、NFS を通じてアクセス可能なディレクトリ構造として Git のコミット履歴をマウントする方法について説明します。これにより、レポジトリ全体をクローンせずにチーム内でコードを検索・確認することが可能になります。 --- ## 前提条件 - リポジトリのストレージに対して読み取り専用アクセス権を持つ Git サーバー環境 - 設定済みの NFS サーバー（Ubuntu/Debian などでは `nfs-kernel-server` など） - セキュアなアクセスのために SSH キーまたは認証方式を設定済みであること（必要に応じて） - マウント対象となるリポジトリがあるクライアント端末において、Git がインストールされていること --- ## ステップ 1：リポジトリ構造の設定 Git リポジトリが `/var/repositories/myrepo` に格納されていると仮定し、コミットログをフォルダとして公開するために専用ディレクトリを作成します。 ```bash mkdir -p /var/nfs/git-commits cd /var/nfs/git-commits git clone --bare /var/repositories/myrepo myrepo.git cd myrepo.git # すべてのコミットとオブジェクトに対してパックファイルを作成 git fsck --full # インTEGRITY（整合性）を確認します git repack -ad # リーズなオブジェクトをパックに集約します ``` コミット履歴をフォルダとして公開するには、コミットログを繰り返し処理します。 ```bash #!/bin/bash REPO_PATH="/var/nfs/git-commits/myrepo.git" cd "$REPO_PATH" # すべての到達可能なコミットを含む完全なコミットグラフをエクスポート git checkout --orphan temp-branch || true git read-tree -m -u HEAD 2>/dev/null || git reset --mixed HEAD for commit in $(git rev-list --reverse HEAD); do mkdir -p "${commit//\//_}" (cd "$REPO_PATH" && git show "$commit":. | tar xz) done ``` > **注**: より清潔で効率的なアプローチとしては、Git ハックまたはスクリプトを用いてコミットのツリー構造を自動化して生成する方法があります。あるいは、`.git/logs/refs/heads/master` を解析しコミットツリーを仮想的ファイルシステムに再構築する `git-dfs` などのツールや、Python スクリプトを採用するのも選択肢の一つです。 --- ## ステップ 2：NFS エクスポートの設定 `/etc/exports` ファイルを編集します： ```bash /volatile/git-commits *(rw,sync,no_root_squash) ``` 次に、変更を適用します： ```bash sudo exportfs -ra sudo systemctl restart nfs-kernel-server ``` ファイアウォールルールで NFS トラフィック（ポート 2049, TCP/UDP）が許可されていることを確認してください。 --- ## ステップ 3：クライアントでのレポジトリのマウント クライアント端末では、以下のように実行します： ```bash sudo mkdir /mnt/git-history sudo mount -t nfs <NFS_SERVER_IP>:/volatile/git-commits /mnt/git-history ``` 永続化のために `/etc/fstab` に追加します： ```bash <NFS_SERVER_IP>:/volatile/git-commits /mnt/git-history nfs defaults 0 0 ``` --- ## ステップ 4：アクセスと探索 マウント後、以下のように移動して確認できます： ```bash cd /mnt/git-history/myrepo ls commit-sha-123abc/ # コミットごとのディレクトリ cat commit-sha-123abc/file.txt ``` 必要に応じて標準の Git コマンドを用いて履歴を解釈します。 ```bash git log --oneline HEAD~5..HEAD # 直近のコミットを検証 git diff HEAD~1 HEAD # 最後にコミットした変更を表示 ``` --- ## トラブルシューティングヒント - **アクセス権限が拒否されました**: NFS エクスポート設定で適切な権限（`rw` および `ro`, ユーザーマッピングなど）を確保してください。 - **マウントに時間がかかります**: `noac`, `nolock` を使用し、NFS サーバーパラメータ（`/etc/nfs.conf`）のチューニングをお勧めします。 - **ファイルシステムの不一致**: バレレポジトリ上で定期的に `git fsck` を実行し、データの整合性を維持してください。 --- ## 代替ツール 高度な用途には専用ツールを検討してください： - [git-dfs](https://github.com/git-dfs) – Git 上の仮想的なファイルシステム - `git-archive-hooks` – シンプルで洗練されたコミットアーカイブワークフロー - `git-repo` API を活用した動的ツリー構造を構築するカスタム Python スクリプト --- ## 結論 NFS を介して Git コミットをフォルダとしてマウントすることで、分散チーム全体でのバージョン履歴のシームレスな閲覧が可能になります。通常の Git クローンの代わりではありませんが、大きなワーキングツリーを複製せずに軽量なスナップショットを共有し、特定の状態を検証する効率的な方法を提供します。 本番環境向けに展開する際には、パフォーマンス、スケーラビリティ、セキュリティのバランスを評価して導入を検討してください。

こんにちは！数日前、こんなことを考え始めました。「git リポジトリ全体をファイルシステムとして実装し、すべてのコミットをフォルダとして表現する FUSE ファイルシステムを作った人はいますか？」ということですが、答えは「はい！」でした。giblefs、GitMounter、そして Plan 9 向けの git9 など既存のプロジェクトが既に存在していました。しかし、macOS において FUSE を使うのは少し面倒です。カーネル拡張機能をインストールする必要があり、セキュリティ上の理由から macOS は近年ますますそのインストールを厳しく制限する傾向にあります。また、それらの既存プロジェクトとは異なるファイルシステムの構成方法についていくつかのアイデアも持っていました。

そこで、「FUSE の他にもmacOS でファイルをマウントする方法がないか」を実験することを面白いと思い、そのような機能を備えたプロジェクト

git-commit-folders

を構築しました。このツールは（少なくとも私の環境では）FUSE と NFS の両方に対応しており、WebDAV への実装も試作段階ではありますが動作しています。まだ実験的な段階であり、「実際に有益なソフトウェアなのか、それとも git の仕組みを考えるために楽しむための玩具なのか」については私も確信を持ってはいませんが、開発自体が楽しく、小さめのリポジトリでの自用も楽しかったので、ここまでに直面したいくつかの問題点について記述します。

目標：コミットをフォルダのように表現する

このプロジェクトを作成した主な理由は、git の内部的な仕組みについて直感的に理解できるよう提供帮助することでした。毕竟、git のコミットは本当にフォルダと似ています。すべての git コミットには、その時点でのファイル一覧が含まれており、そのディレクトリにはサブディレクトリも含まれることができます。ただし、git コミットは実際には「フォルダ」として実装されていません。これはディスク容量を節約するための工夫です。

git-commit-folders

では、すべてのコミットを実際にフォルダとして表現しています。したがって、過去のコミットを確認したい場合でも、従来の

git show

のようにコマンドを実行する必要はなく、単にファイルシステムの中を探索するだけで済みます。

例えば、私のブログリポジトリの最初のコミットを見ると、以下のような表示になります：

$ ls commits/8d/8dc0/8dc0cb0b4b0de3c6f40674198cb2bd44aeee9b86/
README

少しコミットが進んだ後では、以下のように表示されます：

$ ls /tmp/git-homepage/commits/c9/c94e/c94e6f531d02e658d96a3b6255bbf424367765e9/
_config.yml  config.rb  Rakefile  rubypants.rb  source

ブランチはシンボリックリンクである

git-commit-folders

がマウントするファイルシステム内では、コミットのみが「本物のフォルダ」であり、他のすべての要素（ブランチ、タグなど）はすべて特定のコミットへのシンボリックリンクです。これは git の内部構造を忠実に反映しています。

$ ls -l branches/
lr-xr-xr-x 59 bork bazil-fuse -> ../commits/ff/ff56/ff563b089f9d952cd21ac4d68d8f13c94183dcd8
lr-xr-xr-x 59 bork follow-symlink -> ../commits/7f/7f73/7f73779a8ff79a2a1e21553c6c9cd5d195f33030
lr-xr-xr-x 59 bork go-mod-branch -> ../commits/91/912d/912da3150d9cfa74523b42fae028bbb320b6804f
lr-xr-xr-x 59 bork mac-version -> ../commits/30/3008/30082dcd702b59435f71969cf453828f60753e67
lr-xr-xr-x 59 bork mac-version-debugging -> ../commits/18/18c0/18c0db074ec9b70cb7a28ad9d3f9850082129ce0
lr-xr-xr-x 59 bork main -> ../commits/04/043e/043e90debbeb0fc6b4e28cf8776e874aa5b6e673
$ ls -l tags/
lr-xr-xr-x - bork 31 Dec  1969 test-tag -> ../commits/16/16a3/16a3d776dc163aa8286fb89fde51183ed90c71d0

これは git の仕組みを完全に説明できるわけではありません（「コミットはフォルダのようなもの！」というアイデアだけで完結するわけではないのです）が、すべてのコミットがコードの古いバージョンを含む「フォルダ」であるという概念について、もう少し具体的に感じてもらえれば幸いです。

なぜこれが有用なのか？

実装に入る前に、git のコミットをすべてフォルダとして持ったファイルシステムがなぜ役立つのかについてお話したいと思います。私の多くのプロジェクト（

dnspeep

など）は結局使われないこともありますが、このプロジェクトを開発中は実際にそれなりに活用していました。

現時点で見つかった主な利点は以下の通りです：

• 削除した関数の検索

  grep someFunction branch_histories/main/*/commit.go

  のように実行することで、その関数の過去のバージョンを見つけることができます。
• 別のブランチにあるファイルの迅速な確認 1 行をコピーしたい場合などに、

  vim branches/other-branch/go.mod

  のように簡単に別のブランチ上のファイルを閲覧できます。
• すべてのブランチで特定の関数を検索

  grep someFunction branches/*/commit.go

  のように実行することで、すべてのブランチ内で特定の関数を探すことができます。

これらはいずれもコミットへのシンボリックリンクを通じて行われており、コミットを直接参照するわけではありません。もちろん、これらが最も効率的な方法であるとは限りません（

git show

や

git log -S

、あるいは

git grep

を使うと似たようなことを達成できます）が、私はいつもこれらのコマンドの構文を忘れてしまい、ファイルシステムをナビゲートするのは私にとってやりやすいと感じています。また、git worktree を使って複数のブランチを同時にチェックアウトすることもできますが、1 つのファイルをみるためにわざわざ全体として設定された worktree を用意するのは奇妙に感じます。

次からは開発中に直面したいくつかの問題点についてお話します。

問題 1: WebDAV と NFS のどちらを選ぶべきか？

macOS でネイティブサポートされているファイルシステムとしては、WebDAV と NFS の 2 つがありました。どちらの実装が容易か判断できないため、両方とも試しました。

当初は WebDAV が簡単そうに見え、実際には

golang.org/x/net

パッケージに WebDAV の実装があり、設定も比較的容易でした。しかし、その実装ではシンボリックリンクをサポートしていないことがわかりました（おそらく

io/fs

インターフェースを使用しており、現時点では

io/fs

ではシンボリックリンクに対応していないためと思われます）。ただ、この課題への対応は進行中だそうです。

そのため、私は WebDAV を見送って NFS の実装に集中することを決め、go-nfs (NFSv3 ライブラリ) を使用しました。また、macOS には FileProvider というものもあるという指摘もありましたが、それについては検討していませんでした。

問題 2: 複数の実装をどのように同期させるか？

私は FUSE、NFS、WebDAV の 3 つの異なるファイルシステムを実装しており、重複コードをどう避けるかについて明確ではありませんでした。友人の Dave は、「コアの実装を 1 つ書くとともに、それを NFS および WebDAV 変換するためのアダプター（例：

fuse2nfs

や

fuse2dav

）を書く」と提案しました。

実際のところでは、次の 3 つのファイルシステムインターフェースを実装する必要がありました：

• FUSE:

  fs.FS

• NFS:

  billy.Filesystem

• WebDAV:

  webdav.FileSystem

そこで、すべてのコアロジックを

fs.FS

インターフェースに配置し、以下の 2 つの変換関数を作成しました：

• func Fuse2Dav(fs fs.FS) webdav.FileSystem

• func Fuse2NFS(fs fs.FS) billy.Filesystem

いずれのファイルシステムも結構似ていたので、変換自体は難しくありませんでしたが、修正すべき面倒なバグが 100 万個もありました。

問題 3: すべてのコミットをリストしたくない

いくつかの git リポジトリには数千あるいは数百万のコミットが含まれています。これを解決する最初のアイデアは、

commits/

ディレクトリを「空っぽ」として見せるようにし、以下のような挙動を実現することでした：

$ ls commits/           # 出力なし（空）
$ ls commits/80210c25a86f75440110e4bc280e388b2c098fbd/
fuse  fuse2nfs  go.mod  go.sum  main.go  README.md

つまり、コミットを直接参照すればいつでも利用可能ですが、そのリスト自体は表示できないという仕組みです。これはファイルシステムとしては奇妙な挙動ですが、FUSE では問題なく動作します。ただ、NFS ではうまく動かすことができませんでした。おそらく、NFS にディレクトリが空である旨を伝えられた際、「つまり実際には完全に空だ」と解釈されてしまうためだと推測されます。

結局、以下の方法で対処しました：

• .git/objects

  のようにコミットのハッシュの最初の 2 文字で分類し、さらにその下にサブディレクトリ（2 レベル）を設定することで、例えば

  18d46e76d7c2eedd8577fae67e3f1d4db25018b0

  というハッシュを持つコミットを

  commits/18/18df/18d46e76d7c2eedd8577fae67e3f1d4db25018b0

  のように配置する。
• パッキングされたすべてのコミットのハッシュを最初に 1 度だけリストし、メモリ上にキャッシュし、その後でのみ loose オブジェクトを更新するという仕組みを採用した。これはリポジトリ内のほぼすべてのコミットがパック化されており、git がコミットを再パッキングすることをあまり頻繁に行わないという事実に基づいています。

この手法は Linux カーネル（約 100 万のコミット）においてうまく動作しています。私のマシンでは初回読み込みに约 1 分程度かかりますが、それ以降は高速な増分更新のみを行うことになります。各コミットのハッシュはわずか 20 バイトなので、100 万個のコミットをキャッシュしても 20MB しか必要なく、それほど大きな負担ではありません。より賢い方法として、コミット一覧を遅延読み込み（lazy loading）するように実装できる可能性もあります。git はパックファイルをコミット ID でソートするため、1b または 1b8c で始まるすべてのコミットを見つけるためにバイナリサーチを実行するのは比較的容易です。ただし、私が使用していた git ライブラリはこのためのサポートが十分ではありませんでした（「git リポジトリ内のすべてのコミットをリストする」という行為自体がとても奇妙であるため）。私はこれを数日かけて実装しようと試みましたが見つかるべきパフォーマンスを得られず、やむなく諦めました。

問題 4: 「ディレクトリではない」エラー

次のようなエラーが頻発しました：

"/tmp/mnt2/commits/59/59167d7d09fd7a1d64aa1d5be73bc484f6621894/": Not a directory (os error 20)

最初は非常に困惑しましたが、これはディレクトリをリストする際にエラーが発生し、NFS ライブラリがそのエラーを「Not a directory」というメッセージで扱っているだけであることを知りました。この問題は数多く発生し、毎回バグを追跡する必要がありました。

他にも奇妙なエラーが多数ありました。例えば

cd: system call interrupted

というエラーも経験しましたが、これは結局のところ自分のプログラム内の別のバグによるものでした。

やがて、Wireshark を使用して双方間でやり取りされるすべての NFS パケットを監視し、デバッグを楽にする方法を発見しました。

問題 5: インウント番号（inode number）

当初は意図せずにすべてのディレクトリの inode 番号を 0 に設定してしまいました。これは重大な問題でした。すべてのディレクトリの inode 番号が 0 であるディレクトリに対して

find

コマンドを実行すると、ファイルシステム上のループに関する警告を出し、処理を放棄してしまいます（これは当然のことです）。

これを修正するためには、

inode(string)

という関数を定義し、文字列からハッシュ値（インウンド番号）を生成する仕組みを作成しました。ここで使用される文字列は「ツリー ID」や「blob ID」となります。

問題 6: 有効期限切れのファイルハンドル（stale file handle）

このエラーが頻繁に発生しました：

Stale NFS file handle

問題は、不透明な 64 バイトの NFS「ファイルハンドル」から適切なディレクトリをマッピングできるようにするためでした。私が使用している NFS ライブラリの動作としては、各ファイルに対してファイルを生成し、固定サイズのキャッシュ内でそれらの参照情報を保持します。これは小規模なリポジトリでは問題ありませんが、ファイルが多すぎるとキャッシュが溢れ、結果として「有効期限切れのファイルハンドル」エラーが発生するようになります。

まだこの問題は残っており、どのように解決すればよいか明確ではありません。実際の NFS サーバーがこの問題に対してどのように対処しているかは理解しておりません（おそらく非常に大きなキャッシュを持っているのでしょうか）。NFS のファイルハンドルは 64 バイト（ビットではなくバイトです！）という大きさがあり、多くの場合でハンドラ全体にファイルパスをエンコードし、全くキャッシュしないというアプローチも考えられます。将来的にはこの実装を試してみるかもしれません。

問題 7: ブランチ履歴（branch_histories）

現時点では

branch_histories/

ディレクトリには各ブランチの最新の 100 コミットのみが表示されます。ここでの適切な対応策は未だ確立されていません。ブランチの完全な履歴を表示できるようにすることが望ましいです。もしかすると、

commits/

ディレクトリで採用したと同様のサブディレクトリのトリックを使用できるかもしれません。

問題 8: サブモジュール

git リポジトリには時折サブモジュールが含まれています。サブモジュールについては何も理解していないため、現在は無視しています。したがって、これはバグです。

問題 9: NFSv4 の方が優れているのか？

このプロジェクトは当初、利用可能な go ライブラリが NFSv3 に限定されていたため、NFSv3 で構築されました。開発完了後に buildbarn プロジェクトに NFSv4 サーバーの実装があることを知りました。これを採用した方がよいのでしょうか？ これが実際に問題かどうか、あるいは NFSv4 を採用するほど大きな優位性があるかは分かりません。また、buildbarn の NFS ライブラリを利用することに少し懸念もあります（他の開発者が利用することを想定しているのかどうか不透明なためです）。

以上です！

これ以外の問題点もきっと他にもありますが、現時点で思いつくのはこれくらいです。NFS における「有効期限切れのファイルハンドル」の問題や、「Linux カーネル上で起動するのに約 1 分かかる」という問題を修正するかどうかは分かりません！ filesystem に関することについて 100 万件ものことを教えてくれた友人 vasi に感謝します。