こんにちは。現場の最前線でコードとインフラの狭間を走り続けているエンジニアです。
今日は、多くのチームが一度は直面する「Gitが重すぎて泣きたくなる問題」に終止符を打つ、Bitbucket LFS (Large File Storage) について深掘りしていきます。
「Gitに大容量ファイルを入れて、リポジトリが肥大化してクローンが終わらない……」
もし今そんな状況なら、この記事を読み終える頃には、あなたのワークフローは劇的に洗練されているはずです。
—
なぜGitに「巨大なファイル」を入れてはいけないのか？
Gitは本来、ソースコードのような「テキストファイル」の差分を管理するために設計されたツールです。画像、動画、コンパイル済みのバイナリ、データセットなどがリポジトリに入ると、Gitはそれら全ての履歴を保持しようとします。
結果として、`git clone` に数十分かかる、リポジトリサイズが数GBを超えてBitbucketのクォータ（上限）に抵触するといった地獄が待っています。
これを解決するのが Git LFS です。
LFSは、実データは別のストレージに置き、Gitリポジトリにはその「ポインタ（参照先のテキストファイル）」だけを保存することで、リポジトリの軽量化を実現します。
—
1. Git LFSの導入：最短ルート
まずは環境を整えましょう。各OSのパッケージマネージャでインストール可能です。
macOSの場合
brew install git-lfs
Ubuntu/Debianの場合
sudo apt-get install git-lfs
インストール後の初期化（これを忘れないでください）
git lfs install
これだけで、あなたのGit環境はLFSを使う準備が整いました。
—
2. 「HelloWorld」的な動作確認（追跡設定）
LFSを導入する最大のポイントは、「どのファイルをLFSで管理するか」を指定することです。
例えば、プロジェクトで `assets/` フォルダ内の `.psd` ファイルをLFSで管理したい場合、以下のコマンドを打ちます。
.psdファイルをLFSの追跡対象に追加
git lfs track “.psd”
.gitattributesという設定ファイルが生成されたことを確認
cat .gitattributes
出力結果: .psd filter=lfs diff=lfs merge=lfs -text
この `.gitattributes` ファイルは、「どのファイルをLFSとして扱うか」を定義する魔法の杖です。これ自体もGitで管理されるため、チームメンバー全員が同じルールで大容量ファイルを扱えるようになります。
あとは通常通りコミットするだけです。
git add .gitattributes
git add assets/logo.psd
git commit -m “feat: LFSで画像ファイルを管理”
git push origin main
これで、Bitbucket上ではポインタのみが管理され、実体はLFSストレージへと流れていきます。
—
3. 【現場の知見】既存リポジトリへの導入は慎重に
ここからがプロの領域です。既に巨大なファイルがコミット済みのリポジトリにLFSを導入する場合、単純な `git lfs track` だけでは過去の履歴に残った巨大ファイルは消えません。
履歴からファイルを削除し、LFSへ移行するには `git-lfs-migrate` を使うのが定石です。
履歴全体をスキャンして、過去の巨大ファイルをLFSに移行する
git lfs migrate import –include=”.psd” –everything
※注意：これはリポジトリの履歴を書き換えるため、チーム開発では全員に「一度クローンし直す」よう周知徹底してください。
—
4. 運用上の「やってはいけない」こと
LFSを使いこなすための、現場で痛い目を見ないための鉄則を伝授します。
1. `.gitattributes` を無視しない: このファイルをコミットし忘れると、他のメンバーの手元でLFSが正しく動作せず、巨大ファイルが直接Gitリポジトリに流れ込みます。
2. プッシュ漏れを確認: `git lfs push –all origin` で、ポインタだけでなく実データが正しくサーバに送られているか、不安な時はチェックしましょう。
3. ロック機構を活用する: 画像などのバイナリファイルはマージができません。Bitbucket/Git LFSには「ファイルロック機能」があります。
git lfs lock “assets/logo.psd”
これで「編集中」であることを明示し、意図しないコンフリクトを未然に防ぐことができます。
—
最後に：エンジニアとしてのステップアップ
LFSを導入することで、あなたのリポジトリは驚くほど軽快になり、CI/CDのパイプラインも高速化します。
「便利になったな」で終わらせず、「なぜこのファイルはGitで管理すべきか、それとも外に出すべきか」を常に意識してください。本当に巨大なアセットは、S3などのオブジェクトストレージに逃がし、GitにはそのURLを記したテキストだけを置く……という選択肢も、設計者としては常に持っておくべきです。
技術の本質を理解すれば、どんなツールもあなたの強力な武器になります。
さあ、快適な開発ライフを！