Git sparse-checkout（スパース・チェックアウト）とは？

Sparse-checkoutは巨大なリポジトリのうち、いま触る追跡済みファイルだけを作業ツリーへ展開する機能です。Gitを使う開発者、レビュー担当者、リポジトリ運用者は、コマンド名だけで判断せず、作業ツリー、ステージ、ローカル履歴、リモートのどこを変えるかを分けてください。最初に行うのは、変更中ファイルとignoredファイルを確認し、必要なローカルデータをリポジトリ外へ退避することです。本記事は2026年8月6日にGit 2.55.0の公式マニュアルを確認しています。

30秒要約

作業ツリーのファイルを減らす機能で、履歴や既取得オブジェクトを削除しない。
モノレポで担当範囲をディレクトリ単位に限定できるときに向く。
秘密情報を隠す機能ではない。
新規クローンの転送量も減らすならpartial cloneを組み合わせる。
通常状態へ戻すときは空き容量を確認してgit sparse-checkout disableを使う。

前提と状態確認

Gitの操作対象は、少なくとも次の四層に分けます。

層	何があるか	主な確認
作業ツリー	エディタで編集中のファイル、未追跡ファイル	`git status --short`、`git diff`
ステージ	次のコミットへ入れる候補	`git diff --cached`
ローカル履歴	現在のブランチ、HEAD、過去コミット	`git branch --show-current`、`git log --oneline --decorate -n 10`
リモート	追跡参照、fetch先、push先	`git remote -v`、`git branch -vv`

git --version
git status --short
git branch --show-current
git branch -vv
git remote -v
git log --oneline --decorate -n 10

共有先の最新状態を比較したい場合は、作業ツリーへ統合するpullより先にgit fetch --pruneを使います。fetchは通常、現在の作業ツリーを変更せず、リモート追跡参照を更新します。

向くケースと向かないケース

向くのは、Web、API、モバイル、共有パッケージが一つのモノレポにあり、普段の一タスクが触るディレクトリを限定できる場合です。エディタ検索、ファイル監視、担当範囲の見通しを改善できます。

向かないのは、小さなリポジトリ、全体リファクタリング、全ソースを読む生成・監査、秘密情報を見せたくない場面です。対象外のファイルもGit履歴には残り、git show等で参照できます。

似た機能との違い

症状	機能	主に変わるもの
作業フォルダが大きい	Sparse-checkout	作業ツリー
最初の取得が重い	Partial clone	初期取得オブジェクト
`status`が重い	Sparse index	インデックス表現
複数ブランチを同時に開きたい	Worktree	作業場所とHEAD

Cone modeではルートファイルや祖先ディレクトリ直下のファイルが残ります。指定したディレクトリ以外がすべて消えるわけではありません。範囲を増やすときはadd、狭めるときは残す完全な一覧をsetします。

判断表

状況	選ぶ操作	期待結果	影響・戻し方
担当範囲だけ表示	`sparse-checkout set`	作業ツリーを限定	`add`・`set`・`disable`
初回転送も限定	`clone --filter=blob:none --sparse`	blobを遅延取得	追加通信・オフライン制約
並行作業を分離	`worktree add`	ブランチごとの作業場所	clean確認後remove
全体作業	通常checkout	全ファイルを利用	Sparseを無理に維持しない

安全な手順

最小範囲で開始する

前提: 作業ツリーとignoredファイルを確認し、必要データを退避済み

git status --short
git status --short --ignored
git sparse-checkout set apps/web packages/ui
git sparse-checkout list

期待結果: 選択したディレクトリ中心の作業ツリーになる。

影響: 対象外の追跡済みファイルを通常展開しない。ignoredファイル削除の可能性がある。

戻し方: git sparse-checkout addで増やし、空き容量確認後disableで全体へ戻す。

新規クローンで開始する

前提: リモート対応と追加通信を確認済み

git clone --filter=blob:none --sparse <REPOSITORY_URL> product
cd product
git sparse-checkout set apps/web packages/ui

期待結果: 初期作業ツリーと初期blob転送を抑えられる。

影響: 必要なblobは後から取得される。

戻し方: 通常cloneを別に作るか、必要オブジェクトを取得する。

具体例

フロントエンド担当

apps/webと共有UI・型定義を一緒に選び、ルート設定、IDE補完、テストを確認します。

全体リファクタリング

通常checkoutへ戻し、全体検索・生成・テストを行う方が単純で安全です。

失敗時の復旧

必要なファイルが見えない

git sparse-checkout add <directory>で対象を増やします。

競合後に範囲外ファイルが残る

mergeまたはrebaseを終えてからgit sparse-checkout reapplyします。

通常checkoutへ戻せない

空き容量、未コミット変更、ignoredファイルを確認し、強制削除せずdisableします。

チーム運用上の注意

操作前後のブランチ名、対象コミット、実行コマンド、結果、担当者をPull Requestや作業記録へ残します。
共有済み履歴を変える操作は、個人のローカル整理と同じ基準で実行しません。保護ブランチ、レビュー、CI、リリース規則を優先します。
コマンド例のorigin、main、パスは例です。実際の追跡先はgit branch -vvとgit remote -vで確認します。
認証情報、トークン、秘密鍵、個人情報をコマンド、URL、コミットメッセージ、ログ例へ含めません。
破壊的操作を自動化する場合は、dry-run、対象限定、バックアップ、承認、停止条件、復元テストを先に設計します。

導入判断ではリポジトリ総容量ではなく、普段のタスクで触る範囲とビルド入力を確認します。
Sparse indexはSparse-checkoutの動作確認後に検証します。

更新履歴

2026-08-06: Git 2.55.0の公式マニュアルを確認し、Git sparse-checkout（スパース・チェックアウト）とは？の状態確認、安全手順、復旧条件を整理しました。

参考リンク

git-sparse-checkout - 用途、Cone mode、範囲変更
git-clone - --sparseと--filter
git-worktree - 複数作業場所
Git詳細ページ - Sparse-checkout、partial clone、worktreeの役割を確認する既存ページ
Gitクイックガイド - Sparse-checkoutの使いどころを短時間で確認する既存ページ