GitLabリポジトリのクローン方法：git cloneコマンドの使い方

By /

はい、承知いたしました。GitLabリポジトリのクローン方法であるgit cloneコマンドの使い方について、詳細な説明を含む約5000語の記事を作成します。

GitLabリポジトリのクローン方法：git cloneコマンドの徹底解説

はじめに：なぜリポジトリをクローンするのか？

ソフトウェア開発において、バージョン管理システムは不可欠なツールです。中でもGitは、分散型バージョン管理システムとして世界中で広く利用されています。Gitを使用することで、プロジェクトの履歴を記録し、変更を追跡し、複数人での共同作業を効率的に行うことができます。

そして、リモートリポジトリとしてGitLabのようなプラットフォームを利用することで、コードを安全にホストし、チーム内での共有、レビュー、そしてCI/CD（継続的インテグレーション・継続的デリバリー）といった開発プロセス全体の効率化を実現できます。

開発者がGitLab上のリポジトリで作業を開始する際、最初に行う操作の一つが「クローン（Clone）」です。クローンとは、リモートにあるGitリポジトリの内容（すべてのファイル、変更履歴、ブランチ情報など）を、自分のローカルコンピューターに完全にコピーすることです。この操作によって、リモートリポジトリの完全な複製がローカルに作成され、ユーザーはそこで自由にコードの編集、変更のコミット、新しいブランチの作成といった作業を行うことができるようになります。

この記事では、GitLabリポジトリをローカルに複製するための基本的なコマンドであるgit cloneに焦点を当て、その基本的な使い方から、様々なオプション、HTTPSとSSHという二つの主要な接続方法、そして非公開リポジトリへのアクセス方法に至るまで、詳細かつ網羅的に解説します。Git初心者の方でも理解できるよう、基本的な概念から順を追って説明しますので、ぜひ最後までお読みいただき、GitLabでの開発ワークフローをスムーズに進めるための一歩としてください。

GitとGitLabの基本理解

git cloneコマンドを理解するためには、まずGitとGitLabがそれぞれどのような役割を担っているのかを知っておく必要があります。

Git：分散型バージョン管理システム

Gitは、リーナス・トーバルズ氏によって開発された、分散型のバージョン管理システムです。分散型であることの最大の特徴は、リモートリポジトリだけでなく、各開発者のローカル環境にも完全なリポジトリの複製が存在する点です。

  • ローカルリポジトリ: 開発者のコンピューター上に存在する、プロジェクトの全ての変更履歴を含むリポジトリです。ここでファイル編集やコミットといった日常的な作業を行います。
  • リモートリポジトリ: ネットワーク上のどこか（例えばGitLabのサーバー）に存在するリポジトリです。チームメンバーはここを介してコードの共有や同期を行います。GitLabはこのリモートリポジトリを提供するプラットフォームの一つです。

Gitの基本的なワークフローは、以下のサイクルの繰り返しとなります。

  1. クローン (Clone): リモートリポジトリをローカルに複製する。
  2. 変更 (Modify): ローカルのファイルに変更を加える。
  3. ステージ (Stage): 変更したファイルをコミットの対象としてマークする (git add)。
  4. コミット (Commit): ステージした変更をローカルリポジトリに記録する (git commit)。
  5. プッシュ (Push): ローカルのコミットをリモートリポジトリに送信する (git push)。
  6. プル/フェッチ (Pull/Fetch): リモートリポジトリの変更をローカルに取り込む (git pull または git fetch と git merge)。

git cloneは、このサイクルの最初のステップであり、開発作業を開始するための入り口となるコマンドです。

GitLab：リモートリポジトリホスティングプラットフォーム

GitLabは、Gitリポジトリのホスティング機能を中心に、CI/CD、Issue Tracking、コードレビュー（マージリクエスト）、Wiki、Container Registryなど、ソフトウェア開発ライフサイクル全体をカバーする様々な機能を提供するWebベースのプラットフォームです。

GitLabを利用することで、チームは中央集権的にコードを管理し、以下のことを実現できます。

  • コードの共有とバックアップ: リモートリポジトリとしてコードを安全に保管し、チームメンバー間で共有できます。
  • 共同開発: マージリクエスト機能などを活用して、コードレビューを行いながら共同で開発を進められます。
  • 自動化: CI/CDパイプラインを構築し、コードのテストやデプロイを自動化できます。
  • プロジェクト管理: Issue Trackingやボード機能で開発タスクを管理できます。

GitLab上の各プロジェクトには、対応するGitリポジトリが存在します。開発者はこのリモートリポジトリを自分のローカル環境にクローンすることで、そのプロジェクトの開発に参加できるようになります。

git cloneコマンドとは何か？

git cloneコマンドは、リモートGitリポジトリの正確なコピーをローカルファイルシステム上に作成するためのコマンドです。このコマンドを実行すると、以下の処理が行われます。

  1. 指定されたリモートリポジトリに接続します。
  2. リモートリポジトリのすべての履歴（コミット、ブランチ、タグなど）を取得します。
  3. ローカルコンピューター上に新しいディレクトリを作成し、そのディレクトリ内に取得した履歴情報を元にした新しいGitリポジトリ（.git ディレクトリ）を初期化します。
  4. 取得した履歴の中から、リモートのデフォルトブランチ（通常はmainまたはmaster）の最新の状態をワーキングツリー（実際にファイルが展開される領域）にチェックアウトします。
  5. リモートリポジトリへの参照をローカルリポジトリに自動的に設定します。この参照は通常 origin という名前で登録され、今後の git push や git pull コマンドのデフォルトの接続先となります。

これにより、ローカル環境にリモートリポジトリの完全な複製が作成され、すぐに開発作業を開始できる状態になります。

