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.