dsh-gitmodules-dir

English | 中文

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),并以工具形式暴露给模型。

为什么用 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 <sub> 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。