GitLabでのリポジトリURL取得方法

git cloneコマンドを実行するには、クローンしたいGitLabリポジトリのURLが必要です。GitLabでは、プロジェクトのトップページから簡単にこのURLを取得できます。

  1. GitLabにログインする: WebブラウザでGitLabインスタンス（例: gitlab.com または独自のオンプレミスインスタンスのURL）にアクセスし、プロジェクトを含むグループまたは自分のユーザーアカウントにログインします。
  2. プロジェクトを選択する: クローンしたいリポジトリを含むプロジェクトのページに移動します。ナビゲーションメニューやダッシュボードから目的のプロジェクトを選択してください。
  3. クローンURLを探す: プロジェクトの概要（Overview）ページに移動すると、通常、ページの右上付近に「Clone」ボタンまたはセクションが表示されます。
  4. URLをコピーする: 「Clone」ボタンをクリックすると、通常、HTTPSとSSHの二種類のURLが表示されます。使用したい接続方法のURLの横にあるコピーボタン（クリップボードのアイコンなど）をクリックして、URLをコピーします。

例:
* HTTPS URL: https://gitlab.com/your-username/your-project.git
* SSH URL: [email protected]:your-username/your-project.git

これらのURLは、後のgit cloneコマンドで使用します。どちらの方法を選択するかは、後述するHTTPSとSSHそれぞれの特徴を理解した上で決定してください。

基本的なクローン方法: git clone <URL>

最も基本的なgit cloneコマンドの使い方は、取得したリポジトリURLを指定して実行するだけです。

bash
git clone <リポジトリURL>

実行例:

例えば、公開されているGitLab上のプロジェクト https://gitlab.com/gitlab-org/gitlab-runner.git をクローンする場合、ターミナルまたはコマンドプロンプトを開いて以下のコマンドを実行します。

bash
git clone https://gitlab.com/gitlab-org/gitlab-runner.git

またはSSHを使用する場合（公開リポジトリでもSSHは利用可能ですが、通常認証は不要です）。

bash
git clone [email protected]:gitlab-org/gitlab-runner.git

コマンド実行後の動作:

コマンドを実行すると、Gitは指定されたURLに接続し、リポジトリのデータをダウンロードします。ダウンロードが完了すると、デフォルトでリポジトリ名（例: gitlab-runner）と同じ名前の新しいディレクトリが、コマンドを実行したカレントディレクトリ内に作成されます。

.
└── gitlab-runner <-- 新しく作成されたディレクトリ
├── .git <-- ローカルGitリポジトリのすべての履歴情報を含む隠しディレクトリ
├── src <-- プロジェクトのソースコードなどのファイル
├── tests
└── ... (その他のプロジェクトファイルやディレクトリ)

この新しく作成されたディレクトリ（この例ではgitlab-runner）が、ローカルのワーキングツリーおよびローカルリポジトリのルートディレクトリとなります。クローン後、このディレクトリに移動して（cd gitlab-runner）、コードの編集やGitコマンドの実行を開始できます。

また、クローン時にリモートリポジトリへの参照が自動的に設定されます。これは git remote -v コマンドで確認できます。

bash
cd gitlab-runner
git remote -v

出力例:

origin https://gitlab.com/gitlab-org/gitlab-runner.git (fetch)
origin https://gitlab.com/gitlab-org/gitlab-runner.git (push)

またはSSHの場合:

origin [email protected]:gitlab-org/gitlab-runner.git (fetch)
origin [email protected]:gitlab-org/gitlab-runner.git (push)

ここで表示されているoriginは、クローン元のリモートリポジトリに対するデフォルトの名前です。fetchはリモートからデータを取り込む際のURL、pushはローカルの変更をリモートに送信する際のURLを示します。通常、これらは同じURLになります。

HTTPSでのクローンと認証

HTTPSは、Webブラウザでのアクセスと同様に、HTTPプロトコル上でSSL/TLSによって暗号化された接続を使用する方法です。GitLabリポジトリをHTTPSでクローンする場合、特に非公開リポジトリにアクセスする際には「認証」が必要になります。

HTTPS接続の仕組み

HTTPSでクローンする場合、Gitは指定されたURLに対してHTTPリクエストを送信します。GitLabサーバーは、リポジトリが公開されている場合はそのままデータを提供しますが、非公開リポジトリの場合はアクセス権を確認します。アクセス権がない場合や認証情報が不足している場合は、認証を要求します。

認証方法 (非公開リポジトリの場合)

HTTPSで非公開リポジトリをクローンまたはその後の操作（git pull, git pushなど）を行う場合、認証情報を提供する必要があります。一般的な認証方法としては以下の二つがあります。

  1. ユーザー名とパスワード: GitLabのアカウントのユーザー名とパスワードを入力する方法です。ただし、セキュリティ上の理由から、パスワードの直接利用は推奨されません。特に2要素認証（2FA）が有効な場合はパスワード認証は利用できません。
  2. パーソナルアクセストークン (Personal Access Token – PAT): GitLab上で生成できる、特定のアカウントに紐づいた認証用のトークンです。パスワードの代わりとして使用します。必要な権限（スコープ）を指定して生成でき、失効させたり再生成したりできるため、パスワードよりも安全です。APIアクセスやスクリプトからの利用にも適しています。

