git sparse-checkoutで、一部のフォルダーだけを取り出す方法
git sparse-checkout set <フォルダー> を実行すると、作業フォルダーに出すファイルを、指定したフォルダーの中身と、そこまでの途中のフォルダー(いちばん上を含む)の直下にあるファイルだけに絞れます。モノレポ(複数のアプリを1つにまとめたリポジトリ)や大きなリポジトリで、自分が触るアプリのフォルダーだけを手元に置きたいときに使う方法です。消えたように見えるファイルも Git の管理からは外れず、git sparse-checkout disable でいつでも元に戻せます。検証環境でコマンドを実行し、操作の前と後の出力をそのまま載せています。
検証環境は Ubuntu 24.04、Git 2.43.0 です。作者の名前とメールアドレスには例示用の値(Neko <neko@example.com>)を設定し、コミットの日時は環境変数で決めています。取り出し元のリポジトリ(neko-monorepo)は同じ検証環境の中に置き、そこから clone しました。GitHub などのサーバーから clone したときの動き、Windows と macOS での動作、--no-cone(パターンで指定するやり方)と --sparse-index は試していません。
取り出す前のリポジトリ
neko-monorepo というリポジトリを用意しました。apps/ の下に web と api の2つのアプリがあり、ほかに docs/ と packages/ui/ があります。これをふつうに clone し、neko-work に移りました。8つのファイルがすべて作業フォルダーに出てきます。
$ git clone -q neko-monorepo neko-work
$ cd neko-work
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/api/server.js
./apps/web/index.html
./apps/web/src/app.js
./docs/guide.md
./package.json
./packages/ui/button.js
$ git ls-files | wc -l
8
find のコマンドは、.git フォルダーの中を除いて、作業フォルダーにあるファイルを一覧にするものです。
set で、取り出すフォルダーを決める
apps/web だけを取り出すように指定しました。
$ git sparse-checkout set apps/web
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/web/index.html
./apps/web/src/app.js
./package.json
apps/api/、docs/、packages/ui/ のファイルが作業フォルダーから消え、5つになりました。git sparse-checkout list で、今の指定を確かめられます。git status には、管理しているファイルのうち何割が作業フォルダーにあるかが出ます(8つのうち5つで 63%)。
$ git sparse-checkout list
apps/web
$ git status
On branch main
Your branch is up to date with 'origin/main'.
You are in a sparse checkout with 63% of tracked files present.
nothing to commit, working tree clean
指定していない README.md も残る理由
apps/web しか指定していないのに、いちばん上の README.md と package.json、それに apps/README.md も残っています。これは cone モード(Git 2.43 では標準のモード)の決まりです。git sparse-checkout の公式リファレンスによると、cone モードでは、指定したフォルダーの中身はすべて取り出し、その親にあたるフォルダー(ここでは apps/ といちばん上)からは、直下のファイルだけを取り出します。親フォルダーの中の別のフォルダー(apps/api/ など)は出てきません。
この指定は .git/info/sparse-checkout に書かれます。中を見ると、公式リファレンスの説明と同じ形のパターンになっていました。
$ cat .git/info/sparse-checkout
/*
!/*/
/apps/
!/apps/*/
/apps/web/
$ git config --worktree --get core.sparseCheckout
true
$ git config --worktree --get core.sparseCheckoutCone
true
set を実行すると、core.sparseCheckout と core.sparseCheckoutCone の設定も自動で入ります。公式リファレンスによると、以前の Git では init と set の両方を実行する必要がありました。今は init は非推奨(deprecated)とされていて、set だけで済みます。
消えたファイルも、Git の管理からは外れていない
作業フォルダーからは消えても、ファイルは Git の管理に残っています。git ls-files は8つのままで、-t を付けると、作業フォルダーに出していないファイルの頭に S が付きました。git ls-files の公式リファレンスによると、S は skip-worktree(作業フォルダーには出さない)のファイル、H はふつうの管理しているファイルです。
$ git ls-files | wc -l
8
$ git ls-files -t
H README.md
H apps/README.md
S apps/api/server.js
H apps/web/index.html
H apps/web/src/app.js
S docs/guide.md
H package.json
S packages/ui/button.js
$ git log --oneline -- apps/api
bb56d84 APIを更新
f26be41 最初のコミット
取り出していない apps/api の履歴も、git log でそのまま見られます。apps/web の中のファイルを変えて git commit -a でコミットしても、コミットに入ったのは変えた1つのファイルだけでした。作業フォルダーにない apps/api/server.js などが、削除として記録されることはありません。
$ printf "console.log(\"web v2\");\n" > apps/web/src/app.js
$ git commit -q -am "webを更新" && git log --oneline
00e62bc webを更新
bb56d84 APIを更新
f26be41 最初のコミット
$ git show --stat --format= HEAD
apps/web/src/app.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
add で、取り出すフォルダーを足す
set は指定をまるごと置き換えます。今の指定に足したいときは add を使います。docs を足しました。
$ git sparse-checkout add docs
$ git sparse-checkout list
apps/web
docs
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/web/index.html
./apps/web/src/app.js
./docs/guide.md
./package.json
外すフォルダーにコミットしていない変更があるとき
docs/guide.md を書き換えたまま、set apps/web で docs を外してみました。警告が出て、書き換えた docs/guide.md は、変更を残したまま作業フォルダーに残りました。
$ printf "# 使い方(書きかけ)\n" > docs/guide.md
$ git sparse-checkout set apps/web
warning: The following paths are not up to date and were left despite sparse patterns:
docs/guide.md
After fixing the above paths, you may want to run `git sparse-checkout reapply`.
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/web/index.html
./apps/web/src/app.js
./docs/guide.md
./package.json
$ git status --short
M docs/guide.md
警告のとおり、変更を片付けてから git sparse-checkout reapply を実行すると、指定に合わせて取り除かれます。ここでは git restore で変更を取り消しました。残したい変更なら、先にコミットします。
$ git restore docs/guide.md
$ git sparse-checkout reapply
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/web/index.html
./apps/web/src/app.js
./package.json
disable で、すべてのファイルに戻す
git sparse-checkout disable を実行すると、すべてのファイルが作業フォルダーに戻りました。途中でしたコミットも残っています。
$ git sparse-checkout disable
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/api/server.js
./apps/web/index.html
./apps/web/src/app.js
./docs/guide.md
./package.json
./packages/ui/button.js
$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
clone の時点から、一部のフォルダーだけを取り出す
ここまでの方法は、すでに全部のファイルを clone した後で、作業フォルダーを絞るものです。ダウンロードする量も減らしたいときは、git clone に --sparse と --filter=blob:none を付けます。git clone の公式リファレンスによると、--sparse は最初はいちばん上のファイルだけを作業フォルダーに出す指定です。--filter=blob:none は partial clone という機能で、ファイルの中身(blob)を、必要になるまでダウンロードしません。
neko-work から1つ上のフォルダーに戻って試しました。今回は取り出し元が同じ検証環境の中にあるので、--no-local も付けました。取り出し元のリポジトリには、partial clone を受け付ける設定(uploadpack.allowFilter)を入れています。--no-local を付けずに試すと、--filter は無視されるという警告が出て、中身がすべてコピーされました(手元にない中身の数が 0)。
$ cd ..
$ git clone -q --sparse --filter=blob:none neko-monorepo neko-local
warning: --filter is ignored in local clones; use file:// instead.
$ git -C neko-local rev-list --objects --all --missing=print | grep -c "^?"
0
git rev-list --objects --all --missing=print は、手元にない中身を、頭に ? を付けて一覧にします(公式リファレンスの –missing の説明)。--no-local を付けて clone し直した結果がこちらです。
$ git clone --sparse --filter=blob:none --no-local neko-monorepo neko-sparse
Cloning into 'neko-sparse'...
$ cd neko-sparse
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./package.json
$ git sparse-checkout list
$ git rev-list --objects --all --missing=print | grep -c "^?"
7
作業フォルダーには、いちばん上の README.md と package.json だけがあります。手元にない中身は7つで、2つのコミットに出てくる9つの中身のうち、この2ファイルの分を除いたものです(apps/api/server.js は2回のコミットで中身が違うため、2つと数えます)。続けて apps/web を取り出しました。
$ git sparse-checkout set apps/web
$ find . -path ./.git -prune -o -type f -print | sort
./README.md
./apps/README.md
./apps/web/index.html
./apps/web/src/app.js
./package.json
$ git log --oneline
bb56d84 APIを更新
f26be41 最初のコミット
set の時点で、apps/web に必要な中身だけが取り出し元からダウンロードされ、作業フォルダーに出てきました。コミットの履歴は最初からすべて手元にあります。まだ手元にない中身は4つになり、どのファイルのものかを git ls-tree で調べると、取り出していない apps/api/server.js(今と1つ前のコミットの2つ)、docs/guide.md、packages/ui/button.js でした。
$ git rev-list --objects --all --missing=print | grep "^?" | cut -c2- > ../missing.txt && wc -l < ../missing.txt
4
$ git ls-tree -r HEAD | grep -F -f ../missing.txt
100644 blob e70771516cc69da845adc3ccf5878d1fc2bdeaa6 apps/api/server.js
100644 blob d27cb3a6d0d0ee25c14e8c1e7f78e7c6abfb707b docs/guide.md
100644 blob a48c8a976478856e9c13acab69ecafd3fd45cfa3 packages/ui/button.js
$ git ls-tree -r HEAD~1 | grep -F -f ../missing.txt
100644 blob de863e8abe629cf9d93908fe63b69f662ebc8456 apps/api/server.js
100644 blob d27cb3a6d0d0ee25c14e8c1e7f78e7c6abfb707b docs/guide.md
100644 blob a48c8a976478856e9c13acab69ecafd3fd45cfa3 packages/ui/button.js
partial clone で clone したリポジトリは、手元にない中身が必要になったとき(この記事の set apps/web のように、取り出すフォルダーを増やしたときなど)に、取り出し元からダウンロードします。Git の partial clone の設計メモにも、取り出し元に接続できる状態である必要があると書かれています。オフラインで作業する予定があるときは、先に必要なフォルダーを取り出しておきます。




