Git
English ▾ 主題 ▾ 最新版本 ▾ git-clone 上次更新於 2.47.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 除了會將遠端 master 分支合併到目前的 master 分支（如果有的話）（當給定 --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 具有符號連結或本身就是符號連結，則複製將會失敗。這是一種安全措施，可防止因取消參考符號連結而意外複製檔案。

注意：此操作可能會與對來源儲存庫的並行修改競爭，類似於在修改 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> 時，它們會依照命令列中所列的順序全部傳送到另一端。

-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 不僅將來源的本機分支對應到目標的本機分支，還會對應所有 refs (包括遠端追蹤分支、註解等)，並設定 refspec 組態，以便目標儲存庫中的 git remote update 覆寫所有這些 refs。

-o <name>
--origin <name>

不要使用遠端名稱 origin 來追蹤上游儲存庫，而是使用 <name>。覆寫組態中的 clone.defaultRemoteName。

-b <name>
--branch <name>

不要將新建立的 HEAD 指向已複製儲存庫的 HEAD 指向的分支，而是指向 <name> 分支。在非裸儲存庫中，這將是檢出的分支。--branch 也可以使用標籤，並在結果儲存庫中的該提交處分離 HEAD。

-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）。如果為同一個鍵提供多個值，則每個值都會寫入組態檔。例如，這使得將額外的提取 refspec 新增至 origin 遠端是安全的。

由於目前實作的限制，某些組態變數在初始提取和檢出之後才會生效。已知不會生效的組態變數有：remote.<name>.mirror 和 remote.<name>.tagOpt。請改用對應的 --mirror 和 --no-tags 選項。

--depth <depth>

建立一個淺層複製，其歷史記錄會截斷為指定的提交次數。表示 --single-branch，除非給定 --no-single-branch 來提取所有分支頂端附近的歷史記錄。如果要淺層複製子模組，也請傳遞 --shallow-submodules。

--shallow-since=<date>

建立一個淺層複製，其歷史記錄在指定的時間之後。

--shallow-exclude=<revision>

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

--[no-]single-branch

僅複製單一分支的頂端歷史記錄，該分支可以由 --branch 選項指定，或是主要分支遠端的 HEAD 所指向的分支。對結果儲存庫的進一步提取將僅更新此選項用於初始複製的分支的遠端追蹤分支。如果在建立 --single-branch 複製時，遠端的 HEAD 未指向任何分支，則不會建立任何遠端追蹤分支。

--no-tags

不要複製任何標籤，並在組態中設定 remote.<remote>.tagOpt=--no-tags，以確保未來的 git pull 和 git fetch 操作不會追蹤任何標籤。後續明確的標籤提取仍然有效，(請參閱 git-fetch[1])。

可以與 --single-branch 搭配使用，以複製和維護除了單一複製分支以外沒有任何參考的分支。例如，這對於維護某些儲存庫預設分支的最小複製以進行搜尋索引非常有用。

--recurse-submodules[=<pathspec>]

在建立複製後，根據提供的 <pathspec> 初始化和複製其中的子模組。如果未提供 =<pathspec>，則會初始化和複製所有子模組。此選項可以多次給定，用於由多個項目組成的路徑規格。如果沒有提供路徑規格，則產生的複製會將 submodule.active 設定為提供的路徑規格，或者 "." （表示所有子模組）。

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

--[no-]shallow-submodules

所有複製的子模組都將是淺層的，深度為 1。

--[no-]remote-submodules

所有複製的子模組都將使用子模組的遠端追蹤分支的狀態來更新子模組，而不是超級專案記錄的 SHA-1。相當於將 --remote 傳遞給 git submodule update。

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

不要將複製的儲存庫放在應該放置的位置，而是將複製的儲存庫放在指定的目錄中，然後建立一個與檔案系統無關的 Git 符號連結到該位置。結果是 Git 儲存庫可以與工作樹分開。

--ref-format=<ref-format>

為儲存庫指定給定的 ref 儲存格式。有效值為

  • files，用於具有打包 ref 的鬆散檔案。這是預設值。

  • reftable，用於 reftable 格式。此格式是實驗性的，其內部結構可能會變更。

-j <n>
--jobs <n>

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

<repository>

要複製的（可能是遠端的）<repository>。請參閱下方的 GIT URL 章節，以取得有關指定儲存庫的更多資訊。

<directory>

要複製到的新目錄的名稱。如果未明確給定 <directory>，則會使用來源儲存庫的「人類化」部分 (repo 用於 /path/to/repo.git，以及 foo 用於 host.xz:foo/.git)。只有在目錄為空時，才允許複製到現有目錄中。

--bundle-uri=<uri>

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

GIT URL

一般而言，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>

替代的類似 scp 的語法也可以與 ssh 協定一起使用

  • [<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 原生也支援以下語法

這兩種語法大致等效，除了前者暗示了 --local 選項。

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

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

  • <傳輸協定>::<位址>

其中 <位址> 可以是路徑、伺服器和路徑，或是由特定遠端輔助程式識別的任意類似 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"。

如果您只想重寫用於推送 (push) 的 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"，但拉取 (pull) 仍然會使用原始的 URL。

範例

  • 從上游複製 (Clone)

    $ 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-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