パーソナルアクセストークン (PAT) の生成手順 (GitLab UI)

  1. GitLabにログインします。
  2. 右上の自分のユーザーアイコンをクリックし、「Edit profile」を選択します。
  3. 左側のメニューから「Access Tokens」を選択します。
  4. 「Add new token」をクリックします。
  5. 以下の項目を設定します。
    • Token name: トークンの目的が分かる任意の名前を付けます（例: my-dev-machine-clone-token）。
    • Expiration date: トークンの有効期限を設定します。セキュリティのため、必要な期間だけ有効にするのが良いでしょう。
    • Scopes: トークンに許可する権限を選択します。リポジトリのクローンやプッシュには通常 read_repository と write_repository (または api で包括的に) スコープが必要です。
  6. 「Create personal access token」ボタンをクリックします。
  7. 生成されたトークンが表示されます。このトークンは一度しか表示されないため、安全な場所にコピーして保管してください。

PATを使った認証:

クローン時に認証を求められたら、ユーザー名としてGitLabのユーザー名を、パスワードとして生成したPATを入力します。

bash
git clone https://gitlab.com/your-username/your-private-project.git

実行後、以下のようにユーザー名とパスワードの入力を求められます。

Username for 'https://gitlab.com': your-username
Password for 'https://[email protected]': (ここにPATを貼り付け)

認証情報のキャッシュ (Credential Helper)

HTTPSでクローンやプッシュを行うたびに認証情報を入力するのは非常に手間がかかります。GitにはCredential Helperという仕組みがあり、認証情報をローカルにキャッシュしたり、安全に保管したりすることができます。

よく使われるCredential Helperの設定例：

  • メモリキャッシュ: 一定時間（デフォルト15分）だけメモリに認証情報を保持します。ターミナルを閉じたり、設定時間が経過すると失効します。
    bash
    git config --global credential.helper cache
    # キャッシュ時間を変更する場合 (例: 1時間)
    # git config --global credential.helper 'cache --timeout=3600'
  • Store (非推奨): 認証情報を暗号化せずにファイルに保存します。セキュリティリスクが高いため、公開されていない信頼できる環境以外では絶対に使用しないでください。
    bash
    git config --global credential.helper store

  • マネージャー/キーチェーン: OSの提供する安全な資格情報ストア（Windows Credential Manager, macOS Keychain）を利用します。最も推奨される方法です。
    “`bash
    # Windowsの場合
    git config –global credential.helper manager

    macOSの場合

    git config –global credential.helper osxkeychain
    “`

これらの設定を行うことで、一度認証に成功すれば、設定された期間や条件に従って再認証が不要になります。PATを使用する場合でも、Credential Helperと組み合わせることで入力の手間を省けます。

HTTPSの利点と欠点

  • 利点:
    • ファイアウォールを通過しやすい（Webアクセスと同じポートを使用するため）。
    • セットアップが比較的簡単（SSHキーペアの生成や登録が不要）。
    • プロキシ設定などを利用しやすい。
  • 欠点:
    • 非公開リポジトリの場合、認証情報の管理が必要（特にパスワード利用は非推奨）。
    • CI/CDなどで自動化する際に、PATの管理や設定が必要。
    • 大きなリポジトリや多数のファイルがある場合、SSHに比べて少し遅い場合があるという意見もありますが、実際の体感速度はネットワーク環境に依存します。

SSHでのクローンと認証

SSH (Secure Shell) は、安全なリモートログインやファイル転送のためのプロトコルです。GitでもSSHを使用してリモートリポジトリにアクセスできます。SSHを使用する場合、認証は通常、公開鍵認証の仕組みを利用して行われます。

SSH接続の仕組み (公開鍵認証)

SSHの公開鍵認証では、ユーザーはローカル環境でSSHキーペア（秘密鍵と公開鍵）を生成します。

  • 秘密鍵 (Private Key): ローカルコンピューターに安全に保管される、絶対に漏洩させてはならない鍵です。
  • 公開鍵 (Public Key): 秘密鍵とペアになる鍵で、公開しても安全です。GitLabのようなSSHサーバーに登録します。

ユーザーがSSHでGitLabに接続しようとすると、以下の認証プロセスが実行されます。

  1. クライアント（ローカルのGit）がGitLabサーバーに接続要求を送ります。
  2. GitLabサーバーは、クライアントに対して特定のチャレンジ（暗号化されたデータなど）を送り返します。
  3. クライアントは、自身の秘密鍵を使ってそのチャレンジを解読し、応答をサーバーに送り返します。
  4. GitLabサーバーは、クライアントから送られてきた応答を、そのユーザーアカウントに登録されている公開鍵を使って検証します。
  5. 検証に成功すれば（つまり、応答が登録されている公開鍵とペアになる秘密鍵によって生成されたものであると確認できれば）、認証成功となり、アクセスが許可されます。

この仕組みにより、パスワードをネットワーク上に送ることなく、安全に認証を行うことができます。

SSHキーペアの生成方法 (ssh-keygen)

まだSSHキーペアを持っていない場合は、ssh-keygenコマンドを使って生成します。

  1. ターミナルまたはコマンドプロンプトを開きます。
  2. 以下のコマンドを実行します。
    bash
    ssh-keygen -t ed25519 -C "[email protected]"

    • -t ed25519: 使用する暗号化アルゴリズムを指定します。ed25519は比較的新しく、安全で効率的なアルゴリズムとして推奨されています。古いシステムとの互換性が必要な場合はrsa (ssh-keygen -t rsa -b 4096 -C "[email protected]") を使用することもできます（-b 4096で鍵長を4096ビットにすることを推奨）。
    • -C "[email protected]": 生成される公開鍵のコメントとしてメールアドレスなどを埋め込みます。これは必須ではありませんが、どの鍵か識別するのに役立ちます。
  3. 鍵の保存場所を聞かれます。特に理由がなければデフォルトの場所（例: ~/.ssh/id_ed25519）で問題ありません。Enterキーを押します。
  4. パスフレーズの設定を求められます。パスフレーズは秘密鍵を保護するための追加のパスワードです。セキュリティのため、設定することを強く推奨します。パスフレーズを設定すると、秘密鍵を使用する際にそのパスフレーズの入力が必要になります。設定しない場合はEnterキーを二回押します（非推奨）。
  5. パスフレーズを再入力して確認します。
  6. 鍵ペアが生成されました。指定した場所に秘密鍵（例: id_ed25519）と公開鍵（例: id_ed25519.pub）が保存されます。

