簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-clone 上次更新於 2.49.0

名稱

git-clone - 克隆倉庫到一個新目錄

概要

git clone [--template=<template-directory>]
	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
	  [--dissociate] [--separate-git-dir <git-dir>]
	  [--depth <depth>] [--[no-]single-branch] [--[no-]tags]
	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
	  [<directory>]

描述

將倉庫克隆到一個新建立的目錄中，為克隆倉庫中的每個分支建立遠端跟蹤分支（使用 git branch --remotes 可見），並建立並檢出一個從克隆倉庫當前活動分支派生出來的初始分支。

克隆後，不帶引數的普通 git fetch 將更新所有遠端跟蹤分支，而不帶引數的 git pull 除了會將遠端主分支合併到當前主分支（如果有的話）之外，還會進行更新（當給出 --single-branch 時，此情況不成立；詳見下文）。

此預設配置是透過在 refs/remotes/origin 下建立指向遠端分支頭的引用，並初始化 remote.origin.url 和 remote.origin.fetch 配置變數來實現的。

選項

-l
--local

當要克隆的倉庫位於本地機器上時，此標誌繞過正常的“Git 感知”傳輸機制，透過複製 HEAD 以及 objects 和 refs 目錄下所有內容來克隆倉庫。 .git/objects/ 目錄下的檔案在可能的情況下會被硬連結以節省空間。

如果倉庫指定為本地路徑（例如，/path/to/repo），這是預設行為，並且 --local 基本上是一個空操作。如果倉庫指定為 URL，則此標誌將被忽略（我們從不使用本地最佳化）。當給出 /path/to/repo 時，指定 --no-local 將覆蓋預設行為，轉而使用常規的 Git 傳輸。

如果倉庫的 $GIT_DIR/objects 包含符號連結或本身是一個符號連結，則克隆將失敗。這是一項安全措施，旨在防止透過解引用符號連結而意外複製檔案。

出於安全原因，此選項不適用於其他使用者擁有的倉庫，必須指定 --no-local 才能成功克隆。

注意：此操作可能與對源倉庫的併發修改產生競態條件，類似於在修改 <src> 的同時執行 cp -r <src> <dst>。

--no-hardlinks

強制從本地檔案系統上的倉庫克隆時，複製 .git/objects 目錄下的檔案，而不是使用硬連結。如果你正在嘗試備份倉庫，這可能是可取的。

-s
--shared

當要克隆的倉庫位於本地機器上時，不使用硬連結，而是自動設定 .git/objects/info/alternates 以與源倉庫共享物件。生成的倉庫最初不包含任何自己的物件。

注意：這是一個可能危險的操作；除非你瞭解其作用，否則不要使用它。如果你使用此選項克隆倉庫，然後刪除源倉庫中的分支（或使用任何其他使現有提交變為未引用的 Git 命令），某些物件可能會變為未引用（或懸空）。這些物件可能會被正常的 Git 操作（例如 git commit）自動呼叫 git maintenance run --auto 所移除。（請參閱 git-maintenance[1]。）如果這些物件被移除並且被克隆倉庫引用，則克隆倉庫將損壞。

請注意，在透過 --shared 克隆的倉庫中執行不帶 --local 選項的 git repack 將把源倉庫中的物件複製到克隆倉庫的 pack 中，從而抵消 clone --shared 的磁碟空間節省。然而，執行 git gc 是安全的，因為它預設使用 --local 選項。

如果你想解除透過 --shared 克隆的倉庫對其源倉庫的依賴，只需執行 git repack -a，將所有物件從源倉庫複製到克隆倉庫的 pack 中即可。

--reference[-if-able] <repository>

如果引用 <repository> 位於本地機器上，則自動設定 .git/objects/info/alternates 以從引用 <repository> 獲取物件。使用已存在的倉庫作為備用倉庫將減少從被克隆倉庫複製的物件數量，從而降低網路和本地儲存成本。使用 --reference-if-able 時，如果目錄不存在，則會跳過併發出警告，而不是中止克隆。

注意：請參閱 --shared 選項的注意事項，以及 --dissociate 選項。

--dissociate

僅為減少網路傳輸而從透過 --reference 選項指定的參考倉庫借用物件，並在克隆完成後透過對借用物件進行必要的本地副本而停止從它們借用。此選項也可用於從已經從另一個倉庫借用物件的本地倉庫進行克隆時——新倉庫將從同一個倉庫借用物件，此選項可用於停止借用。

-q
--quiet

安靜操作。進度不會報告到標準錯誤流。

-v
--verbose

