git clone完整使用手册

git-clone - 将一个仓库克隆到一个新目录中

用法

git clone [--template=<模板目录>]
          [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
          [-o <名称>] [-b <名称>] [-u <上传包>] [--reference <仓库>]
          [--dissociate] [--separate-git-dir <git目录>]
          [--depth <深度>] [--[no-]single-branch] [--no-tags]
          [--recurse-submodules[=<路径模式>]] [--[no-]shallow-submodules]
          [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
          [--filter=<过滤器> [--also-filter-submodules]] [--] <仓库>
          [<目录>]

描述

将一个仓库克隆到一个新创建的目录中，为克隆的仓库中的每个分支创建远程跟踪分支（可通过

git branch --remotes

查看），并创建并检出一个从克隆仓库的当前活动分支派生的初始分支。

克隆完成后，一个没有参数的

git fetch

命令将更新所有远程跟踪分支，而一个没有参数的

git pull

命令还会将远程主分支合并到当前的主分支（如果指定了

--single-branch

，这不适用；参见下文）。

这种默认配置是通过在

refs/remotes/origin

下创建指向远程分支头的引用，并初始化

remote.origin.url

和

remote.origin.fetch

配置变量来实现的。

选项

-l, --local

当克隆的仓库位于本地机器上时，该标志绕过常规的“Git感知”传输机制，通过复制

HEAD

和

objects

与

refs

目录下的所有内容来克隆仓库。
如果仓库指定为本地路径（如

/path/to/repo

），这是默认行为，

--local

实质上没有作用。如果仓库是一个URL，则忽略此标志（并且不会使用本地优化）。
如果仓库的

$GIT_DIR/objects

包含符号链接或本身是符号链接，克隆将失败。此操作可防止通过解引用符号链接意外复制文件。

--no-hardlinks

强制在本地文件系统上从仓库克隆时复制

.git/objects

目录下的文件，而不是使用硬链接。适用于需要备份仓库的情况。

-s, --shared

克隆时共享对象而不复制，结果仓库不会包含自己的对象。此操作有风险，可能导致数据丢失，建议谨慎使用。

--reference[-if-able] <仓库>

使用本地参考仓库共享对象，减少网络和存储消耗。

--dissociate

在克隆完成后停止借用参考仓库的对象，必要时复制借用的对象到本地。

-q, --quiet

静默操作，不输出进度。

-v, --verbose

详细输出。

--progress

强制显示进度状态。

-n, --no-checkout

克隆完成后不检出

HEAD

。

--bare

创建裸仓库，

$GIT_DIR

是

<目录>

本身，且不会检出工作树。

--mirror

设置镜像仓库，包含所有引用，并配置同步更新。

-o <名称>, --origin <名称>

自定义远程仓库名称，默认为

origin

。

-b <名称>, --branch <名称>

指定要检出的分支，或通过标签指定某个提交。

--depth <深度>

创建一个浅克隆，历史记录被截断为指定的提交数。

--shallow-since=<date>

创建一个浅克隆仓库，包含从指定时间点之后的历史记录。这可以减少克隆时拉取的提交数量。

--shallow-exclude=<revision>

创建一个浅克隆仓库，排除从指定远程分支或标签开始的提交记录。可以多次指定该选项以排除多个修订点的提交。

--[no-]single-branch

仅克隆指定分支（通过

--branch

选项指定，或默认指向远程仓库的主分支）的历史记录。此选项生成的仓库在后续获取更新时，仅更新该分支的远程跟踪分支。如果远程的

HEAD

不指向任何分支，则不会创建远程跟踪分支。

--no-tags

不克隆任何标签，并在配置中设置

remote.<remote>.tagOpt=--no-tags

，确保后续的

git pull

和

git fetch

操作不会跟随任何标签。后续的显式标签获取仍然有效（详见

git-fetch(1)

）。此选项可以与

--single-branch

一起使用，以克隆并维护一个不包含其他引用的最小化分支仓库。这对于某些仓库的默认分支的搜索索引等用途非常有用。

--recurse-submodules[=<pathspec>]

在克隆完成后，初始化并克隆基于提供的

pathspec

的子模块。如果未提供

pathspec

，则初始化并克隆所有子模块。该选项可多次使用以包含多个

pathspec

。生成的克隆仓库的

submodule.active

配置为提供的

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 仓库与工作树分离。

-j <n>

/

--jobs <n>

同时获取的子模块数量。默认值由

submodule.fetchJobs

配置选项决定。

<repository>

指定要克隆的仓库（可能是远程仓库）。有关指定仓库的更多信息，参见 GIT URLS 部分。

<directory>

指定要克隆到的新目录名称。如果未显式指定目录，则使用源仓库的 "humanish" 部分作为默认名称（例如

/path/to/repo.git

的名称为

repo

，

host.xz:foo/.git

的名称为

foo

）。仅允许克隆到空目录中。

--bundle-uri=<uri>

在从远程仓库获取数据之前，从指定的

<uri>

获取一个 bundle，并将数据解压到本地仓库中。bundle 中的引用将存储在隐藏的

refs/bundle/*

命名空间中。此选项与

--depth

、

--shallow-since

和

--shallow-exclude

选项不兼容。

GIT URLS

通常情况下，URL 包含有关传输协议、远程服务器地址以及仓库路径的信息。根据传输协议的不同，某些信息可能会缺失。

Git 支持 ssh、git、http 和 https 协议（此外，也可以使用 ftp 和 ftps 来获取内容，但它们效率低下，已经被弃用；请不要使用它们）。

原生的传输方式（即 git:// URL）不进行身份验证，因此在不安全的网络环境中应谨慎使用。

以下语法可以与这些协议一起使用：

ssh://[user@]host.xz[:port]/path/to/repo.git/
git://host.xz[:port]/path/to/repo.git/
http[s]://host.xz[:port]/path/to/repo.git/
ftp[s]://host.xz[:port]/path/to/repo.git/

对于 ssh 协议，还可以使用类似 scp 的替代语法：

[user@]host.xz:path/to/repo.git/

此语法仅在第一个冒号前没有斜杠时才被识别。这有助于区分包含冒号的本地路径。例如，本地路径

foo:bar

可以指定为绝对路径或

./foo:bar

，以避免被误认为是 ssh URL。

ssh 和 git 协议还支持 ~username 扩展：

ssh://[user@]host.xz[:port]/~[user]/path/to/repo.git/
git://host.xz[:port]/~[user]/path/to/repo.git/
[user@]host.xz:/~[user]/path/to/repo.git/

对于 Git 原生支持的本地仓库，可以使用以下语法：

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

这两种语法基本等效，除了前者隐含了

--local

选项。

git clone

、

git fetch

和

git pull

命令也接受合适的 bundle 文件。参见

git-bundle(1)

。

当 Git 不知道如何处理某个传输协议时，它会尝试使用

remote-<transport>

远程助手（如果存在）。要明确请求远程助手，可以使用以下语法：

<transport>::<address>

其中

<address>

可以是路径、服务器和路径或被特定远程助手识别的任意类似 URL 的字符串。详情请参阅

gitremote-helpers(7)

。

如果有大量同名的远程仓库，且希望为它们使用不同的 URL 格式（即，您使用的 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。

EXAMPLES 示例

从上游克隆：

$ 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

CONFIGURATION 配置

从本节起，以下内容是从

git-config(1)

文档中选择性引用的。内容与

git-config(1)

文档中相同：

• init.templateDir：指定将从哪个目录复制模板。（参见 git-init(1) 中的 "TEMPLATE DIRECTORY" 部分）
• init.defaultBranch：允许覆盖默认分支名称，例如在初始化新仓库时。
• clone.defaultRemoteName：克隆仓库时创建的远程仓库名称。默认为 origin，可以通过传递 --origin 命令行选项覆盖。
• clone.rejectShallow：拒绝克隆一个浅仓库，可以通过命令行中的 --reject-shallow 选项覆盖。参见 git-clone(1)。
• clone.filterSubmodules：如果提供了部分克隆过滤器（参见 git-rev-list(1) 中的 --filter），并且使用了 --recurse-submodules，则也将过滤器应用于子模块