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 命令参数详解。