詳細執行。不影響向標準錯誤流報告進度狀態。

--progress

預設情況下，當標準錯誤流連線到終端時，除非指定了 --quiet，否則進度狀態會報告到標準錯誤流。此標誌強制報告進度狀態，即使標準錯誤流未定向到終端。

--server-option=<option>

使用協議版本 2 進行通訊時，將給定字串傳輸到伺服器。給定字串不能包含 NUL 或 LF 字元。伺服器對伺服器選項（包括未知選項）的處理是伺服器特定的。當給出多個 --server-option=<option> 時，它們將按照命令列中列出的順序全部發送到另一端。當命令列中未給出 --server-option=<option> 時，則使用配置變數 remote.<name>.serverOption 的值。

-n
--no-checkout

克隆完成後不執行 HEAD 的檢出。

--[no-]reject-shallow

如果源倉庫是淺層倉庫，則失敗。clone.rejectShallow 配置變數可用於指定預設值。

--bare

建立一個裸 Git 倉庫。也就是說，不是建立 <directory> 並將管理檔案放在 <directory>/.git 中，而是將 <directory> 本身作為 $GIT_DIR。這顯然意味著 --no-checkout，因為沒有地方可以檢出工作樹。此外，遠端的分支頭會直接複製到相應的本地分支頭，而無需對映到 refs/remotes/origin/。使用此選項時，既不會建立遠端跟蹤分支，也不會建立相關的配置變數。

--sparse

採用稀疏檢出，最初只有頂層目錄中的檔案存在。 git-sparse-checkout[1] 命令可用於根據需要擴充套件工作目錄。

--filter=<filter-spec>

使用部分克隆功能，並請求伺服器根據給定的物件過濾器傳送可達物件的子集。使用 --filter 時，提供的 <filter-spec> 用作部分克隆過濾器。例如，--filter=blob:none 將過濾掉所有 blob（檔案內容），直到 Git 需要它們。此外，--filter=blob:limit=<size> 將過濾掉所有大小至少為 <size> 的 blob。有關過濾器規範的更多詳細資訊，請參閱 git-rev-list[1] 中的 --filter 選項。

--also-filter-submodules

還將部分克隆過濾器應用於倉庫中的任何子模組。需要 --filter 和 --recurse-submodules。這可以透過設定 clone.filterSubmodules 配置選項來預設開啟。

--mirror

設定源倉庫的映象。這暗示了 --bare。與 --bare 相比，--mirror 不僅將源的本地分支對映到目標的本地分支，它還對映所有引用（包括遠端跟蹤分支、註釋等），並設定一個 refspec 配置，以便所有這些引用都會被目標倉庫中的 git remote update 覆蓋。

-o <name>
--origin <name>

不使用遠端名稱 origin 來跟蹤上游倉庫，而是使用 <name>。覆蓋配置中的 clone.defaultRemoteName。

-b <name>
--branch <name>

不將新建立的 HEAD 指向克隆倉庫的 HEAD 所指向的分支，而是指向 <name> 分支。在非裸倉庫中，這將是將被檢出的分支。--branch 也可以接受標籤，並將結果倉庫中的 HEAD 分離到該提交。

--revision=<rev>

建立一個新倉庫，並獲取指向給定修訂版本 <rev> 的歷史記錄（僅此而已），不建立任何遠端跟蹤分支，不建立任何本地分支，並將 HEAD 分離到 <rev>。引數可以是引用名稱（例如 refs/heads/main 或 refs/tags/v1.0），它會剝離到某個提交，或者是一個十六進位制物件名稱。此選項與 --branch 和 --mirror 不相容。

-u <upload-pack>
--upload-pack <upload-pack>

如果給出此引數，並且透過 ssh 訪問要克隆的倉庫，則此引數指定在另一端執行的命令的非預設路徑。

--template=<template-directory>

指定將使用模板的目錄；（請參閱 git-init[1] 的“模板目錄”部分。）

-c <key>=<value>
--config <key>=<value>

在新建立的倉庫中設定配置變數；這在倉庫初始化後立即生效，但在獲取遠端歷史或檢出任何檔案之前。 <key> 的格式與 git-config[1] 預期的一致（例如，core.eol=true）。如果為同一個鍵提供了多個值，則每個值都將寫入配置檔案。例如，這使得向 origin 遠端新增額外的 fetch refspec 成為安全的操作。

由於當前實現的限制，某些配置變數在初始 fetch 和 checkout 之後才生效。已知不生效的配置變數有：remote.<name>.mirror 和 remote.<name>.tagOpt。請改用相應的 --mirror 和 --no-tags 選項。

