git cloneの使い方｜ブランチ指定とshallow clone

git cloneとは、リモートにあるリポジトリを履歴ごと手元に複製し、すぐ作業できる状態（リモート設定・ブランチのチェックアウトまで済んだ状態）にするコマンドです。 基本は git clone <URL> の1行ですが、-b でブランチを指定したり、--depth 1 で履歴を浅く取ったり（shallow clone）、--filter で必要になるまで中身を取らない（partial clone）といった取り方を選べます。

この記事では、通常clone・--depth 1・--single-branch・--filter=blob:none・--filter=tree:0 を同じリポジトリに対して実行し、所要時間と .git のサイズを実測しました。さらに、shallow cloneのあとで「他のブランチが見えない」「git log が1件しか出ない」「pushが拒否される」という場面を再現し、git fetch --unshallow や git remote set-branches で元に戻すところまで、すべて実際の出力つきで紹介します。検証は git 2.43.0（Linux）で行い、オプションの仕様は公式ドキュメント（git-clone、今回開いた時点の表示は 2.54.0 更新版）で確認しています。

git cloneの早見表

まずは「やりたいこと」からコマンドを引ける表です。URLは自分のリポジトリに読み替えてください。

git cloneの基本の使い方

書式とURLの種類

git clone [オプション] <リポジトリURL> [作成先フォルダ]

作成先フォルダを省略すると、URLの末尾（.git を除いた名前）がフォルダ名になります。URLの書き方は主に次の3種類です。

cloneが内部でやっていること

git clone は、次の操作をまとめて行うコマンドです。「cloneしたのにブランチが1つしか無い」という疑問は、4番を知っておくと解けます。

通常のcloneでは、ローカルブランチは既定の1つ（多くは main）だけ作られ、ほかのブランチは origin/develop のようなリモート追跡ブランチとして存在します。git branch -a で確認でき、git switch develop と打てば追跡ブランチ付きのローカルブランチが自動で作られます。

$ git clone file:///srv/origin.git myapp
Cloning into 'myapp'...
$ cd myapp
$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/develop
  remotes/origin/feature/login
  remotes/origin/main

ブランチを指定してcloneする（-b）

-b <ブランチ名>（--branch）を付けると、clone直後にそのブランチがチェックアウトされます。-b だけでは取得量は減りません。 全ブランチを取ったうえで、最初に開くブランチを変えるオプションです。

# developを開いた状態でclone（全ブランチ・全履歴を取得）
git clone -b develop https://github.com/example/myapp.git

# developの最新1コミットだけ（取得量も最小）
git clone --depth 1 -b develop https://github.com/example/myapp.git

# developの全履歴だけ（ほかのブランチは取らない）
git clone --single-branch -b develop https://github.com/example/myapp.git

タグを指定した場合はdetached HEADになる

-b にはタグ名も渡せます。その場合はブランチではなくコミットを直接開いた状態（detached HEAD）になります。次は実行した出力です。

$ git clone -b v1.0 --depth 1 file:///srv/origin.git c_tag
Cloning into 'c_tag'...
Note: switching to 'afe87a515b9aeff90879280aa836f8cb9e7ad337'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
（以下略）
$ git -C c_tag status
Not currently on any branch.
nothing to commit, working tree clean

特定のリリース版をビルドするだけならこのままで問題ありません。そこから変更を積みたいときは git switch -c fix-from-v1.0 でブランチを作ってから作業します。

存在しないブランチ名を指定したとき

$ git clone -b nobranch file:///srv/origin.git c_e1
Cloning into 'c_e1'...
fatal: Remote branch nobranch not found in upstream origin

ブランチ名の打ち間違いが多い原因です。cloneの前に git ls-remote --heads <URL> を実行すると、リモートにあるブランチ名の一覧を取得せずに確認できます。

5つのclone方式を同じリポジトリで実測

検証に使ったリポジトリと条件

取り方による差を数字で見るために、検証用のリポジトリを用意して5方式（＋組み合わせ3つ）でcloneしました。

ネットワークを通していないので、秒数は「方式ごとの比率」を見るための値です。 実際の回線越しでは転送量の差がそのまま時間差として大きく出ます。サーバー側では partial clone を受け付けるために uploadpack.allowFilter=true を設定しています（GitHubなど主要なホスティングでは既定で使えます）。

実測結果の比較表

結果から読み取れること

