Git只拉取分支中特定文件夹的实操

必须启用cone模式，因非cone模式需手动写完整路径规则、不支持递归通配符且易出错；正确流程是先git sparse-checkout init --cone，再用set或add添加目录路径，结尾斜杠可选但建议统一。

git sparse-checkout 只拉指定文件夹必须开 cone 模式

默认 sparse-checkout 是“非 cone”模式，它要求你手动写完整路径规则，且不支持通配符递归（比如 src/* 会失败）。实际中几乎没人用非 cone 模式——容易漏文件、难维护、git read-tree -mu HEAD 容易报错。

正确做法是初始化时加 --cone 参数，它启用简化规则：路径末尾加 /* 表示该目录下所有内容（含子目录），不加则只匹配单个文件或空目录。

• git sparse-checkout init --cone 是必须的第一步，不能跳过
• 之后再用 git sparse-checkout add src/ docs/ 添加路径，注意结尾斜杠可选但建议统一加（src/ 和 src 效果相同）
• 如果之前没 init 过，直接 echo "src/" >> .git/info/sparse-checkout 会无效——因为 config 没开 sparseCheckout，也不会自动创建 .git/info/sparse-checkout

拉取前必须先 fetch 再 pull，不能跳过 fetch

很多人执行 git pull origin main 后发现文件夹没出来，其实是 pull 前没 fetch 到远程最新提交。sparse-checkout 只影响工作区检出，不改变 fetch 行为。

标准流程是：

• git remote add origin <url>（如果还没关联）
• git fetch origin main（明确 fetch 目标分支，避免默认拉所有分支）
• git sparse-checkout set src/ tests/（推荐用 set 而不是 add，它会覆盖旧规则并自动重置工作区）
• git checkout origin/main 或 git switch -c main --track origin/main（创建本地分支并检出）

注意：git pull = fetch + merge，而 sparse-checkout 下 merge 可能因缺失文件导致冲突或静默失败，所以更安全的是 fetch + checkout。

文件夹路径写错会导致检出为空，且无提示

sparse-checkout 不校验路径是否存在，src/frontend 写成 src/frontent 或 frontend/（忘了父目录），执行 git checkout 后工作区就是空的——连 .git 外壳都没，看起来像“什么都没拉下来”。

排查方法：

• 先确认远程分支里真有那个路径：git ls-tree -d origin/main -- src/（-d 只列目录）
• 检查 .git/info/sparse-checkout 文件内容是否和 git ls-tree 输出一致
• 运行 git sparse-checkout list 看当前生效规则（Git 2.32+ 支持）
• 临时关 sparse-checkout：git config --unset core.sparsecheckout，再 git read-tree -mu HEAD 看能否完整检出——用来判断是不是路径问题还是权限/网络问题

git archive 更适合一次性导出，别当成工作流替代方案

有人看到 git archive --format=zip --output=out.zip origin/main:src/ 能快速拿到文件夹，就以为这是“拉取”的正解。但它生成的是快照 ZIP，不带 Git 历史、不能 commit、不能 push，也不能跟踪后续变更。

适用场景很窄：

• CI/CD 中构建时提取源码片段（比如只打包 dist/ 发布）
• 给非开发者发一份静态代码包
• 你确定永远只读、不改、不提交回仓库

只要需要后续 git add / commit / push，就必须走 sparse-checkout 流程——archive 是快照，sparse-checkout 是活的工作区。

真正容易被忽略的是：sparse-checkout 初始化后，.git 目录里依然存着完整对象数据库（只是工作区不展开），所以磁盘占用不会明显减少；如果目标真是“节省空间”，得配合 shallow clone（--depth 1）一起用，但要注意 shallow 仓库不能 push，也不能 checkout 其他分支。