公開鍵のGitLabへの登録方法

生成した公開鍵（.pubファイルの方）の内容をGitLabに登録します。

  1. 生成した公開鍵ファイル（例: ~/.ssh/id_ed25519.pub）をテキストエディタなどで開きます。ファイルの内容は ssh-ed25519 AAAA... のような文字列で始まります。この文字列全体をコピーします。
    • 公開鍵ファイルの内容は、以下のコマンドでも表示できます。
      bash
      cat ~/.ssh/id_ed25519.pub
  2. GitLabにログインします。
  3. 右上の自分のユーザーアイコンをクリックし、「Edit profile」を選択します。
  4. 左側のメニューから「SSH Keys」を選択します。
  5. 「Add an SSH key」ボタンをクリックします。
  6. 以下の項目を設定します。
    • Key: コピーした公開鍵の内容を貼り付けます。
    • Title: この鍵の目的が分かる任意のタイトルを付けます（例: My Laptop SSH Key）。
    • Expires at: 鍵の有効期限を設定します。セキュリティのため、必要に応じて有効期限を設定することを推奨します。
  7. 「Add key」ボタンをクリックします。

これで公開鍵の登録は完了です。この公開鍵に対応する秘密鍵を持つコンピューターから、SSH経由でGitLabリポジトリにアクセスできるようになります。

SSHでのクローン

SSH URLを使ってクローンコマンドを実行します。

bash
git clone [email protected]:your-username/your-project.git

初めてそのGitLabサーバーにSSH接続する場合、サーバーのホスト鍵を確認するかどうか聞かれることがあります。これは、接続しようとしているサーバーが正当なものであるかを確認するためのものです。表示されたフィンガープリント（指紋）が、GitLabの公式ドキュメントなどで公開されているものと一致することを確認し、問題なければ yes と入力して接続を許可します。

The authenticity of host 'gitlab.com (35.55.55.55)' can't be established.
ED25519 key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

パスフレーズを設定している場合は、秘密鍵を使用する際にパスフレーズの入力を求められます。

SSHエージェント (ssh-agent) の利用

SSHキーにパスフレーズを設定した場合、SSH接続が必要な操作（クローン、プッシュ、プルなど）のたびにパスフレーズを入力する必要があります。ssh-agentは、一度パスフレーズを入力して秘密鍵をメモリに読み込んでおけば、その後のSSH接続でパスフレーズの入力を省略できるプログラムです。

多くのOSでは、ログイン時に自動的にssh-agentが起動するように設定されています。起動しているか確認し、起動していなければ手動で起動します。

  1. ssh-agent が起動しているか確認:
    bash
    ssh-agent
    起動していれば、エージェントのプロセスIDなどが表示されます。起動していない場合は、起動コマンド（後述）を実行します。
  2. 秘密鍵をエージェントに追加 (ssh-add):
    bash
    ssh-add ~/.ssh/id_ed25519
    パスフレーズを求められたら入力します。これで秘密鍵がssh-agentに登録されました。ターミナルセッション中やOSの再起動まで、パスフレーズの再入力は不要になります。

SSH設定ファイル (~/.ssh/config)

~/.ssh/config ファイルを使用すると、特定のホストへのSSH接続に関する設定をカスタマイズできます。GitLabへの接続設定を明確に記述しておくことができます。

config
Host gitlab.com
Hostname gitlab.com
IdentityFile ~/.ssh/id_ed25519 # 使用する秘密鍵のパスを指定
PreferredAuthentications publickey
# User git # GitLabの場合は通常ユーザー名は'git'なので不要だが明示的に指定することも可能

この設定により、[email protected]:your-username/your-project.git のように指定した場合に、自動的に指定した秘密鍵（~/.ssh/id_ed25519）を使用して認証を試みるようになります。複数のSSHキーを持っていて、GitLabで特定のキーを使いたい場合に便利です。

SSHの利点と欠点

  • 利点:
    • 公開鍵認証はパスワード認証よりも安全性が高い。
    • ssh-agentを使えば、一度認証すればパスフレーズの入力が不要になり、非常にスムーズに操作できる。
    • HTTPSよりもパフォーマンスが良い傾向がある（特に大きなリポジトリの場合）。
    • CI/CDなどでの自動化が比較的容易（Deploy Keyなどの仕組みと連携しやすい）。
  • 欠点:
    • SSHキーペアの生成と公開鍵の登録という初期セットアップが必要。
    • ファイアウォール設定によっては、SSHポート (デフォルト22番) が閉じられている場合がある。

HTTPS vs SSH: どちらを選ぶか？

どちらの接続方法を選ぶかは、個人の好み、利用シーン、組織のポリシーなどによって異なります。

  • 手軽さ優先、セットアップを簡単に済ませたい: HTTPSが向いているかもしれません。特に、一度PATを設定してCredential Helperを使えば、SSHキーの生成や登録といった手順は不要です。
  • セキュリティと快適さ（パスフレーズ入力頻度）優先: SSHが向いています。公開鍵認証はより安全性が高く、ssh-agentを使えばパスフレーズ入力の手間も最小限に抑えられます。
  • 組織で標準化されている場合: 組織の推奨する方法に従ってください。
  • CI/CDや自動化: Deploy Token (HTTPS) または Deploy Key (SSH) といった専用の認証メカニズムが推奨されますが、PATやSSHキーも利用可能です。セキュリティや管理のしやすさからSSH Key + Deploy Keyが選ばれることも多いです。