--depth <depth>

建立一個淺克隆，歷史記錄被截斷到指定的提交數量。除非指定 --no-single-branch 以獲取所有分支尖端的歷史記錄，否則隱含 --single-branch。如果要淺層克隆子模組，也要傳遞 --shallow-submodules。

--shallow-since=<date>

建立一個在指定時間之後具有歷史記錄的淺層克隆。

--shallow-exclude=<ref>

建立一個淺層克隆，其歷史記錄排除從指定遠端分支或標籤可到達的提交。此選項可以多次指定。

--[no-]single-branch

僅克隆指向單個分支尖端的歷史記錄，該分支要麼由 --branch 選項指定，要麼由主分支遠端的 HEAD 指向。隨後獲取到生成倉庫的操作將僅更新用於初始克隆的該分支的遠端跟蹤分支。如果進行 --single-branch 克隆時，遠端的 HEAD 未指向任何分支，則不會建立遠端跟蹤分支。

--[no-]tags

控制是否克隆標籤。當給出 --no-tags 時，該選項將透過設定 remote.<remote>.tagOpt=--no-tags 配置而永久生效。這確保了未來的 git pull 和 git fetch 不會跟蹤任何標籤。隨後的顯式標籤獲取仍然有效（參見 git-fetch[1]）。

預設情況下，標籤會被克隆，因此傳遞 --tags 通常是空操作，除非它取消了之前的 --no-tags。

可以與 --single-branch 結合使用，以克隆和維護一個除了單個克隆分支外沒有其他引用的分支。這對於例如維護某些倉庫預設分支的最小克隆以進行搜尋索引很有用。

--recurse-submodules[=<pathspec>]

建立克隆後，根據提供的 <pathspec> 初始化並克隆其中的子模組。如果未提供 =<pathspec>，則初始化並克隆所有子模組。此選項可多次給定，用於包含多個條目的 pathspec。生成的克隆將 submodule.active 設定為提供的 pathspec，如果未提供 pathspec，則設定為“.”（表示所有子模組）。

子模組使用其預設設定進行初始化和克隆。這等效於在克隆完成後立即執行 git submodule update --init --recursive <pathspec>。如果克隆的倉庫沒有工作樹/檢出（即，如果給定了 --no-checkout/-n、--bare 或 --mirror 中的任何一個），則此選項將被忽略。

--[no-]shallow-submodules

所有被克隆的子模組都將是深度為 1 的淺層克隆。

--[no-]remote-submodules

所有被克隆的子模組將使用子模組遠端跟蹤分支的狀態來更新子模組，而不是使用父專案的記錄 SHA-1。等同於向 git submodule update 傳遞 --remote。

--separate-git-dir=<git-dir>

不將克隆的倉庫放置在它應該在的位置，而是將其放置在指定的目錄中，然後建立指向該位置的與檔案系統無關的 Git 符號連結。結果是 Git 倉庫可以與工作樹分離。

--ref-format=<ref-format>

為倉庫指定給定的引用儲存格式。有效值為

  • files 表示帶有 packed-refs 的鬆散檔案。這是預設值。

  • reftable 表示 reftable 格式。此格式是實驗性的，其內部結構可能會更改。

-j <n>
--jobs <n>

同時獲取的子模組數量。預設為 submodule.fetchJobs 選項。

<repository>

要克隆的（可能是遠端的）<repository>。有關指定倉庫的更多資訊，請參閱下面的 GIT URLS 部分。

<directory>

要克隆到的新目錄的名稱。如果未明確給出 <directory>，則使用源倉庫的“人性化”部分（對於 /path/to/repo.git 為 repo，對於 host.xz:foo/.git 為 foo）。只允許克隆到空目錄。

--bundle-uri=<uri>

