git clone 把远端仓库完整复制到本地:建目录、拉对象、创建 origin 远端、建远程跟踪分支、检出当前分支,一条命令全做完。它是加入一个已有项目时唯一需要记的命令。

大仓库、单分支、子模块、只要历史不要文件……这些需求全靠参数控制。本文把 git clone 的常用参数逐项列出并解说。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 3 / 28 篇,全部收录在 Git 栏目。参数表列的是日常高频项,并非穷举;想看某个命令的完整参数,用 git clone -h 看精简列表、git help clone 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架,再对照下一节的参数表。<占位> 表示必填值,实际输入时不要带尖括号;[...] 表示可选项,-- 用来分隔选项与路径。

bash语法
git clone [<options>] [--] <repository> [<directory>]

二、参数逐项详解

下表按用途列出 git clone 的常用参数,每项都注明了「它到底改变了什么」。

参数作用
<repository> / <directory>仓库地址(HTTPS / SSH / 本地路径)与本地目录名;目录须不存在或为空
-b <名> / --branch克隆后检出指定分支或标签;接标签会进入 detached HEAD
-o <名> / --origin把远端别名从 origin 改成别的名字
--depth=<n>浅克隆,只取最近 n 条提交;隐含 --single-branch
--single-branch / --no-single-branch只克隆单分支历史 / 显式取回所有分支
--recurse-submodules[=<路径>]克隆后一并初始化并拉取子模块
--shallow-submodules子模块也用 --depth=1 浅克隆
--no-tags / --tags不取标签 / 显式取标签(默认就会取)
--filter=<过滤规则>部分克隆,如 blob:none 先不下载文件内容,用到时再按需取
--sparse启用稀疏检出,初始只放顶层目录文件
-n / --no-checkout克隆完不检出文件,只要 .git 历史;注意这里 -n 不是 dry-run
--bare / --mirror建裸仓库 / 建完整镜像(含所有 refs,常用于仓库搬迁)
-j <n> / --jobs并发拉取子模块的数量
-c <key>=<value>克隆时顺手写一条仓库级配置,在拉取历史前就生效
-q / -v静默 / 详细输出

三、常用示例

几种实用的克隆姿势

bash几种实用的克隆姿势
git clone git@example.com:team/app.git
git clone -b release/2.0 --single-branch git@example.com:team/app.git app-2
git clone --depth=1 --filter=blob:none https://example.com/big-repo.git
git clone --recurse-submodules https://example.com/mono.git

浅克隆之后补全历史

bash浅克隆之后补全历史
git fetch --unshallow
# 想看到其它远端分支
git remote set-branches origin "*"
git fetch --prune

克隆后先确认状态

bash克隆后先确认状态
git remote -v
git branch -a
git status -sb

四、注意事项

⚠️
浅克隆的两个坑
--depth 会连带开启 --single-branch,之后 git branch -r 看不到别的远端分支;要补就先 git remote set-branches origin '*' 再 git fetch。另外浅仓库里 git log 看不到更早历史,做二分排查前务必先 git fetch --unshallow。
HTTPS 还是 SSH: 只读拉公开仓库用 HTTPS 最省事;要推送就配 SSH key。地址写错协议时不用重新克隆,用 git remote set-url origin <新地址> 改即可。

五、小结

普通项目一条 git clone <url> 就够了;遇到超大仓库再叠加 --depth、--filter、--sparse。记住「浅克隆是有代价的」,需要完整历史时随时可以用 git fetch --unshallow 补回来。

本系列共 28 篇,一个命令一篇,完整目录见 Git 栏目。下一篇:git status 命令参数详解。