Git 大仓库工作区优化
大仓库变慢时，先别急着拆仓库
一次线上热修需要保持当前功能分支，又要检出发布分支复现问题。开发者先 stash，切分支后发现依赖目录被重写；另一个人为了节约磁盘使用 sparse-checkout，却发现 clone 下载量几乎没变；第三个人用了 --filter=blob:none，入场很快，断网后一次 git blame 却卡在取对象。
三个现象分别发生在不同层：
Worktree 增加同一仓库的并行工作区，解决反复切分支和多个 index 互相干扰。Sparse checkout 收窄某个工作树中呈现的 tracked path，解决文件遍历、IDE 索引和开发者注意力成本。Partial clone 让服务端暂不发送某些可达对象，解决首次或后续 fetch 的对象传输量。
它们可以组合，却不能互相替代。工作区少不代表对象少，文件看不见不代表没有读取权限，首轮下载少也不代表长期网络请求少。架构选型的起点不是“仓库很大”，而是先测清时间花在工作区切换、文件系统遍历、index、对象下载、构建还是 IDE。
三层模型：工作树、索引与对象库
Worktree 共享什么，隔离什么
一个普通非裸仓库有主工作树，还可以附着多个 linked worktree。git-worktree 说明 linked worktree 与主仓库共享对象库、大多数 refs 和默认仓库配置，但拥有各自的 HEAD、index、工作区状态以及部分伪引用。
git worktree add -b hotfix/payment ../payment-hotfix HEAD
git worktree list --porcelainlinked worktree 顶层 .git 是指向管理目录的文本文件。不要写脚本假设 .git 一定是目录：
git rev-parse --git-dir
git rev-parse --git-common-dir
git rev-parse --git-path HEAD
git rev-parse --git-path objects在两个工作树里，--git-dir 和 HEAD 路径不同，--git-common-dir 与对象库最终指向同一公共管理区。同一个本地分支默认不能同时检出到两个工作树，因为两个独立 index 若同时推进同一引用，结果不可控。
共享对象库节约磁盘和下载，也扩大故障半径：对象损坏、磁盘耗尽、错误 gc 或公共配置变更会影响全部工作树。构建输出、依赖安装目录、端口和测试数据库则通常需要按工作树隔离。
Sparse checkout 改变的是工作树呈现
稀疏检出使用 index 中的稀疏状态和规格决定哪些 tracked path 出现在磁盘。优先使用 cone mode，以目录为输入：
git sparse-checkout set --cone services/payment shared
git sparse-checkout list这不会删除提交中的其他路径，也不会限制 git show HEAD:path 读取历史。它更不是权限系统。真正的保密边界仍由仓库拆分和服务端授权承担。
需要文件级或复杂模式时可以使用 non-cone mode，但其模式接近 gitignore 语义，性能和认知成本更高。Git 在 sparse-checkout 手册 中持续记录命令与其他操作的行为差异；团队应通过 set、add、reapply、disable 管理规格，不直接编辑内部文件。
Partial clone 改变的是对象传输
Partial clone 设计 允许服务端按 filter 省略部分本应可达的对象，本地把相应远端标记为 promisor remote，在命令需要缺失对象时补取。常见的 blob:none 保留 Commit 和 tree，延迟文件内容 blob：
git clone --filter=blob:none <remote-url> repoblob:limit=<size> 只延迟大于阈值的 blob；tree filter 可能节省更多初始对象，但增加路径遍历和兼容复杂度。--depth、--single-branch 与 filter 不是一回事：前者限制提交图或引用范围，filter 限制选定提交范围中的对象类型。
判断本地是否为 partial clone：
git config --show-origin --get extensions.partialClone
git config --show-origin --get remote.origin.promisor
git config --show-origin --get remote.origin.partialCloneFilter
git rev-list --objects --all --missing=printpromisor 语义让 Git 能区分“承诺可补取的缺失对象”和普通损坏，但承诺最终依赖网络、认证、远端保留与服务端实现。一次成功 clone 不能证明离线构建和长期使用成立。
启用顺序与关键配置
三项能力都内置于 Git CLI。先确认实际执行版本和命令帮助，不把另一台机器的能力当成本机事实：
git --version
git worktree -h
git sparse-checkout -h
git clone -h增加并行工作树
明确创建分支适合持续开发：
git worktree add -b topic/payment ../payment-worktree HEAD一次性审查可使用 detached HEAD：
git worktree add --detach ../release-inspect origin/main路径位于移动硬盘或暂时离线挂载时，可以锁定以避免元数据被 prune：
git worktree lock --reason "portable review disk" ../release-inspect
git worktree unlock ../release-inspect工作树专属配置需要显式启用仓库格式扩展：
git config extensions.worktreeConfig true
git config --worktree example.runtimePort 18081
git config --worktree --get example.runtimePort启用后配置保存在各工作树的 config.worktree，旧 Git 可能拒绝访问该仓库。官方文档还要求检查 core.worktree、core.bare、core.sparseCheckout 等不应错误共享的配置。团队在启用前必须验证最低 Git 版本和回退重建路径。
收窄当前工作树
git sparse-checkout set --cone services/payment shared build-tools
git sparse-checkout list某些命令会让规格外路径临时重新出现，或本地修改阻止 Git 更新稀疏状态。先保护用户数据，再执行：
git status --short --ignored
git sparse-checkout reapply大 index 可试点 sparse index：
git sparse-checkout set --cone --sparse-index services/payment shared build-tools它会用稀疏目录项压缩范围外 index。Git CLI 可以展开这些目录项，但 IDE、扫描器和旧脚本未必兼容。出现问题可切回 --no-sparse-index，不必放弃稀疏工作树。
克隆时同时减少对象与文件
git clone --filter=blob:none --sparse <remote-url> payment-repo
cd payment-repo
git sparse-checkout set --cone services/payment shared build-toolsgit-clone 的 filter 说明 明确 blob:none 会把 blob 延迟到 Git 真正需要时。远端必须通过协议广告 filter 能力；若不支持，客户端可能警告 filtering 未识别或得到接近完整 clone 的结果。
若仓库还有子模块，顶层过滤器默认不等于递归过滤。只有经过验证后才使用：
git clone --filter=blob:none --recurse-submodules --also-filter-submodules <url> repo它会把 promisor、凭证、代理和离线风险扩展到每个子仓库。
可复制的组合正反实验
实验使用本地裸远端并通过 file:// 走上传包协议。直接把本地路径传给 clone 可能触发本地优化，绕过 filter 协商，不能证明 partial clone 行为。
建立包含大小 blob 的远端
mkdir git-scale-lab
cd git-scale-lab
git init --initial-branch=main source
git -C source config user.name "Example Developer"
git -C source config user.email "developer@example.invalid"
mkdir -p source/services/payment source/services/search source/shared
printf "payment-v1\n" > source/services/payment/app.txt
printf "search-v1\n" > source/services/search/app.txt
printf "shared-v1\n" > source/shared/lib.txt
git -C source add .
git -C source commit -m "feat: initialize scale lab"
git clone --bare source remote.git
git -C remote.git config uploadpack.allowFilter true
git -C remote.git config uploadpack.allowAnySHA1InWant trueuploadpack.allowFilter 只用于本地实验远端。生产服务端应按托管平台或 Git 服务的受支持配置管理，不能让开发者随意修改。
正例：partial clone 加 cone mode
在 POSIX shell 或 Git Bash 中取得绝对 file URL：
git clone --filter=blob:none --sparse "file://$PWD/remote.git" client
git -C client sparse-checkout set --cone services/payment shared
git -C client sparse-checkout list
git -C client config --get remote.origin.promisor
git -C client config --get remote.origin.partialCloneFilter预期目录列表为 services/payment 和 shared，promisor 为 true，filter 为 blob:none。继续检查工作树和索引：
test -f client/services/payment/app.txt
test ! -e client/services/search/app.txt
git -C client ls-files services/search/app.txt最后一条仍会列出 search 文件，因为 sparse checkout 没有从历史或 index 逻辑中删除它，只是不把它呈现在工作树。
反例：把稀疏检出当权限
git -C client show HEAD:services/search/app.txt预期仍输出 search-v1，必要时从 promisor remote 补取 blob。这是可复制的反证：看不见路径不等于无权读取。敏感模块不能靠 sparse pattern 隔离。
正例：两个 worktree 拥有独立 index
git -C client worktree add -b topic/payment ../client-review HEAD
git -C client worktree list --porcelain
git -C client rev-parse --git-common-dir
git -C client-review rev-parse --git-common-dir
git -C client rev-parse --git-path index
git -C client-review rev-parse --git-path index两个 --git-common-dir 指向同一个公共管理区，两个 index 路径不同。修改 linked worktree：
printf "review\n" >> client-review/services/payment/app.txt
git -C client status --short
git -C client-review status --short预期主工作树保持干净，只有 linked worktree 报告修改。这证明工作区与 index 隔离；对象库和普通分支引用依然共享。
反例：同一分支不能重复检出
git -C client worktree add ../duplicate topic/payment预期命令非零退出，并提示 topic/payment 已在另一个工作树检出。修复方式是复用现有路径、创建新分支或使用 detached HEAD，不是用 --force 掩盖所有权。
验证按需对象与离线风险
git -C client rev-list --objects --all --missing=print
git -C client show HEAD:services/search/app.txt
git -C client rev-list --objects --all --missing=print第一次列表可能以 ? 标记尚未取得的对象，读取后对应 blob 应已在本地。要验证离线场景，应在受控实验中临时把 origin 改为不可达地址，再读取一个尚未补取的 blob，保留退出码和 stderr，随后恢复 URL。不要在真实仓库删除凭证或破坏代理来模拟。
按语义清理
git -C client-review restore services/payment/app.txt
git -C client worktree remove ../client-review
git -C client branch -D topic/payment
git -C client sparse-checkout disable
git -C client worktree prune --dry-run --verbose
cd ..
rm -rf git-scale-labPowerShell 最后一条改用 Remove-Item -LiteralPath .\git-scale-lab -Recurse。删除前确认绝对路径确实是实验目录。不要先用文件管理器删 linked worktree，再让 Git 猜元数据状态。
项目接入：从真实大仓库建立基线
先建立完整 clone 对照组，记录这些指标：
| 指标 | 解释 | 可能对应的手段 |
|---|---|---|
| clone/fetch 网络字节与耗时 | 对象传输成本 | partial clone、镜像、协议与服务端优化 |
| checkout 文件数与耗时 | 工作树写入成本 | sparse-checkout |
index 大小、status P50/P95 | index 和文件遍历成本 | cone mode、sparse index、文件系统监视器 |
| 同时活跃任务数、切换耗时 | 工作区冲突成本 | worktree |
| IDE 首次索引与稳态延迟 | 工具链读取范围 | sparse 模板、IDE 配置 |
| lazy fetch 次数与失败率 | 延迟对象的长期代价 | 预热、完整 clone、代理与凭证治理 |
| 全库构建和扫描成功率 | 稀疏范围是否形成依赖闭包 | 补齐目录、保留完整 CI 环境 |
推荐按风险从低到高推进：
用 worktree 解决热修、评审复现和长期分支并行，先隔离构建目录、端口和依赖缓存。为高稳定度的一组顶层目录建立 cone mode 模板，验证 IDE、构建、测试、代码生成和清理脚本。对 index 明显成为瓶颈的试点启用 sparse index，并保留旧 Git/外部工具兼容矩阵。
服务端确认 filter 后再试点 blob:none，同时测首次节省、稳态 lazy fetch、离线失败和代理连接数。把启用、扩展、退出和完整副本重建写入项目脚本，但脚本只调用稳定 Git 子命令，不直接修改 .git 内部结构。
典型项目入口可以是可选脚本，而不是强制每个人复制命令：
git sparse-checkout set --cone services/payment shared build-tools
git sparse-checkout reapply脚本不得写开发者绝对路径、远端凭证或个人工作树位置。团队可约定 worktree 根目录与命名规则，但创建命令应接收本机可写路径。
常用操作与恢复
Worktree 生命周期
git worktree list --porcelain
git worktree add -b topic/example ../example HEAD
git worktree add --detach ../inspect origin/main
git worktree move ../example ../example-renamed
git worktree lock --reason "offline disk" ../inspect
git worktree unlock ../inspect
git worktree remove ../example-renamed
git worktree prune --dry-run --verbose
git worktree repair目录被手工移动后优先 move 或 repair。目录消失而列表显示 prunable 时，先用 prune --dry-run --verbose 确认将删除的记录；挂载盘只是暂时不在线时应 lock，而不是 prune。
Sparse 范围调整
git sparse-checkout list
git sparse-checkout set --cone services/payment shared
git sparse-checkout add build-tools
git sparse-checkout reapply
git sparse-checkout disableset 替换规格，add 扩展规格，disable 恢复完整工作树。若范围外有 untracked 文件，Git 不会为了稀疏化静默删除用户数据；先用 status --short --ignored 分类，再决定迁移或清理。
Partial clone 诊断
git count-objects -vH
git rev-list --objects --all --missing=print
git config --show-origin --get-regexp '^(extensions\.partialClone|remote\..*\.(promisor|partialCloneFilter))$'
GIT_TRACE=1 GIT_TRACE_PACKET=1 git fetchtrace 可能包含远端地址、引用、用户名和认证上下文。只在受控环境短时启用，脱敏后保存，并设置日志保留期。不要把 trace 永久打开到公共 CI。
对 blobless clone，较新的 Git 提供 git backfill 预取缺失 blob，并可结合 sparse 规格。团队不能只因命令出现在某版文档就直接加入脚本，应先检查最低客户端、服务端行为、磁盘增量和回退方案；旧基线可通过实际读取所需历史或重建完整 clone 达到离线准备。
常见失败与判断证据
分支已在另一个工作树检出
证据：git worktree add 或 git switch 非零退出，路径和分支出现在 git worktree list --porcelain。
这是 Git 对共享分支引用的保护，不是锁文件残留。复用对应工作树，或为新任务创建独立分支/detached HEAD。仅当确认原工作树已经失效时，才按 repair/prune 流程修复元数据。
工作树目录不存在但列表仍有记录
git worktree list --porcelain
git worktree prune --dry-run --verbose先区分误删、搬迁和离线挂载。搬迁用 repair，可移动设备用 lock；确认不可恢复后再 prune。直接删除 $GIT_COMMON_DIR/worktrees 会丢失 HEAD、index 与恢复证据。
稀疏范围外仍有文件
git status --short --ignored
git sparse-checkout list
git sparse-checkout reapply常见原因是 untracked/ignored 文件不能被静默删除，或某命令临时 materialize 了 tracked path。保护本地数据后 reapply。若构建持续需要范围外路径，说明 sparse 模板不是依赖闭包，应修正模板，而非反复清理输出。
--filter 被忽略或 clone 仍然很大
查看 clone 的 warning、promisor 和 filter 配置，再比较对象类型与字节：
git config --get remote.origin.promisor
git config --get remote.origin.partialCloneFilter
git count-objects -vH服务端未开放 filter、本地路径 clone 绕过协议、仓库体积主要来自 Commit/tree，或 filter 与对象分布不匹配，都会降低收益。使用 file:// 只适合受控实验；生产判断必须基于实际托管服务和真实数据画像。
本地命令突然要求网络或凭证
show、diff、blame、checkout、merge 或构建都可能触发 missing object 补取。先确认 partial clone，再用 rev-list --missing=print 判断对象状态。401/403、SSH 拒绝、代理 407 和 TLS 错误属于传输身份链；missing blob 并不等于对象库普通损坏。
Sparse index 下 IDE 或扫描器漏文件
先用 Git CLI 对比 status、ls-files 和构建结果，再切回普通 index：
git sparse-checkout set --cone --no-sparse-index services/payment shared build-tools若问题消失，说明外部工具不能正确处理 sparse directory entry。将该版本加入兼容矩阵，在修复前不要向全团队启用 sparse index。
代理 / 权限 / 凭证与敏感数据
Worktree 与 sparse-checkout 主要是本地能力，不新增远端权限；partial clone 的初次传输和每次 lazy fetch 都沿用远端 HTTPS/SSH 认证、代理和授权。
Sparse checkout 不是 ACL。能 fetch 某个 Commit 的账号通常仍能读取规格外对象，敏感路径必须拆到受控仓库或由服务端授权隔离。Partial clone 可能在看似本地的命令中触发远端访问，短期 token、SSO 会话和代理必须覆盖整个开发时段，而不是只验证 clone 当刻。不把 PAT、SSH 私钥或带凭证 URL 写入初始化脚本、Git 配置模板和 trace。凭证交给系统凭证库、agent 或平台身份机制。
promisor remote 是缺失对象的信任来源。变更 URL、镜像或认证时，要验证对象一致性和故障回退，不能只看默认分支。多 worktree 共用对象与多数仓库配置。对公共配置、maintenance、gc 和 alternates 的变更必须按仓库审查，而不是当成单个目录的个人设置。构建输出、测试数据和 .env 应按工作树隔离并保持忽略。并行工作树复用同一端口、数据库 schema 或缓存 key 会产生代码之外的互相污染。
packet trace 和性能采样可能泄漏仓库 URL、分支名和业务路径。采集最小化、访问控制、脱敏和到期删除必须同时落地。
架构选型与成本模型
| 现场 | 首选 | 不应期待它解决 |
|---|---|---|
| 同时维护热修、功能和评审复现 | Worktree | clone 带宽、index 规模、权限隔离 |
| 只开发稳定的少数目录，文件遍历和 IDE 索引昂贵 | Cone-mode sparse checkout | 历史对象下载、模块保密、构建依赖自动发现 |
| 大量历史 blob 很少被读取，远端与网络稳定 | blob:none partial clone | 工作树文件数、长期离线、服务端容量本身 |
| 大 blob 超过 Git 协作模型 | Git LFS 或制品仓库 | 仅靠 sparse/filter 解决版本与分发治理 |
| 模块权限必须隔离 | 仓库拆分和服务端 ACL | Sparse checkout |
| 构建任务和远程缓存是主要瓶颈 | Monorepo 构建系统治理 | Git 工作区技巧 |
Worktree 的直接成本是每个工作树的文件、index、依赖和构建输出；对象库只存一份。Sparse checkout 降低磁盘文件和工具遍历，但模板维护、依赖闭包和工具兼容有持续成本。Partial clone 减少首轮传输，却增加 promisor 服务负载、lazy fetch 延迟、代理连接和离线准备。
决策应比较完整周期：首次 clone、首个可编辑时刻、首个成功构建、日常 status、历史查询、分支切换、离线工作、升级与清理。只展示“clone 快了 60%”而不测后续补取和失败率，会把网络成本从可预测入场推迟到不可预测的开发中途。
团队落地与长期维护
仓库 owner 维护推荐 sparse 目录、服务端 filter 能力、最低 Git 版本和完整副本策略；开发体验 owner 验证 IDE、构建、测试、生成器和扫描器；平台 owner 管理代理、凭证、镜像、maintenance 和容量；开发者负责每个工作树的 dirty state、生命周期和本地敏感数据。
持续度量至少包括：
完整与优化 clone 的 P50/P95 时间、网络字节和失败率。checkout 文件数、index 大小、status 与 IDE 索引延迟。每日 lazy fetch 次数、补取字节、认证失败和代理重试。
Worktree 数量、无 owner 的遗留目录、构建缓存与磁盘水位。稀疏环境和完整环境的构建、测试、安全扫描差异。Git/IDE 升级后的兼容回归和支持工单。
每个团队至少保留一条完整 clone 的 CI 路径。稀疏环境负责提高开发效率，完整环境负责发现跨目录依赖、生成器遗漏和全库治理问题。Partial clone 也需要定期验证远端不可用、凭证过期和离线预热，不能把 promisor 承诺当成备份。
落地工程深水区：组合后出现的新风险
Worktree 让本地并行变快，也让共享故障变大
对象损坏、公共 refs 异常、磁盘耗尽和错误 maintenance 会同时影响所有 linked worktree。事故时只在一个目录反复 reset 不能修复公共对象库，反而可能覆盖独立 index 证据。先收集 worktree list、fsck、磁盘和配置来源，再按仓库统一恢复。
Sparse 目录不是构建依赖图
cone mode 只理解路径，不知道代码生成、schema、测试发现、运行时资源和根配置。推荐模板必须来自真实构建证据，并随着依赖变化更新。若每次开发都要手工 add 新目录，说明模板或仓库边界已经失真。
Lazy fetch 把稳定网络变成命令隐含依赖
完整 clone 把下载集中在入场阶段；partial clone 可能让 blame、diff、merge 和构建在数小时后发起网络请求。高延迟代理、短 token、远端限流会制造许多小停顿。架构师要同时衡量首轮节省与稳态请求放大，并为离线人员提供 backfill、预热或完整副本。
组合配置具有工作树边界
每个 worktree 可以有不同 sparse 规格，而仓库配置默认共享。错误共享 core.sparseCheckout 或直接编辑公共 $GIT_DIR/info/sparse-checkout，可能让另一个工作树被意外收窄。需要 per-worktree 配置时采用 extensions.worktreeConfig，并先验证旧客户端拒绝策略和修复方法。
清理自动化最容易越权
脚本按目录年龄直接 Remove-Item，可能删除 dirty worktree；自动 prune 可能清掉暂时离线的挂载；激进 gc 可能和长任务争用公共对象库。清理顺序应是确认 owner、检查 dirty state、lock/repair 判断、remove、prune --dry-run，最后才处理目录。任何递归删除都应校验解析后的绝对路径位于受控根目录。
已用实测把工作区切换、工作树文件、index、对象传输、构建和 IDE 瓶颈分开。每个 linked worktree 有 owner、用途、独立分支或 detached 依据、命名和清理期限。团队理解对象库与普通 refs 共享，HEAD、index 和工作区状态按 worktree 隔离。
构建输出、依赖缓存、端口、数据库和测试数据不会跨工作树互相污染。Sparse 模板采用 cone mode 起步，并通过 IDE、构建、测试、生成器和扫描器验证。团队明确 sparse checkout 不是权限控制，规格外对象仍可能被读取。
Sparse index 只对兼容客户端和工具启用，存在 --no-sparse-index 回退路径。服务端 filter、promisor 配置、按需补取、代理、凭证和远端限流均有实测证据。已测断网或远端不可用场景，并为离线工作准备预热、backfill 或完整 clone。
Trace、远端配置和脚本不含 token、私钥、内网地址或无需共享的业务路径。worktree remove、repair、prune --dry-run、sparse-checkout disable 均完成可恢复演练。保留完整 clone 对照与全库 CI，不用局部成功替代仓库级验证。
P50/P95、网络、lazy fetch、磁盘、兼容性和支持工单进入持续度量。当瓶颈属于构建图、权限边界或制品分发时，已转交对应架构方案，而不是继续叠加 Git 参数。