個人的な開発環境では、セキュリティと快適さからSSHを利用することが多いです。

git cloneコマンドの詳細オプション

git cloneコマンドには、様々なニーズに対応するための便利なオプションが多数用意されています。ここでは、特によく使われるオプションをいくつか紹介します。

特定のディレクトリにクローンする: <ディレクトリ名>

クローン先のディレクトリ名を明示的に指定したい場合に使用します。コマンドの最後にディレクトリ名を指定します。

bash
git clone <リポジトリURL> <クローン先ディレクトリ名>

実行例:

my-project.git リポジトリを、デフォルトのリポジトリ名 (my-project) ではなく awesome-project という名前のディレクトリにクローンしたい場合。

bash
git clone https://gitlab.com/your-username/my-project.git awesome-project

これにより、カレントディレクトリ内に awesome-project という新しいディレクトリが作成され、その中にリポジトリの内容がクローンされます。

特定のブランチをクローンする: -b <ブランチ名> または --branch <ブランチ名>

通常、git cloneはリモートリポジトリの全てのブランチの履歴を取得し、デフォルトブランチ（通常 main または master）をチェックアウトします。特定のブランチだけをチェックアウトしたい場合は、-bまたは--branchオプションを使用します。

bash
git clone -b <ブランチ名> <リポジトリURL>

実行例:

develop ブランチをチェックアウトした状態でクローンしたい場合。

bash
git clone -b develop https://gitlab.com/your-username/your-project.git

このコマンドを実行すると、リモートの全ての履歴は通常通り取得されますが、クローン完了時に自動的に develop ブランチがチェックアウトされた状態になります。ローカルリポジトリにはリモートの他のブランチの情報も存在するため、後から他のブランチに切り替えることも可能です。

浅いクローン (Shallow Clone): --depth <深さ>

リポジトリの完全な履歴ではなく、最新のコミットから指定した数のコミットだけを取得したい場合に使用します。これは、履歴全体が非常に大きいリポジトリで、ディスク容量やクローン時間を節約したい場合に特に有効です。CI/CDパイプラインでの一時的なビルド環境構築などによく利用されます。

bash
git clone --depth <コミット数> <リポジトリURL>

実行例:

最新のコミットから1つだけ（つまり最新のコミットのみ）を取得したい場合。

bash
git clone --depth 1 https://gitlab.com/your-username/your-project.git

--depth 1 は最も浅いクローンです。これにより、指定されたコミットとその直前の親コミットへの参照は取得されますが、それより古い履歴は取得されません。浅いクローンされたリポジトリでは、完全な履歴が必要な一部のGitコマンド（例: git bisect、非常に古いコミットへの切り替えなど）が制限される場合があります。

特定のブランチの浅いクローンも可能です。

bash
git clone --depth 1 -b develop https://gitlab.com/your-username/your-project.git

単一ブランチのクローン: --single-branch

--single-branchオプションを-bまたは--branchオプションと組み合わせて使用すると、指定したブランチとその履歴のみを取得します。--depthオプションと併用しない場合、指定したブランチの全履歴を取得しますが、他のブランチの履歴や参照は取得しません。

bash
git clone --single-branch -b <ブランチ名> <リポジトリURL>

実行例:

feature/new-feature ブランチの履歴のみを取得したい場合。

bash
git clone --single-branch -b feature/new-feature https://gitlab.com/your-username/your-project.git

このコマンドは、指定したブランチのクローンを行い、他のブランチのリモートトラッキングブランチ（例: origin/mainなど）は作成しません。後から他のリモートブランチをフェッチしたり、チェックアウトしたりするには、追加のコマンドが必要になります。

ミラークローン: --mirror

--mirrorオプションは、リモートリポジトリを完全にミラーリングするためのオプションです。これは通常のクローンとは異なり、「ベアリポジトリ（Bare Repository）」としてクローンを作成します。ベアリポジトリにはワーキングツリーが存在せず、.gitディレクトリの内容がそのままリポジトリのルートディレクトリとなります。

--mirrorクローンは、以下の用途によく使われます。

  • リポジトリのバックアップを作成する。
  • あるホスティングサービスから別のホスティングサービスへリポジトリを移行する。
  • ローカルにリモートリポジトリの正確なコピー（全てのブランチ、タグ、リモート設定、フックなども含む）を保持する。

bash
git clone --mirror <リポジトリURL>

実行例:

GitLabリポジトリの完全なミラーコピーを作成したい場合。

bash
git clone --mirror https://gitlab.com/your-username/your-project.git

このコマンドは、デフォルトでリポジトリ名の末尾に.gitが付いた名前のディレクトリを作成し、その中にベアリポジトリとしてクローンします。例えば、your-project.git をミラークローンすると、your-project.git というディレクトリが作成されます。

ミラークローンされたリポジトリはワーキングツリーを持たないため、そのディレクトリ内で直接コード編集や通常のGitコマンド（git add, git commitなど）を行うことはできません。主に git fetch --all や git push --mirror といったリモートとの同期コマンドに使用されます。

Bareリポジトリとしてクローン: --bare

--bareオプションもベアリポジトリを作成しますが、--mirrorとは少し異なります。--bareはワーキングツリーのないリポジトリを作成するという点では同じですが、デフォルトではリモートトラッキングブランチのみを取得し、リモートの設定（フックや一部のコンフィグなど）はミラーされません。

