dsh-tool-git

English | 中文

Git tools for DeepSeek Harness agents — nine structured, model-facing tools that replace "shelling out to git and parsing text":

Tool	Purpose	Key parameters	Canonical value highlights
git_status	Working-tree status	workdir?	Structured branch/head/clean/staged/unstaged/untracked/conflicts
git_diff	Diff (unstaged by default)	staged? stat? paths?	diff text or stat numeric summary; UI diff card
git_log	Commit history	count? paths?	commits[] (hash/shortHash/author/date/subject)
git_add	Stage files	paths? or all?	stagedFiles[] read back from the index
git_commit	Create a commit	message (required) body? amend? stageAll?	New hash/shortHash/branch; empty index returns reason: 'nothing-to-commit'
git_branch	List/create/checkout/delete branches	action? name? startPoint? force?	branches[] (name/current/upstream) or action result
git_show	Show a commit or a file at a revision	rev path? stat?	Commit metadata + patch (UI diff card) or file content (UI read card)
git_restore	Discard working-tree changes / unstage	paths staged? source?	restored[] — the files actually changed
git_merge	Merge a branch/commit	rev noFF? abort? message?	New HEAD, or conflicts[] on a merge conflict

All tools accept workdir (defaults to the session workspace; relative paths resolve against it).

Compatibility

• Tested against DeepSeek Harness 0.1.0-rc.6 — the peer/dev dependency pins in package.json match the packages shipped with that version.
• Harness plugin interfaces are still evolving during the preview. If you upgrade dsh, re-run pnpm test against the new version and report any breakage.
• Requires git ≥ 2.23 (--porcelain=v2 and git restore).

Install

# From GitHub (pnpm runs the prepare build automatically)
dsh plugin --profile web add github:Huasfan/dsh-tool-git

# First git install: pnpm refuses to run build scripts until explicitly allowed —
# dsh prints the exact key to add to the profile's pnpm-workspace.yaml:
#   allowBuilds:
#     dsh-tool-git: true
# Consider pinning a commit: github:Huasfan/dsh-tool-git#<commit-sha>

Local / development:

# Patch overlay using the bundle layer
dsh --profile web --patch /abs/path/to/dsh-tool-git/cordis.patch.yml

# Or load the TypeScript source directly (the loader supports .ts, including
# relative imports):
#   name: '/abs/path/to/dsh-tool-git/src/index.ts'

Configuration (cordis.yml)

- id: git-tool
  name: dsh-tool-git
  config:
    gitPath: git        # git executable, default "git"
    timeoutMs: 30000    # per-invocation timeout in ms, default 30000

Config is a Schemastery schema: invalid configuration fails loudly at load time with an actionable error.

Design principles

• One canonical JSON value. execute returns only the structured value declared by output.schema; output.render turns it into model-facing prose. The model never parses prose for fields (per the official tool authoring reference).
• Non-zero exits are domain outcomes, not exceptions. A failing git call (not a repository, unmatched pathspec, rejected hook, …) returns { ok: false, error }; only infrastructure failures (missing executable, timeout, cancellation) throw. Timeouts land in error; cancellation re-throws as an AbortError using the registry-recognized TOOL_ABORTED.
• Cooperative cancellation. exec.signal is forwarded to child_process.execFile on every call.
• No shell injection. execFile with an argument array; command strings are never interpolated. Environment is pinned (LC_ALL=C, GIT_TERMINAL_PROMPT=0, GIT_PAGER=cat) and read-only commands use --no-optional-locks.
• Registration is an effect. ctx.tools.register(...) unregisters automatically when the plugin unloads.
• Machine-readable parsing. git status --porcelain=v2 -z --branch with positional slicing (paths may contain spaces); a rename's original path is the bare record that immediately follows.
• Tool-owned UI cards. Pure presentCall/presentResult presenters, with output.presentationMeta projecting replayable diff-card and read-card data (git_diff, git_show) that survives session-log replay.

Reference implementation: @deepseek-ai/dsh-tool-bash.

Development

pnpm install     # all dev dependencies come from npm; no local dsh install needed
pnpm typecheck   # tsc --noEmit (TS 5.8 strict + erasableSyntaxOnly)
pnpm test        # vitest: 28 tests (parser unit tests + real scratch-repo integration)
pnpm build       # esbuild bundle → lib/index.js (same as the prepare script)

Peer packages (@deepseek-ai/dsh-tools etc.) are pinned to the exact versions shipped with dsh 0.1.0-rc.6; at runtime they resolve from the profile's in-box dependencies.

Documentation

• CONTRIBUTING.md — how to build, test, and submit changes.
• RELEASE-NOTES.md — per-version release notes.

License

MIT