• --depth 1 は通常cloneの約22分の1の時間、.git は約35分の1になりました。履歴を持たないぶん軽くなります。
• --single-branch だけではほとんど軽くなりませんでした（59MBのまま）。今回のリポジトリは develop と feature/login が main から分かれて数十コミットしか進んでおらず、履歴の大半を共有しているためです。ブランチごとに中身が大きく違うリポジトリでは差が出ます。
• --filter=blob:none は、400件の履歴をすべて持ったまま 2.0MB に収まりました。コミットとツリー（フォルダ構成）は全部取り、ファイルの中身（blob）は最新のチェックアウトに必要なものだけ取るためです。
• --filter=tree:0 はさらに小さく速い一方、あとで履歴を調べる操作に時間がかかります（次の項で実測）。
• --sparse を組み合わせると 464KB まで小さくなりました。最上位フォルダ直下のファイルだけを展開するため、チェックアウトに必要なblobも減るからです。

bloblessとtreelessは「あとで調べるとき」に差が出る

partial cloneは、足りないオブジェクトを必要になった時点でサーバーから取りに行きます。同じ「特定ファイルの履歴を見る」操作を2つの方式で比べました。

# どちらも clone 直後に実行
git log --oneline -5 -- docs/note1.md

treelessは「cloneは最速、履歴調査は遅い」という性質です。ビルドして捨てるCIジョブには向き、手元で git log -- <パス> や git blame を使う開発用にはbloblessが向いています。

どの方式を選ぶかの判断表

shallow clone（--depth）の仕組みと使い方

shallow cloneは、指定した深さより前の履歴を持たないcloneです。--depth 1 なら各ブランチ先端の1コミットだけを取得します。公式ドキュメントにあるとおり、--depth を付けると --single-branch も自動で付きます（--no-single-branch を指定しない限り）。この「1ブランチだけになる」動作が、あとで紹介する「ブランチが見えない」の理由です。

shallowかどうかは次のコマンドで確認できます。

$ git rev-parse --is-shallow-repository
true
$ cat .git/shallow
aa5a3ed28de0c5344e1d4b909c38a8ced9ae893c

.git/shallow には「ここより前の履歴は持っていない」という境界のコミットIDが記録されています。

shallow clone後に困る場面を再現して直す

ここからは git clone --depth 1 <URL> で作ったリポジトリで、よく出会う3つの場面を再現します。

場面1：git logが1件しか出ない

$ git log --oneline
aa5a3ed commit 400

リモートには400件ありますが、手元には先端の1件だけです。git blame や git bisect、過去のタグとの比較もこの範囲でしか動きません。

直し方A：全履歴を取り直す（通常のリポジトリに戻す）

$ git fetch --unshallow
$ git rev-parse --is-shallow-repository
false
$ git rev-list --count HEAD
400

直し方B：必要なぶんだけ深くする

$ git fetch --deepen=10
$ git rev-list --count HEAD
11

--deepen=10 は「いまの深さからさらに10件」、--depth=50 は「先端から50件に揃える」という違いがあります。すでに完全なリポジトリで --unshallow を実行すると、次のメッセージが出て何も起きません。

$ git fetch --unshallow
fatal: --unshallow on a complete repository does not make sense

なお、今回の検証では --unshallow 後の .git が 103MB になり、通常clone（59MB）より大きくなりました。あとから取得したオブジェクトが別のパックに分かれて格納されるためで、git gc を実行すると整理されます。

場面2：ほかのブランチが見えない・切り替えられない

$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
$ git switch develop
fatal: invalid reference: develop

リモートには develop があるのに、手元には origin/develop がありません。原因は fetch の設定（refspec）が main だけになっていることです。

$ git config --get remote.origin.fetch
+refs/heads/main:refs/remotes/origin/main

