dsh-gitmodules-dir

English | 中文

git-partial-submodule bundle for DeepSeek Harness (dsh): lets dsh users add, clone, and manage
partial git submodules — blobless partial clones plus sparse checkout — without hand-rolling the
underlying git plumbing. It wraps the git-partial-submodule
project (Apache-2.0): the upstream single-file Python script is vendored into this bundle
(bin/git-partial-submodule.py, pinned to commit bd8bb4e7) and exposed to the model.

Why partial submodules

In top-level repositories, git provides partial-clone options such as "blobless" clone to reduce the
burden of downloading large repositories, but for submodules only "shallow" clones are supported by
git, and shallow clones have usability issues. git-partial-submodule
clones submodules as blobless repos — fully functional while saving bandwidth and disk space — and
stores sparse-checkout patterns in .gitmodules, so they travel with the superproject under version
control.

Installation

# From the directory containing this package:
dsh plugin --profile web add ./dsh-gitmodules-dir
# or from a remote: dsh plugin --profile web add github:you/dsh-gitmodules-dir#<sha>
dsh web

Prerequisites on the machine where dsh runs: git 2.27.0 or later and python3 3.8 or later (the tool
warns at startup when either is missing, and fails with a clear error on use).

What the model gets

After startup the model side automatically gains:

• Tool git_partial_submodule — runs one git-partial-submodule operation in the session working
  directory (or an explicit cwd):
  • add — add a new submodule as a blobless partial clone (-b/--branch, --name, --sparse).
  • clone — initialize partial submodules after a fresh clone of the superproject, applying sparse
    patterns saved in .gitmodules.
  • save-sparse — persist the submodule's current sparse patterns to .gitmodules.
  • restore-sparse — reapply the sparse patterns saved in .gitmodules after pulls or branch
    switches.
• Skill git-partial-submodule — teaches when and how to use the operations, with the exact
  underlying command lines in references/git-commands.md (read on demand through the directory
  resource hint).

The tool returns { exitCode, stdout, stderr }; a non-zero exitCode means the operation failed —
the model reads stderr and reports it.

Configuration overrides

A patch replaces a row's whole config; users override by row id in their profile
cordis.patch.yml or a --patch overlay:

# Disable the bundle entirely (no tool, no skill):
- id: gitmodules-dir
  disabled: true

Syncing the vendored script

bin/git-partial-submodule.py is vendored from the upstream
git-partial-submodule repository pinned to a
commit, keeping "plugin version ↔ upstream version" reproducible:

npm run sync-script            # sync the pinned commit
npm run sync-script -- <ref>   # sync a specific commit / tag / branch
npm run smoke                  # end-to-end smoke test of the four operations

Known Limitations and Deferred Work

Upstream limitations carried into the bundle (see the upstream README):

• Partial clone and sparse checkout are still experimental git features that may have sharp edges.
• The tool works by fiddling with repository internals in not-officially-supported ways; it may fail
  or leave the repo in a bad state in edge cases.
• Recursive clone is not supported; not all options of the underlying git clone / git submodule add are supported; spaces in sparse-checkout patterns are not handled correctly.

Modern-git interactions (upstream is dormant since 2021, git has moved on):

• git >= 2.37 defaults to "cone" mode sparse checkout, where git sparse-checkout list returns
  empty. As a result save-sparse stores an empty pattern and clone / restore-sparse cannot
  re-apply sparse mode, because the upstream script supports non-cone mode only. Workaround: run the
  superproject's git with core.sparseCheckoutCone=false (e.g. git config --global core.sparseCheckoutCone false), or set sparse patterns explicitly with
  git -C <sub> sparse-checkout set --no-cone ....
• add --sparse enables sparse checkout in the new submodule but does not write the initial pattern
  set to .gitmodules (an upstream TODO); run save-sparse once to persist it.
• --filter is ignored when the submodule repository is served over a plain local path; use a
  file:// URL or a real remote (https) for the blobless filter to take effect.

License

• Plugin code, skill, and packaging of this bundle: MulanPSL-2.0.
• The vendored script and its license text come from
  git-partial-submodule (Apache-2.0), copied at
  bin/git-partial-submodule.py and bin/LICENSE.txt.