在從遠端獲取之前，從給定的 <uri> 獲取一個包，並將資料解包到本地倉庫中。包中的引用將儲存在隱藏的 refs/bundle/* 名稱空間下。此選項與 --depth、--shallow-since 和 --shallow-exclude 不相容。

GIT URLS

通常，URL 包含有關傳輸協議、遠端伺服器地址和倉庫路徑的資訊。根據傳輸協議，其中一些資訊可能不存在。

Git 支援 ssh、git、http 和 https 協議（此外，ftp 和 ftps 也可用於獲取，但這效率低下且已棄用；請勿使用它們）。

原生傳輸（即 git:// URL）不進行身份驗證，在不安全的網路上應謹慎使用。

可以使用以下語法：

  • ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

  • git://<host>[:<port>]/<path-to-git-repo>

  • http[s]://<host>[:<port>]/<path-to-git-repo>

  • ftp[s]://<host>[:<port>]/<path-to-git-repo>

ssh 協議還可以使用另一種類似 scp 的語法：

  • [<user>@]<host>:/<path-to-git-repo>

此語法僅在第一個冒號之前沒有斜槓時才被識別。這有助於區分包含冒號的本地路徑。例如，本地路徑 foo:bar 可以指定為絕對路徑或 ./foo:bar，以避免被誤解為 ssh URL。

ssh 和 git 協議還支援 ~<username> 擴充套件

  • ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>

  • git://<host>[:<port>]/~<user>/<path-to-git-repo>

  • [<user>@]<host>:~<user>/<path-to-git-repo>

對於 Git 本身也支援的本地倉庫，可以使用以下語法

  • /path/to/repo.git/

  • file:///path/to/repo.git/

這兩種語法基本等效，只是前者隱含 --local 選項。

git clone、git fetch 和 git pull，但不包括 git push，也將接受合適的包檔案。請參閱 git-bundle[1]。

當 Git 不知道如何處理某種傳輸協議時，如果存在 remote-<transport> 遠端輔助工具，它會嘗試使用它。要明確請求遠端輔助工具，可以使用以下語法

  • <transport>::<address>

其中 <address> 可以是路徑、伺服器和路徑，或者是特定遠端輔助工具可識別的任意類 URL 字串。有關詳細資訊，請參閱 gitremote-helpers[7]。

如果存在大量名稱相似的遠端倉庫，並且您想為它們使用不同的格式（以便您使用的 URL 將被重寫為可用的 URL），您可以建立以下形式的配置節：

	[url "<actual-url-base>"]
		insteadOf = <other-url-base>

例如，有了這個：

	[url "git://git.host.xz/"]
		insteadOf = host.xz:/path/to/
		insteadOf = work:

“work:repo.git”或“host.xz:/path/to/repo.git”這樣的 URL 在任何接受 URL 的上下文中都將被重寫為“git://git.host.xz/repo.git”。

如果只想重寫推送的 URL，可以建立以下形式的配置節：

	[url "<actual-url-base>"]
		pushInsteadOf = <other-url-base>

例如，有了這個：

	[url "ssh://example.org/"]
		pushInsteadOf = git://example.org/

像“git://example.org/path/to/repo.git”這樣的 URL 將被重寫為“ssh://example.org/path/to/repo.git”用於推送，但拉取仍將使用原始 URL。

示例

  • 從上游克隆

    $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
$ cd my-linux
$ make

  • 建立一個本地克隆，從當前目錄借用物件，而不進行檢出

    $ git clone -l -s -n . ../copy
$ cd ../copy
$ git show-branch

  • 從上游克隆，同時從現有本地目錄借用

    $ git clone --reference /git/linux.git \
	git://git.kernel.org/pub/scm/.../linux.git \
	my-linux
$ cd my-linux

  • 建立一個裸倉庫以釋出您的更改

    $ git clone --bare -l /home/proj/.git /pub/scm/proj.git

  • 從其他使用者克隆本地倉庫

    $ git clone --no-local /home/otheruser/proj.git /pub/scm/proj.git

配置

本節中以下所有內容均從 git-config[1] 文件中選擇性地包含。內容與彼處相同：

init.templateDir

指定將從中複製模板的目錄。（請參閱 git-init[1] 的“模板目錄”部分。）

init.defaultBranch

允許覆蓋預設分支名稱，例如在初始化新倉庫時。

init.defaultObjectFormat

允許覆蓋新倉庫的預設物件格式。請參閱 git-init[1] 中的 --object-format=。命令列選項和 GIT_DEFAULT_HASH 環境變數都優先於此配置。

init.defaultRefFormat

允許覆蓋新倉庫的預設引用儲存格式。請參閱 git-init[1] 中的 --ref-format=。命令列選項和 GIT_DEFAULT_REF_FORMAT 環境變數都優先於此配置。

clone.defaultRemoteName

克隆倉庫時要建立的遠端倉庫的名稱。預設為 origin。可以透過傳遞 --origin 命令列選項來覆蓋。

clone.rejectShallow

如果倉庫是淺層倉庫，則拒絕克隆；這可以透過在命令列上傳遞 --reject-shallow 選項來覆蓋。

clone.filterSubmodules

如果提供了部分克隆過濾器（請參閱 git-rev-list[1] 中的 --filter）並且使用了 --recurse-submodules，則也將過濾器應用於子模組。

GIT

Git[1] 套件的一部分

scroll-to-top