通常cloneなら +refs/heads/*:refs/remotes/origin/*（全ブランチ）になる箇所です。この状態で git fetch origin develop を実行しても、取得結果は FETCH_HEAD に入るだけで origin/develop は作られません。

$ git fetch origin develop
From file:///srv/origin
 * branch            develop    -> FETCH_HEAD
$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

直し方：fetch対象を広げてから取り直す

# 全ブランチを対象にする
$ git remote set-branches origin '*'
$ git config --get remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*

# 浅いまま各ブランチの先端を取得
$ git fetch --depth 1
From file:///srv/origin
 * [new branch]      develop       -> origin/develop
 * [new branch]      feature/login -> origin/feature/login
 * [new tag]         v1.0          -> v1.0

$ git switch develop
Switched to a new branch 'develop'
branch 'develop' set up to track 'origin/develop'.

特定のブランチだけ追加したい場合は --add を使います。

$ git remote set-branches --add origin main
$ git config --get-all remote.origin.fetch
+refs/heads/develop:refs/remotes/origin/develop
+refs/heads/main:refs/remotes/origin/main
$ git fetch --depth 1 origin main
From file:///srv/origin
 * branch            main       -> FETCH_HEAD
 * [new branch]      main       -> origin/main

git remote set-branches は .git/config の remote.origin.fetch を書き換えるコマンドです。--single-branch でcloneしたリポジトリ（shallowでなくても）でも同じ手順で直せます。

場面3：別のリモートへpushすると拒否される

shallowなリポジトリでも、clone元へ新しいコミットをpushすることは通常どおりできます。困るのは、履歴を持っていない別のリモート（新しく作った空のリポジトリなど）へpushするときです。

$ git push ../newremote.git main
To ../newremote.git
 ! [remote rejected] main -> main (shallow update not allowed)
error: failed to push some refs to '../newremote.git'

受け取る側は、途中で切れた履歴を既定では受け付けません。リポジトリの引っ越しやミラー作成のときに出会いやすいエラーです。

直し方：先に履歴をそろえてからpushする

$ git fetch --unshallow
$ git push ../newremote.git main
To ../newremote.git
 * [new branch]      main -> main

リポジトリを丸ごと移すことが目的なら、最初から git clone --mirror <URL> で取得するのが確実です。

shallowで困ったときの対処まとめ

いずれも今回の検証で症状と解消を確認したものです。

partial clone（--filter）の使い方

partial cloneは、履歴（コミット）は持ったまま、中身の一部を「必要になったら取る」方式です。shallow cloneが「過去を切る」のに対し、partial cloneは「過去は残して中身を後回しにする」と考えると区別しやすくなります。

clone後の設定を見ると、リモートが「足りない分を約束してくれる相手（promisor）」として記録されています。

$ git config --get-regexp 'remote.origin.*'
remote.origin.url file:///srv/origin.git
remote.origin.fetch +refs/heads/*:refs/remotes/origin/*
remote.origin.promisor true
remote.origin.partialclonefilter blob:none

fetch対象が *（全ブランチ）である点に注目してください。bloblessならブランチの切り替えも git log も通常cloneと同じ感覚で使え、切り替え時に足りないblobだけが自動で取得されます。オフラインで過去のファイルを開く予定がある場合は、通常cloneを選ぶと安心です。

shallowとpartialの違い

sparse-checkoutで必要なフォルダだけ展開する

モノレポのように大きなリポジトリでは、作業ツリーに展開するフォルダも絞れます。--sparse を付けてcloneすると、最初は最上位フォルダ直下のファイルだけが展開されます。次は実行した出力です（検証用リポジトリは最上位にファイルが無いため、最初の ls は空です）。

$ git clone --filter=blob:none --sparse file:///srv/origin.git mono
$ cd mono
$ ls

$ git sparse-checkout set docs
$ ls
docs

$ git sparse-checkout add src/app
$ ls
docs
src

$ git sparse-checkout list
docs
src/app

disable を実行すると assets docs src の全フォルダが展開され、検証では .git が 548KB から 2.0MB に増えました。展開に必要なblobがその時点で取得されたためです。「filterで取得量を減らし、sparse-checkoutで展開量を減らす」という2段構えになっています。

認証情報の管理（HTTPSとSSH）

非公開リポジトリのcloneでは認証が必要です。この項のコマンドは外部サービスへの接続が必要なため、今回の検証環境では未実行です（一般に知られた手順として紹介します）。

URLにトークンを直接埋め込む書き方（https://<トークン>@...）は、.git/config やシェルの履歴に残ります。 資格情報ヘルパーに保存する方法にすると、URLには秘密の値が残りません。

# 資格情報ヘルパーの確認と設定
git config --global credential.helper            # いまの設定を表示
git config --global credential.helper manager    # Windows（Git Credential Manager）
git config --global credential.helper osxkeychain # macOS
git config --global credential.helper 'cache --timeout=3600'  # Linux：1時間メモリに保持

# clone後にHTTPSからSSHへ切り替える
git remote set-url origin git@github.com:example/myapp.git
git remote -v

SSH鍵の作り方と接続確認は別の記事で詳しく扱っているため、ここでは要点の表に留めます。

エラー別の対処早見表

「実行」欄が「再現」のものは今回の検証で実際に出力を確認したメッセージ、「未実行」のものは外部サービスやWindows環境が必要なため今回は動かしておらず、一般に知られたメッセージと対処を載せています。

Windows：Filename too long

Windowsでは、パスの長さに上限（260文字）があるため、深い階層を持つリポジトリでは展開が途中で止まることがあります。Git for Windows側の設定で長いパスを扱えるようにします。

# Git側で長いパスを有効にする
git config --global core.longpaths true

# すでにcloneが途中で止まったフォルダなら、設定後に作業ツリーを展開し直す
git restore --source=HEAD :/

あわせて、cloneする場所を C:\src\myapp のように浅くすると余裕ができます。OS側の「長いパスを有効にする」設定が必要な場合もあるため、管理者に確認するとスムーズです。

Windows：改行コード（CRLFとLF）の問題

Windowsでcloneした直後に「何も変更していないのに全ファイルが変更扱いになる」「シェルスクリプトが \r のせいで動かない」ときは、改行コードの自動変換が関係しています。

チーム全員の設定をそろえるには、個人の設定に頼らず .gitattributes をリポジトリに置く方法が確実です。

# .gitattributes
* text=auto eol=lf
*.bat text eol=crlf
*.png binary

# clone時だけ設定を上書きする（-c はそのcloneで作るリポジトリに設定を書き込む）
git clone -c core.autocrlf=input https://github.com/example/myapp.git

clone後に確認しておくと安心なコマンド

cloneが終わったら、次の4つを実行すると状態が一目でわかります。

git remote -v                          # 取得元URL（HTTPSかSSHか）
git branch -a                          # ローカル／リモート追跡ブランチ
git rev-parse --is-shallow-repository  # shallowなら true
git config --get remote.origin.fetch   # fetch対象（* なら全ブランチ）

よくある質問

Q. --depth 1 でcloneしたリポジトリで、そのまま開発を続けても大丈夫ですか？ A. コミットやclone元へのpushは通常どおり行えます。過去の履歴を調べる操作（git log、git blame、過去のタグとの比較）が取得した範囲に限られるため、開発用として長く使うなら git fetch --unshallow で全履歴を取っておくか、最初から --filter=blob:none でcloneすると快適です。

Q. -b でブランチを指定すれば、そのブランチだけ取得されますか？ A. -b だけでは全ブランチが取得されます。1ブランチに絞るには --single-branch を併用します。--depth を付けた場合は自動で --single-branch も付くため、結果として1ブランチだけになります。

Q. shallow cloneとpartial clone（--filter=blob:none）はどちらを選べばよいですか？ A. ビルドして捨てるCIのような使い捨ての用途には --depth 1、手元で履歴を見ながら開発する用途には --filter=blob:none が合います。今回の実測では、どちらも通常cloneの10分の1以下の時間で終わり、.git は2MB前後でした。

Q. cloneしたあとで、取得するブランチを追加できますか？ A. できます。git remote set-branches --add origin <ブランチ名> で対象に加えてから git fetch を実行します。全ブランチを対象に戻すなら git remote set-branches origin '*' です。

まとめ

• git clone <URL> は、init・remote追加・fetch・チェックアウトをまとめて行うコマンドで、ローカルブランチは既定の1つだけ作られる
• -b は「最初に開くブランチ」を決めるだけで、取得量を減らすには --single-branch や --depth を組み合わせる
• 実測では --depth 1 が0.50秒／1.7MB、--filter=blob:none が0.88秒／2.0MB（通常cloneは11.23秒／59MB）
• --depth は自動で --single-branch になるため、ほかのブランチは git remote set-branches origin '*' と git fetch で見えるようにする
• git fetch --unshallow で通常のリポジトリに戻せる。少しだけ深くするなら --deepen=<n>
• shallow update not allowed は、履歴をそろえてからpushすると解消する
• Windowsの Filename too long は core.longpaths、改行コードは .gitattributes でそろえる

株式会社RJCでは、git cloneの取り方やリポジトリの扱い方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。