> 版本控制的边界要跟着"什么在变"走，不是跟着目录大小走

Research Tools Beginner 2026-10-08 05:57 2026-10-08
#tooling #provenance #git #backup #failure-modes

自建工具链常见的一种错配：指针那层在版本控制里，逻辑那层不在。

// TABLE_OF_CONTENTS

结论先行

自建工具链常见的一种错配：指针那层在版本控制里，逻辑那层不在。

一次实测的分布：

层 内容 大小 在 git 里
技能定义 ~/.claude/skills 43 个 SKILL.md，主要是调用说明 5 MB ✅
后端实现 ~/Tools 这些技能真正执行的 Python 15 GB ❌

结果是：一天里改的两千多行后端代码，磁盘上只有一份。 提交技能仓库看起来"存档了这轮工作"，实际存的是一堆指向未存档代码的路径。

后来按白名单建了仓：跟踪 121 个文件、1.1 MB 文本。 15 GB 里剩下的全是别人的代码、模型资产和虚拟环境。

原因不是判断失误，是默认值：小目录顺手 git init 了， 大目录（内含 13 个第三方 git 仓库、单个子目录 7 GB）没人敢 init，于是一直裸着。

为什么

「太大所以不能进版本控制」这个推理有一步是错的： 大的是别人的代码和数据，不是你的。自研工具目录本身通常只有几百 KB 的文本。

正确的切法是白名单，不是黑名单：

# 默认什么都不跟踪
*
# 只放行自研的工具目录
!/notation-check/
!/self-review/
!*/*.py
!.gitignore

黑名单（.gitignore 里逐条排除大目录）迟早会漏—— 下次 clone 一个新的第三方仓库进来，它不在黑名单里，就进了历史。 而白名单漏的方向是安全的：漏了只是没跟踪，补一行就行。

顺带两条同源的卫生：

  • 第三方目录要有 UPSTREAM-SOURCE.txt，否则将来会被误当自研去改， 升级时冲突；或者反过来被当 vendored 删掉。
  • 提交之前扫一遍明文凭据。 一次真实的 artifact 检查在真实项目里查出 多处明文 SSH 口令已经进了 git——进了历史就删不干净了。

怎么用

一句话自查：我今天改的代码，在哪个仓库的哪个 commit 里？ 答不上来就是这个毛病。

按「什么在变」重划边界：

  1. 列出最近一个月改动过的文件，看它们分别落在哪个仓库。
  2. 改得最多、却没有仓库的那一层，就是要补的那一层。
  3. 用白名单 .gitignore 建仓，第一次提交前跑一遍卫生检查 （.gitignore 缺口 · 被跟踪的大文件 · notebook 输出 · 明文凭据）。
  4. 建完补一条自检项，验证"每个被技能声明的后端都在版本控制里"—— 否则半年后又会漂回去。见 手写的自检清单永远是全绿的——它只包含你刚修过的东西。

出处

  • ~/Tools（15 GB，47 个顶层目录，13 个内嵌 git 仓库）→ 2026-09-06 按白名单建仓， 121 个文件、1.1 MB；.gitignore 的写法与刻意留在白名单外的清单见 ~/Tools/TOOLS_REWRITE_PLAN_2026-09-06.md 的 T12 一节
  • ~/.claude/skills/repo-hygiene/：.gitignore 缺口 / 大文件 / notebook 输出 / 许可证 / 来源标记
  • 明文口令那次：~/Tools/TOOLS.md 2026-09-05 第二轮记录
  • 同一类失效：最危险的工具故障是"静默少做"——技能在、后端不在
< BACK_TO_NOTES()