dsh-gitmodules-dir

Readme

# dsh-gitmodules-dir

English | [中文](README.zh.md)

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](https://github.com/Reedbeta/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.

| Layer | Source | Shape in dsh |
| --- | --- | --- |
| Tool | Vendored [git-partial-submodule](https://github.com/Reedbeta/git-partial-submodule) script, run via `python3` | Built-in tool `git_partial_submodule` (add / clone / save-sparse / restore-sparse) |
| Skill | This bundle | Built-in skill `git-partial-submodule` in the model's `<available_skills>` catalog, loaded on demand via the `skill` tool |

## 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](https://github.com/Reedbeta/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

```sh
# 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:

```yaml
# 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](https://github.com/Reedbeta/git-partial-submodule) repository pinned to a
commit, keeping "plugin version ↔ upstream version" reproducible:

```sh
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](https://github.com/Reedbeta/git-partial-submodule) (Apache-2.0), copied at
  `bin/git-partial-submodule.py` and `bin/LICENSE.txt`.