部分子模块管理 xiongjiamu/dsh-gitmodules-dir

dsh-gitmodules-dir

DeepSeek Harness(dsh)的 git-partial-submodule bundle:让 dsh 用户无需手搓底层 git 命令,就能添加、克隆和管理部分 git submodule —— blobless 部分克隆 + sparse checkout。本 bundle 包装了 git-partial-submodule 项目(Apache-2.0): 上游单文件 Python 脚本被 vendored 进本包(bin/git-partial-submodule.py,固定 commit bd8bb4e7),并以工具形式暴露给模型。

| 层 | 来源 | 在 dsh 中的形态 |
| 工具 | Vendored git-partial-submodule 脚本,通过 python3 执行 | 内置工具 git_partial_submodule(add / clone / save-sparse / restore-sparse) |
| 技能 | 本 bundle | 内置技能 git-partial-submodule,出现在模型的 <available_skills> 目录中,按需通过 skill 工具加载 |

为什么用 partial submodule

对顶层仓库,git 提供了 "blobless" clone 等部分克隆选项来减小下载大仓库的负担;但对 submodule,
git 只支持 "shallow" 克隆,而 shallow 克隆存在可用性问题。
git-partial-submodule 把 submodule 克隆成 blobless 仓库 —— 功能完整,同时节省带宽与磁盘 —— 并把 sparse-checkout 模式存进 .gitmodules, 随超项目一起纳入版本控制。

安装

在本包所在目录执行:
dsh plugin --profile web add ./dsh-gitmodules-dir
或从远端安装: dsh plugin --profile web add github:you/dsh-gitmodules-dir#<sha>
dsh web

运行 dsh 的机器上需要:git 2.27.0+ 与 python3 3.8+(启动时缺任一都会告警,使用时给出明确报错)。

模型侧获得的能力

启动后模型侧自动获得:

- 工具 git_partial_submodule —— 在会话工作目录(或显式 cwd)里执行一次 git-partial-submodule 操作:
- add —— 以 blobless 部分克隆方式添加新 submodule(支持 -b/--branch、--name、--sparse)。
- clone —— 克隆超项目后初始化部分 submodule,并应用 .gitmodules 里保存的稀疏模式。
- save-sparse —— 把 submodule 当前的稀疏模式持久化到 .gitmodules。
- restore-sparse —— pull 或切换分支后,把 .gitmodules 里保存的稀疏模式重新应用回去。
- 技能 git-partial-submodule —— 教学何时以及如何使用这些操作;底层实际执行的命令详见
references/git-commands.md(通过目录资源提示按需读取)。

工具返回 { exitCode, stdout, stderr };exitCode 非零表示操作失败 —— 模型读取 stderr 并向用户报告。

配置覆盖

patch 按行整体替换 config;用户可以在自己的 profile cordis.patch.yml 或 --patch overlay 里按行 id 覆盖:

完全禁用本 bundle(不注册工具与技能):
- id: gitmodules-dir
disabled: true

同步 vendored 脚本

bin/git-partial-submodule.py 来自上游 git-partial-submodule 仓库,固定到某个 commit,保证"插件版本 ↔ 上游版本"可复现:

npm run sync-script # 同步固定 commit
npm run sync-script -- <ref> # 同步指定 commit / tag / 分支
npm run smoke # 四个操作的端到端冒烟测试

已知限制与待办

随 bundle 携带的上游限制(见上游 README):

- 部分克隆与 sparse checkout 仍是实验性 git 特性,可能有锋利边缘。
- 该工具以非官方支持的方式操作仓库内部结构,可能在未考虑到的边界情况下失败或把仓库弄坏。
- 不支持递归克隆;底层 git clone / git submodule add 的选项并未全部支持;sparse-checkout 模式中的空格处理不正确。

与现代 git 的交互(上游自 2021 年起停更,git 已演进):

- git >= 2.37 默认 "cone" 模式 sparse checkout,此时 git sparse-checkout list 返回空,导致 save-sparse 存下空模式、clone / restore-sparse 无法重新应用稀疏模式 —— 上游脚本只支持 non-cone 模式。解决办法:让超项目的 git 运行在 core.sparseCheckoutCone=false(例如 git config --global core.sparseCheckoutCone false),或用 git -C sparse-checkout set --no-cone ... 显式设置稀疏模式。
- add --sparse 会在新 submodule 里启用稀疏检出,但不会把初始模式集写进 .gitmodules(上游 TODO);需要先跑一次 save-sparse 持久化。
- 当 submodule 仓库通过纯本地路径提供时,git 会忽略 --filter;要生效请使用 file:// URL 或
真实远端(https)。

许可证

- 本 bundle 的插件代码、技能与打包:MulanPSL-2.0。
- Vendored 脚本及其许可证文本来自
git-partial-submodule(Apache-2.0),随包
复制于 bin/git-partial-submodule.py 与 bin/LICENSE.txt。