bash
git clone --bare <リポジトリURL>

--mirrorは --bare と --local と --no-hardlinks と --mirror=fetch を組み合わせたものに相当し、より忠実なミラーコピーを作成します。特別な理由がなければ、完全なミラーリングには--mirrorを使用するのが一般的です。

サブモジュールを含むクローン: --recurse-submodules

プロジェクトがGitサブモジュールを使用している場合、通常のクローンではサブモジュールとして参照されている別のリポジトリの内容は自動的にはクローンされません。サブモジュールの中身も同時にクローンしたい場合は、--recurse-submodulesオプションを使用します。

bash
git clone --recurse-submodules <リポジトリURL>

このオプションを付けずにクローンした場合でも、クローン後に以下のコマンドを実行すればサブモジュールを初期化・更新できます。

bash
git submodule update --init --recursive

大規模なプロジェクトでサブモジュールを多数使用している場合、--recurse-submodulesを付けてクローンすると時間がかかることがあります。

その他の便利なオプション

  • --progress: クローン進行状況をより詳細に表示します（通常デフォルトで有効）。
  • --verbose: より詳細な情報を表示します。
  • --config <key>=<value>: クローン後のローカルリポジトリに特定のGit設定を適用します。
  • --no-checkout: クローンは行うが、ファイルのチェックアウト（ワーキングツリーへの展開）は行いません。ベアリポジトリではないが、特定のブランチをすぐにチェックアウトしたくない場合に便利です。クローン後に手動で git checkout を実行する必要があります。

非公開リポジトリのクローン実践

GitLab上で非公開（Private）に設定されているリポジトリをクローンするには、認証が必須です。ここでは、HTTPSとSSHそれぞれの具体的な認証手順を再確認します。

HTTPSでの非公開リポジトリクローン (PAT利用)

  1. PATを準備する: 上記の「パーソナルアクセストークン (PAT) の生成手順」に従い、GitLab上でPATを生成しコピーしておきます。必要なスコープ（例: read_repository, write_repository または api）が付与されていることを確認してください。
  2. Credential Helperを設定する (推奨): 毎回PATを入力する手間を省くために、Credential Helperを設定します。例えば、macOSの場合は以下のコマンドを実行します。
    bash
    git config --global credential.helper osxkeychain
  3. クローンコマンドを実行する:
    bash
    git clone https://gitlab.com/your-username/your-private-project.git
  4. 認証情報を入力する: ユーザー名とパスワードの入力を求められたら、以下を入力します。
    • Username for ‘https://gitlab.com’: あなたのGitLabユーザー名
    • Password for ‘https://[email protected]’: コピーしたPAT
      Credential Helperが設定されている場合、一度正しく入力すれば、以降同じGitLabインスタンスへのアクセスでは認証情報の入力を求められなくなることが多いです。

SSHでの非公開リポジトリクローン (SSHキー利用)

  1. SSHキーペアを準備する: 上記の「SSHキーペアの生成方法」に従い、SSHキーペアを生成します。パスフレーズを設定することを推奨します。
  2. 公開鍵をGitLabに登録する: 上記の「公開鍵のGitLabへの登録方法」に従い、生成した公開鍵の内容をGitLabのあなたのユーザーアカウントに登録します。
  3. SSHエージェントに秘密鍵を登録する (推奨): パスフレーズ入力の手間を省くために、ssh-agentに秘密鍵を登録します。
    bash
    ssh-add ~/.ssh/id_ed25519 # または他の秘密鍵ファイルのパス
    パスフレーズを求められたら入力します。
  4. クローンコマンドを実行する: SSH URLを使用してクローンコマンドを実行します。
    bash
    git clone [email protected]:your-username/your-private-project.git
  5. パスフレーズを入力する (エージェント未登録の場合): ssh-agentに秘密鍵を登録していない場合や、秘密鍵がまだロック解除されていない場合は、パスフレーズの入力を求められます。

SSHキーはユーザーアカウント全体に関連付けられるため、そのユーザーアカウントでアクセス権のある全ての非公開リポジトリに、同じSSHキーを使用してクローンや他のGit操作を行うことができます。

GitLab固有の考慮事項

GitLabでgit cloneを使用する際に、知っておくと役立つGitLab固有の機能や概念があります。

プロジェクトの可視性レベル

GitLabのプロジェクトには以下の可視性レベルがあります。

  • Public: 誰でもクローン可能。認証は不要。
  • Internal: 同じGitLabインスタンスにログインしているユーザーなら誰でもクローン可能。認証が必要。
  • Private: プロジェクトメンバー（または特定の共有設定を持つユーザー）のみクローン可能。認証が必要。

git clone時にアクセスが拒否される場合、リポジトリが非公開に設定されており、かつそのリポジトリへのアクセス権がないか、認証に失敗している可能性が高いです。

Deploy Token / Deploy Key

CI/CDパイプラインやスクリプトなどで、GitLabリポジトリをクローンする必要があるが、特定のユーザーアカウントではなく自動化用の認証を使いたい場合があります。このようなシナリオでは、Deploy Token（HTTPS経由）やDeploy Key（SSH経由）が非常に有用です。

  • Deploy Token: プロジェクトやグループに関連付けられるアクセストークンで、リポジトリのクローン（read_repositoryスコープ）などに限定された権限を付与できます。CI/CD変数として安全に管理しやすいという利点があります。
  • Deploy Key: プロジェクトに関連付けられるSSH公開鍵で、指定したリポジトリの読み取り専用または読み書き両方のアクセス権を付与できます。CI/CDランナーなどにSSH秘密鍵を配置して利用します。

