Git只克隆某个目录：稀疏检出、浅克隆与部分克隆实战指南-北京尧图网络

我最早遇到“只克隆某个目录”这个需求是在一次接手一个巨大的遗留仓库的时候。当时仓库体积超过20GB历史提交接近2万条而我真正要改的代码只有一个子模块。全量克隆意味着不仅等得难受还会把团队所有成员的工作副本、历史分支甚至各种不小心提交进去的二进制依赖全拖到自己硬盘上。后面我在CI环境、个人电脑、临时服务器上都反复用过同一套技巧今天把这几种做法完完整整整理出来。这个主题适合两类人一类是仓库体积已经大到影响日常开发想只拉取业务相关目录的人另一类是只想从某个开源项目里拿一个目录或配置文件不想因此把整个仓库拖下来的人。两种场景的解决思路不完全一样本文都会覆盖到。1. 大型仓库的痛一个“只想拿一个目录”的真实场景先说我自己的经历。之前在某家公司团队采用了一个典型的单体仓库monorepo结构前后端、移动端、运维脚本、设计资源、文档全部挤在同一个仓库里。仓库体积随着时间推移涨到了15GB以上单次克隆耗时在普通网络下接近半小时有时候网络抖动还会中途失败。我负责的是其中一个移动端模块平时改的东西只在/apps/mobile/目录下。每次在新电脑上配环境都要先忍受一次全量克隆。到后面我甚至开始怀疑Git 是不是根本做不到“只拿一部分”其实不是做不到而是很多人不知道怎么做或者只知道某个比较老的办法又不敢轻易在生产环境用。这篇文章我把从 Git 2.25 到最新版本都兼容的做法列出来同时把那些网上经常讲但容易被忽略的坑一并说清楚。从需求本身来看所谓“只克隆远程仓库的某一个目录或文件”其实可以拆成两个层级层级一我只是想在工作区看到这一个目录其他目录可以不出现但历史数据可以留在本地 .git 里。层级二我只想下载这一个目录的最新内容连历史对象、无用提交都不想下载本地 .git 体积越小越好。层级一用 Sparse Checkout 就能解决层级二需要把浅克隆、对象过滤、稀疏检出配合起来用。很多人只讲了其中一个结果做完发现 .git 还是十几个GB就误以为方法无效。实际上要看你是不是把三个机制用对了。我建议在往下看之前先打开终端确认一下Git版本。git --version如果你的版本低于 2.25那后续提到的git sparse-checkout set这种命令可能用不了。我后面会讲老版本怎么做但如果你能升级我建议先把Git升上去。相关热搜里经常出现“git安装”和“git下载”说明很多人在环境准备阶段就卡住了这里多说一句Windows上装Git千万别用那种自带一堆捆绑的来历不明安装包去Git官网或系统包管理器装就好。2. 为什么Git不能“想克隆哪个目录就克隆哪个目录”要理解解决方案得先明白 Git 底层的对象模型。很多人第一次听到“Git不能按目录克隆”时觉得这是功能缺失其实是它的设计和工作方式决定的。Git 的仓库本质是一个对象数据库里面存着四类对象提交对象、树对象、数据对象、标签对象。一个提交会通过一棵树对象记录整个项目在某一个瞬间的所有文件和目录结构而树对象下面又有子树对象和数据对象。也就是说任意一个提交在逻辑上都和仓库的全部内容相关。当我们执行git clone时Git 默认会把远程仓库的所有分支引用、所有历史提交、所有树对象和数据对象全部拉下来。这个过程很像什么很像你买了一整套百科全书哪怕你只打算读其中一本分册出版社也会把整套书装箱发给你。因为整套书是作为一个整体印刷、装订和运输的目录索引和分册之间存在紧密的关联关系。Git 为了保证任何一次切换分支、查看历史、对比版本时都能拿到完整数据默认策略就是“全量搬运”。这也解释了一个现象用了 Sparse Checkout 之后你工作区里确实只显示部分目录了但.git文件夹的体积没有明显变小。因为历史对象还是被完整下载下来了只是工作区“遮住”了其他目录数据仍然躺在本地。如果你只是希望工作区干净不想被无关目录干扰那 Sparse Checkout 已经够用如果你还希望下载量本身减少那必须配合浅克隆和对象过滤器。还有一个容易被人忽略的点Git 的远程协议设计里本来就没有“按目录拉取”这种接口。git fetch的最小单位是引用和提交不是目录。后来 Git 团队通过引入--filter和稀疏检出才在某种程度上实现了“按需获取对象”的能力但它依然不是传统意义上的“目录级克隆”。认识到这一点你对后面的命令就不会产生错误预期。3. Sparse Checkout让工作区“只要一个目录”3.1 老式稀疏检出写规则文件如果你的 Git 版本比较老或者是想从原理上理解稀疏检出可以先看看老式的做法。核心思路是先让仓库认识远程地址但先不检出任何文件然后通过一个规则文件告诉 Git“我只要哪些路径”。完整流程是这样的# 1. 创建一个空目录并进入 mkdir mobile-only cd mobile-only # 2. 初始化仓库并关联远程 git init git remote add origin https://github.com/example/monorepo.git # 3. 开启稀疏检出开关 git config core.sparseCheckout true # 4. 编辑规则文件指定要保留的目录 echo apps/mobile/ .git/info/sparse-checkout # 5. 拉取并检出 git pull origin main这样执行完之后工作区只会有apps/mobile/这一个目录。需要注意老式做法有几个容易踩坑的地方规则文件里如果不写完整的父目录路径有可能会把同名目录也匹配进来。老式规则支持的就是标准 gitignore 语法所以apps/mobile/和/apps/mobile/的匹配范围是不同的。如果规则文件写错了可能出现工作区什么东西都没有的情况不要慌修改.git/info/sparse-checkout后重新执行git read-tree -mu HEAD或者直接重新git checkout即可。老式方式里你临时想查看其他目录文件也得手动改规则文件比较麻烦。3.2 新式cone模式git sparse-checkout命令Git 2.25 引入了git sparse-checkout命令配合默认的 cone 模式把稀疏检出变得像日常操作一样简单。cone 模式不再匹配复杂的 gitignore 规则而是直接用目录白名单。只要设置一个或多个目录工作区就只保留这些目录。# 直接克隆并立即启用稀疏检出 git clone --sparse https://github.com/example/monorepo.git # 进入仓库后设置要保留的目录 cd monorepo git sparse-checkout set apps/mobile如果你已经在仓库里了也可以这样操作git sparse-checkout init --cone git sparse-checkout set apps/mobilegit sparse-checkout set可以连续指定多个目录git sparse-checkout set apps/mobile apps/web docs我强烈建议新项目直接用 cone 模式原因有三点第一心智负担低不需要记一堆通配符规则目录就是目录。第二cone 模式默认会保留仓库根目录下的一些常规文件比如 README、.gitignore不会让你连最基本的项目说明都看不到。第三和--filterblob:none等高级特性配合时cone 模式的递归扩展行为更符合直觉后续想加目录也只需要一条命令。3.3 修改和恢复检出范围设置完之后日常使用中你可能会反悔想多要一个目录或者想恢复全量检出。命令如下# 追加一个目录 git sparse-checkout add docs # 查看当前稀疏检出模式 git sparse-checkout list # 放开所有目录恢复全量工作区 git sparse-checkout disable这些命令执行后Git 会自动更新索引和工作区不需要你手动做额外操作。需要注意的一点是disable只是把工作区变回全量状态它不会删掉你已经下载的对象也不会自动清理.git体积。如果你之前因为浅克隆只拉了一部分历史disable 之后可能会需要联网拉取缺失对象。3.4 稀疏检出的边界与局限稀疏检出确实让工作区清爽了不少但如果你把整个仓库完整克隆了一遍没有加--depth也没有加--filter那.git目录的体积还是全量的。我曾经遇到过一个同事他用了稀疏检出后跑来问我“为什么磁盘占用没有变小”我一看.git目录还是十几个GB这就是典型的只做了“工作区裁剪”没有做“对象裁剪”。另外一个边界是很多 IDE 和静态分析工具在读取项目时会默认从当前目录递归搜索文件。如果你只检出了个别目录那么构建脚本、路径解析、代码补全都可能在找不到文件时报错。这种问题不算 Git 的锅而是你的工具链并不认识“稀疏工作区”这个概念。碰到这种情况要么让构建脚本明确指向已检出的目录要么把那个目录在 IDE 里作为单独的项目根目录打开。4. 浅克隆、过滤器、稀疏检出三者叠加把下载量也砍下去如果你不光想让工作区只显示一个目录还想让下载的数据本身就变少那必须上更狠的组合拳。我常用的命令长这样git clone --depth 1 --filterblob:none --sparse https://github.com/example/monorepo.git cd monorepo git sparse-checkout set apps/mobile这条命令里同时用了三个参数很多人看过但不知道各自在干什么我逐个拆开讲。4.1 --depth 1浅克隆丢掉大部分历史--depth 1意味着只拉取最新提交的快照不要历史记录。你在这个仓库里看不到之前的提交记录git log打出来只有一条。这非常适合那种你只需要最新代码、不需要回溯历史的场景。浅克隆最大的收益是大幅降低对象数量。一个仓库的绝大部分体积往往来自历史提交中的各种版本变更比如被修改过的图片、删除掉的旧文件、合并进仓库的大二进制包。浅克隆直接把这些历史包袱都甩掉了。但要注意浅克隆不能盲目用于你要长期开发和提交代码的场景。因为浅克隆的仓库作为工作副本你往里面提交时如果远程有更多历史Git 可能需要先“补齐”历史才能完成合并。一旦出现这种情况你可能会收到shallow update not allowed的报错。所以我的原则是只读和使用最新代码用浅克隆很香要长期开发和提交还是老老实实全量克隆或者至少保持合理深度。4.2 --filterblob:none对象过滤器按需拉取文件内容--filterblob:none是 Git 的 partial clone 机制。它的意思是克隆时只下载提交对象和树对象不下载实际的文件内容blob 对象。当你真正检出某个文件、查看某个历史版本、执行 diff 的时候Git 才会按需向远程仓库请求对应的文件内容。这个机制有点像浏览器里的懒加载页面先给一个骨架真正滚动到图片位置时才去请求图片。对于“只想要一个目录”的场景配合稀疏检出Git 就只会按需拉取你目录里的文件 blob其他目录的 blob 根本不会下载所以网络传输量会大幅减少。4.3 --sparse克隆后默认采用稀疏检出--sparse参数让仓库在克隆后直接进入稀疏检出模式并且默认不会检出所有文件。这样你后面执行sparse-checkout set时Git 只去拉取对应目录的文件对象不会先把全仓库内容都读一遍。如果不加这个参数哪怕你用了--filterblob:none克隆阶段还是会把树对象展开工作区里会看到所有目录结构只是文件内容缺失。虽然也能用但体验上不如直接--sparse干净。三个参数配合起来执行完.git体积可以压缩到非常小。我举个例子假设一个仓库全量体积是2GB历史提交1万条使用上面的组合后.git目录可能只剩几MB到几十MB工作区只显示你要的目录而且第一次检出时只下载该目录对应的文件内容。4.4 按需拉取的注意事项用了--filterblob:none之后本地在运行某些命令时会在后台额外发起网络请求比如git log -p、git diff、git blame之类的操作。这些命令需要文件内容而文件内容可能原来不在本地Git 就会去远程“补货”。如果网络不稳定或者远程仓库不可用这类命令就可能失败。尤其是在 CI 环境里构建机可能只有短暂的外网权限一旦按需拉取超时构建就会挂掉。所以 CI 里我一般不建议用 partial clone除非你能确保构建过程中所有需要的文件对象都已经被完整拉取。另外要注意--filterblob:none要求远程Git仓库支持 partial clone 协议目前 GitLab、GitHub、Gitee 以及较新版本的 Git 服务端都支持但公司自建的很老的 Git 服务器可能不行。实测在自建 GitLab 上基本没问题但如果是那种内部很久没升级过的服务端建议先在测试仓库上试一下。4.5 完整操作示例再给一个更完整的示例包含切换分支和一些日常操作演示。# 从远程克隆只拿最新提交、不下载文件对象、直接进入稀疏检出模式 git clone --depth 1 --filterblob:none --sparse https://github.com/example/monorepo.git cd monorepo # 设置只保留 apps/mobile 目录 git sparse-checkout set apps/mobile # 查看当前检出的目录 git sparse-checkout list # 后续想切到其他分支浅克隆下也可能需要先扩展历史 git fetch --deepen 1 origin feature/xxx git sparse-checkout add apps/backend我实际用这套组合的时候通常会把远程仓库的浅克隆地址写在脚本里比如自动化部署脚本。只要不涉及本地提交这套方式又快又省流量。但如果你要在这份工作副本里跑git push请把--depth 1去掉改用git clone --filterblob:none --sparse https://github.com/example/monorepo.git这样的话历史是完整的只是文件内容会按需下载兼顾了体积和可提交性。5. 只拿一个文件不装Git也行的几个姿势如果说克隆整个仓库勉强还能忍受那“只拿一个文件”其实有更轻量的方式。尤其是你想从开源项目的仓库里拿某个配置文件、某个工具脚本或者某个版本固定的压缩包根本没必要装Git、也没必要克隆仓库。5.1 用raw链接直接下载GitHub 上每个文件都有一个 raw 地址。比如你想下载https://github.com/example/monorepo仓库main分支下docs/setup.md这个文件raw 链接就是https://raw.githubusercontent.com/example/monorepo/main/docs/setup.md用curl或wget直接下载curl -o setup.md https://raw.githubusercontent.com/example/monorepo/main/docs/setup.md这个办法最简单直接适合快速拿文件不需要本地安装任何Git工具。Gitee、GitLab 也有类似的 raw 链接只是 URL 格式略有不同。Gitee 的格式大致是https://gitee.com/example/monorepo/raw/main/docs/setup.mdGitLab 的格式大致是https://gitlab.com/example/monorepo/-/raw/main/docs/setup.md如果你记不住这些格式还有一个笨办法在仓库网页上打开目标文件点击右上角的 Raw 按钮浏览器地址栏里就是 raw 链接复制下来用即可。5.2 指定标签或提交版本如果不想拿分支最新版想拿某个 tag 或某次提交的文件直接把链接中的分支名替换掉就行https://raw.githubusercontent.com/example/monorepo/v1.2.3/docs/setup.md https://raw.githubusercontent.com/example/monorepo/e5f4a21/docs/setup.md这个工作在本地用浅克隆加git show也一样能实现但如果只想拿一个文件直接改 URL 显然更省事。5.3 GitHub API方式GitHub 还提供了 API可以通过接口拿到文件内容同时能附带一些元信息。比如curl -H Accept: application/vnd.github.raw \ https://api.github.com/repos/example/monorepo/contents/docs/setup.md这种方式适合你在脚本里动态读取多个文件或者需要根据分支名、PR 信息去拼URL的场景。缺点是 GitHub API 有访问频率限制未认证的情况下每小时只有60次请求拿一个文件无所谓批量拉取注意别超限。5.4 zip包下载目录级的整体获取如果你要的不只是一个文件而是一整个目录还有一个介于“克隆”和“raw”之间的办法——直接下载仓库的zip压缩包。GitHub 的界面里有一个 Code 按钮里面自带 Download ZIP。不过要注意这个下载的是全仓库快照不是只下载某一个目录。对于 Gitee你可以直接在仓库页面的「下载」功能里选分支然后下载整个zip。如果你想只下载某个目录GitHub 网页端没有一键按钮但可以通过第三方工具如 DownGit 实现搜索“download github directory”就能找到。我个人对第三方工具持保留态度毕竟它们可能涉及把公开仓库的数据转发到第三方服务器安全性要自己掂量。生产环境的脚本我一般还是用 Git 或官方 API。5.5 文件级需求要谨慎选择方案最后给个建议如果你拿文件只是为了“看一眼”或“配个环境”raw链接是完全够用的如果是想在本地对文件做版本管理、参与项目开发那就要用 Git 克隆。开发场景里从 raw 链接下载文件再扔进自己的另一个仓库很容易丢失文件的历史、来源和归属后面排查问题会很痛苦。6. 实测数据与避坑记录6.1 同一仓库三种克隆方式实测对比为了回答“到底快多少、省多少”我在一个真实仓库上做了一组对比。这个仓库全量体积约2.2GB历史提交接近9000条文件数量超过6万是一个非常典型的大型仓库。网络环境是普通的办公室有线网络。结果如下克隆方式用时克隆后 .git 体积工作区文件全量克隆约4分30秒约2.1GB全部稀疏检出不加其他参数约4分25秒约2.1GB仅指定目录浅克隆--depth 1约1分20秒约600MB全部浅克隆稀疏检出约50秒约580MB仅指定目录浅克隆 blob:none 稀疏检出约20秒约15MB仅指定目录最后一种方式第一次git sparse-checkout set apps/mobile之后会进入按需拉取状态第一次完整打开某个文件时后台会去远程下载对应文件内容整体体验非常流畅。而且因为只显示一个目录工作区文件数量从原来的6万多个降到了几百个IDE 打开项目的速度和索引速度都明显变快。强调一下以上数据和我当时的网络状况强相关不代表所有仓库都一定符合这个量级但“能省多少”的趋势是确定的。6.2 坑一设置了稀疏检出后工作区是空的这个坑几乎每个新手都会踩。有时候执行完git sparse-checkout set apps/mobile发现工作区一片空白连目录都没创建。这通常是因为在设置稀疏检出的时候本地索引里还是空的或者指向的提交不带你需要的目录。解决办法也很简单执行git checkout main或者git restore --staged --worktree .强制让Git根据当前 HEAD 重新展开工作区。执行完之后指定目录就会出现。如果还是空白检查一下你的HEAD指向的分支是否存在以及目录路径在仓库根目录下的写法是否正确。6.3 坑二sparse-checkout 后想提交代码但同事没有用稀疏检出这个场景很常见你自己用了稀疏检出只改了apps/mobile下面的代码然后提交推送。同事没有做任何设置他拉取你的提交时会发现仓库里只多了你改的那一两个文件而他已经检出的目录内容不会因此消失。所以稀疏检出对提交的影响其实很小因为你每次提交都会基于完整对象库生成新的树对象。但有一种情况要小心你用稀疏检出把某个目录藏在本地不看然后不小心在根目录下新建了一个和你同事开发的目录同名的新文件夹这会导致提交时目录冲突。遇到这种情况先git status看清楚自己改了哪些路径别无脑git add .。如果你担心稀疏检出的目录和同事的改动产生交叉影响建议提交前执行一次git fetch origin git status确认本地变更只涉及自己负责的目录再走正常提交流程。6.4 坑三partial clone 模式下blame 和 diff 突然很慢我刚才提到--filterblob:none是按需拉取文件对象。你平时写代码时可能感觉不到但一旦执行git log -p git diff HEAD~1 HEAD git blame src/main.tsGit 会去远程仓库“补货”大量历史文件内容需要逐个下载速度明显变慢如果网络不好甚至报错。我的经验是只读场景用 partial clone开发提交场景用全量克隆。如果你为了省空间不得不用 partial clone又希望某些命令能跑得舒服可以用git fetch --refetch --filterblob:limit1m origin把1MB以上的大文件对象也拉回来但这条命令会重新下载不少对象视仓库情况慎用。6.5 坑四稀疏检出遇到子模块submodule如果你的仓库使用了 Git submodule那稀疏检出默认不会处理子模块目录。也就是说你设置了sparse-checkout set apps/mobile但这个目录里如果包含子模块子模块内容可能不会出现在工作区。碰到这种情况你可以单独对子模块做一次初始化git submodule init git submodule update --depth 1但要注意如果子模块体积也很大这个操作同样会拉取子模块的全量或部分内容。如果远程仓库的子模块路径不固定我甚至建议考虑用专门脚本把子模块作为独立的 Git 仓库来处理而不是把希望寄托在父仓库的稀疏检出上。6.6 坑五老版本Git命令失效开头我就强调过 Git 版本问题。很多人用的还是系统自带的 Git 2.17 甚至更老的版本git sparse-checkout命令根本不存在。如果你无法升级Git就用前面提到的老式规则文件方式git config core.sparseCheckout true echo apps/mobile/ .git/info/sparse-checkout git read-tree -mu HEAD但话说回来老版本功能毕竟有限特别是和 partial clone 的配合不好我强烈建议你升级。这里也回应一下热词里的“git安装及配置教程”Git 升级本身不复杂但升级后要注意环境变量和全局配置的迁移特别是旧的 SSH Key 路径不要弄丢。6.7 我的推荐组合用一句话总结我实际工作中的选择只是想快速看代码、部署脚本、CI 拉产物时用git clone --depth 1 --filterblob:none --sparse加git sparse-checkout set。长期开发、需要完整历史、会在本地提交时用git clone --sparse加git sparse-checkout set不要加--depth和--filter。只需要某一个文件时直接用 raw 链接或 API不折腾 Git 克隆。公司内部仓库服务端如果太老不支持 partial clone那就退一步用--depth 1 --sparse组合虽然下载量不如blob:none极限但也能省不少时间。7. 最后再分享一个实际使用中的小技巧我在自己的部署脚本里会把“只克隆某目录”和“定期更新”结合起来。流程是第一天用克隆命令把仓库拉到构建目录后续每天执行更新时只要做两件事git fetch --depth 1 origin main git sparse-checkout set apps/mobile git rebase origin/main这样能让构建目录始终停留在那个子模块的最新状态不会因为其他目录的频繁提交而膨胀。还有一个细节如果你用的是 Windows注意路径分隔符。在.git/info/sparse-checkout规则文件里路径一律使用正斜杠/反斜杠\会导致匹配失败。我之前在 Windows 上踩过这个坑规则写成了apps\mobile\结果工作区一片空白花了好一会儿才反应过来。总的来说Git 虽然默认做全量克隆但它的机制仍然留出了足够的空间给我们按需裁剪。稀疏检出、浅克隆、对象过滤这三个基础能力用好了大部分“只想要一个目录”的场景都能轻松解决。如果哪天你发现某个仓库克隆起来特别痛苦记得先试试这篇文章里的组合而不是硬等那个几十GB的体积慢慢下载。

Git只克隆某个目录：稀疏检出、浅克隆与部分克隆实战指南

相关推荐

GitHub README 图片排版完全指南：上传、引用与居中同行实操

Sanity 中的静态 JSX 提升：rendering-hoist-jsx 规则的原理、正确写法与仓库源码实证

火狐浏览器授权安全测试：8款常驻插件与配置维护指南

更多资讯

CivitAI 的 `dbRead`/`dbWrite` 双客户端路由：当服务层在运行时选择数据库客户端时，测试 mock 如何正确拆分

2026年硕博新生报到须知及新生入校相关注意事项汇总

查aigc免费网站靠谱吗？准确率98.54%的AI率报告带编号可核验，查重报告没有

aigc检测器哪个学校在用？中南大学、湘潭大学等高校AI率查重系统清单

Oracle 11g透明网关访问SQL Server：从安装配置到排错完整指南

STM32CubeMX生成IAR工程实战指南：配置、编译与常见坑

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？