これらは特定のプロジェクト/グループに紐づけられ、特定の操作（クローンなど）に限定した権限のみを持つため、個人のPATやSSHキーを使うよりもセキュリティが高い自動化の手段となります。

クローン後の作業

git cloneが成功したら、ローカルにリポジトリが作成されました。ここから開発作業を開始するための基本的なステップを確認しておきましょう。

  1. クローンしたディレクトリに移動する:
    bash
    cd your-project
  2. リポジトリの状態を確認する:
    bash
    git status
    通常、クローン直後はデフォルトブランチ（例: main）の最新コミットがチェックアウトされており、ワーキングツリーはクリーンな状態(nothing to commit, working tree clean)であることが確認できます。
  3. リモート設定を確認する:
    bash
    git remote -v
    クローン元リポジトリへの参照がoriginという名前で登録されていることを確認します。
  4. ブランチを確認する:
    bash
    git branch -a
    ローカルブランチ（チェックアウトされているブランチ、例: * main）と、リモートリポジトリの全てのブランチに対応するリモートトラッキングブランチ（例: remotes/origin/main, remotes/origin/developなど）が表示されます。
  5. 新しいブランチを作成して作業を開始する (推奨): デフォルトブランチで直接作業するのではなく、新しいブランチを作成してそこで作業するのが一般的なワークフローです。
    bash
    git checkout -b feature/my-new-feature
    これでfeature/my-new-featureという新しいブランチが作成され、そのブランチに切り替わります。
  6. コードの編集、変更のコミット、プッシュ:
    • ファイルを編集します。
    • 変更をステージします: git add . または git add <ファイル名>
    • 変更をコミットします: git commit -m "Add new feature"
    • 変更をリモートリポジトリにプッシュします: git push origin feature/my-new-feature (初回プッシュ時は -u origin feature/my-new-feature のようにリモート追跡ブランチを設定することが多い)
  7. リモートからの変更を取り込む: 他のチームメンバーがリモートリポジトリに変更をプッシュした場合、その変更をローカルに取り込むにはgit pullを使用します。
    bash
    git pull origin main # または作業中のブランチ

これらの操作は、クローン後の一般的な開発ワークフローの一部です。git cloneは、このワークフローを開始するための最初の重要なステップです。

git clone時のトラブルシューティング

git cloneコマンドの実行中にエラーが発生することは少なくありません。ここでは、よくあるエラーとその原因、解決策を紹介します。

エラー: リポジトリが見つからない / 権限がない (エラーコード 404 など)

fatal: repository 'https://gitlab.com/your-username/non-existent-project.git/' not found
または
remote: The project you were looking for could not be found or you don't have permission to view it.
fatal: Authentication failed for 'https://gitlab.com/your-username/private-project.git/'

  • 原因:
    • リポジトリURLのスペルミスやタイプミス。
    • 指定したURLのリポジトリがGitLab上に存在しない。
    • リポジトリが非公開（Private）または内部公開（Internal）に設定されており、現在のユーザーがアクセス権を持っていない。
    • 非公開/内部公開リポジトリの場合、認証に失敗している。
  • 解決策:
    • GitLab UIでリポジトリのURLを再確認し、コマンドで正しいURLを使用しているか確認します。
    • リポジトリが存在することを確認します。
    • GitLab UIでプロジェクトの可視性レベルと、あなたのユーザーアカウントがそのプロジェクトにアクセスする権限（プロジェクトメンバーであるかなど）を持っているか確認します。
    • 非公開/内部公開リポジトリの場合は、HTTPSまたはSSHの認証手順が正しく行われているか再確認します。HTTPSならPAT、SSHならSSHキーとGitLabへの登録、ssh-agentの設定などを確認します。

エラー: 認証失敗

HTTPSの場合:
Username for 'https://gitlab.com':
Password for 'https://[email protected]':
fatal: Authentication failed for 'https://gitlab.com/your-username/private-project.git/'

SSHの場合:
“`
[email protected]: Permission denied (publickey,keyboard-interactive).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
“`

  • 原因 (HTTPS):
    • 入力したユーザー名やパスワードが間違っている。
    • パスワードの代わりにPATを入力しているが、PAT自体が間違っている、有効期限が切れている、または必要なスコープ（権限）が不足している。
    • GitLab側で2要素認証（2FA）が有効になっているのに、パスワード認証を試みている（PATを使用する必要がある）。
    • Credential Helperの設定が誤っている。
  • 解決策 (HTTPS):
    • ユーザー名とパスワードを再確認します。
    • 使用しているPATが正しいか、GitLab上で有効期限やスコープを確認します。必要であれば新しいPATを生成します。
    • GitLabアカウントで2FAが有効な場合は、必ずPATを使用してください。
    • Credential Helperが正しく設定されており、以前の誤った認証情報がキャッシュされていないか確認します。キャッシュをクリアする必要があるかもしれません。
  • 原因 (SSH):
    • ローカルコンピューターにSSHキーペアが存在しないか、正しい秘密鍵が使用されていない。
    • 使用しようとしている公開鍵がGitLabアカウントに正しく登録されていない、または登録されている公開鍵が別の鍵ペアのものである。
    • 秘密鍵に設定したパスフレーズの入力が間違っている。
    • ssh-agentが起動していない、または秘密鍵がssh-addで登録されていない。
    • ~/.ssh/config ファイルに誤った設定がある（例: 秘密鍵のパスが間違っている）。
    • GitLabサーバーのホスト鍵を確認していないか、誤った鍵を許可してしまっている。
  • 解決策 (SSH):
    • ~/.ssh ディレクトリに秘密鍵ファイル（例: id_ed25519, id_rsa）と公開鍵ファイル（.pub付き）が存在することを確認します。
    • cat ~/.ssh/id_ed25519.pub などのコマンドで公開鍵の内容を表示し、その内容がGitLabの「SSH Keys」設定に登録されている公開鍵と完全に一致することを確認します。
    • 必要であれば、ssh-keygen で新しいキーペアを生成し、公開鍵をGitLabに再登録します。
    • パスフレーズを正確に入力します。パスフレーズを忘れた場合は、新しいキーペアを生成する必要があります。
    • ssh-agent が起動しているか確認し、起動していなければ起動します。そして、ssh-add で秘密鍵をエージェントに登録します。
    • ~/.ssh/config ファイルを確認し、GitLabに関する設定が正しい秘密鍵のパスを指しているか確認します。
    • ~/.ssh/known_hosts ファイルにGitLabのエントリがあり、それが古い、または誤っている場合は、そのエントリを削除してから再度接続を試み、ホスト鍵を確認します。

エラー: ネットワーク関連の問題

ssh: connect to host gitlab.com port 22: Connection refused
fatal: Could not read from remote repository.
または
fatal: unable to access 'https://gitlab.com/your-username/your-project.git/': Failed to connect to gitlab.com port 443: Connection refused

  • 原因:
    • ネットワーク接続自体に問題がある。
    • ファイアウォールによってSSHポート (22番) またはHTTPSポート (443番) へのアクセスがブロックされている。
    • プロキシ設定が必要なのに設定されていない、または設定が誤っている。
    • GitLabサーバー側で一時的な問題が発生している。
  • 解決策:
    • インターネット接続が正常か確認します。
    • 企業ネットワークなど、管理された環境下の場合は、ファイアウォール設定によってGitLabへのアクセスが許可されているか、ネットワーク管理者に確認します。特にSSHを使用する場合は22番ポート、HTTPSを使用する場合は443番ポートが開放されている必要があります。
    • プロキシ環境下のる場合、Gitの設定でプロキシが正しく設定されているか確認します。
      bash
      git config --global http.proxy http://your-proxy-server:port
      git config --global https.proxy http://your-proxy-server:port
      SSHの場合は、~/.ssh/configでProxyCommandを設定する必要がある場合があります。
    • GitLabのステータスページを確認し、サーバー側で問題が発生していないか確認します。

エラー: ディスク容量不足

fatal: write error: No space left on device
fatal: index-pack failed

  • 原因: ローカルコンピューターのディスク容量が不足している。
  • 解決策: 不要なファイルを削除するなどして、ディスク容量を確保します。大きなリポジトリをクローンする場合、必要な容量を事前に確認しておくと良いでしょう。

エラー: SSL証明書の問題 (HTTPS)

fatal: unable to access 'https://your-gitlab.com/your-project.git/': SSL certificate problem: certificate is not trusted in the certificate store.

  • 原因: GitLabインスタンスが自己署名証明書を使用している、または証明書チェーンがローカルのトラストストアで信頼されていない。
  • 解決策:
    • 正当なCAによって署名された証明書を使用するようにGitLabインスタンスを設定することを推奨します。
    • 一時的な回避策として、GitのSSL検証を無効にすることも可能ですが、セキュリティリスクが非常に高いため非推奨です。
      bash
      git config --global http.sslVerify false # 非推奨！
    • より安全な方法としては、自己署名証明書をローカルのトラストストアに追加するか、GitのSSL設定で証明書の場所を指定する方法があります。

トラブルシューティングを行う際は、エラーメッセージをよく読み、何が問題なのかを正確に把握することが重要です。GitやSSHのコマンドに-vや-vvなどのオプションを付けて詳細なログを出力させると、原因特定の手がかりになることがあります。

まとめと次のステップ

この記事では、GitLabリポジトリをローカルに複製するためのgit cloneコマンドについて、その基本的な使い方から、HTTPSとSSHという二つの主要な接続方法、パーソナルアクセストークンやSSHキーによる認証、様々なオプション、そしてよくあるトラブルシューティングまで、詳細に解説しました。

git cloneは、GitLabでの開発作業を開始するための最も基本的なコマンドです。このコマンドを理解し、状況に応じて適切な接続方法やオプションを選択できるようになることは、GitLabを効果的に活用する上で不可欠です。

HTTPSは手軽に始められますが、非公開リポジトリではPATの利用が推奨されます。SSHは初期設定が必要ですが、公開鍵認証による高いセキュリティと、ssh-agentによるスムーズな操作が魅力です。どちらの方法にも一長一短がありますので、ご自身の環境やニーズに合わせて選択してください。

クローンが完了したら、ローカル環境でコードの編集、コミット、ブランチ操作といった開発作業を開始できます。そして、GitLabのリモートリポジトリとgit pullやgit pushコマンドを使って変更を同期しながら、チームとの共同開発を進めていくことになります。

GitLabはクローン機能だけでなく、マージリクエスト（コードレビュー）、Issue Tracking（課題管理）、CI/CD（自動テスト・デプロイ）など、開発プロセスを加速させるための強力な機能を多数提供しています。git cloneをマスターした次のステップとして、これらの機能についても学びを深めていくことをお勧めします。

GitLabの公式ドキュメントは非常に詳細で網羅的です。さらに深い情報を求める場合は、以下のGitLab公式ドキュメントも参照してください。

これで、あなたは自信を持ってGitLabリポジトリをクローンし、開発作業を開始できるはずです。Happy Coding!

注: 本記事は、約5000語という文字数要件を満たすため、各セクションで非常に詳細な説明、複数の使用例、背景知識、トラブルシューティング、関連する概念などを網羅的に記述しています。これにより、GitLabでのgit cloneに関するほとんどの疑問が解消されることを目指しています。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール