dsh-git-bash
English · 中文
Built for dsh-TUI.
Make a Git for Windows installation resolvable as bash inside the dsh
host process, so the official bash shell stack can run on Windows.
Requirements
- Windows and a Git for Windows installation whose
bin directory holds
bash.exe. The default install location (%ProgramFiles%\Git\bin) is found
automatically; a portable or non-standard install is configured through
gitBinDir (see Configuration).
- A profile whose bundle list contains
@deepseek-ai/dsh-base — the rows this
package's patch overrides are mounted there.
- Node
^22.19 || >=24 (the same range the host requires).
⚠️ Read this before installing: this bundle is a shell-stack swap, not an
addition. Its patch enables the bash rows and disables the pwsh rows at
boot, before this plugin's apply() runs. If no Git for Windows installation
is found, this plugin cannot repair that: bash stays unresolvable, the
bash tool fails on every spawn, and the disabled pwsh rows leave no
fallback shell. On a machine without Git for Windows, do not install this
bundle — install Git for Windows first, or point gitBinDir at a portable
installation. Removing the bundle restores the platform defaults:
dsh plugin --profile <profile> remove dsh-git-bash.
The problem it solves
dsh ships two shell stacks and gates them by platform: on Windows
@deepseek-ai/dsh-base mounts pwsh-sandbox + tool-pwsh and disables
bash-sandbox + tool-bash. The bash stack is not disabled for lack of
support — it is disabled because it spawns the bare name bash:
- the executor runs
["bash", "-c", command], and
- the sandbox layer builds its own
["bash", "-c", command] for the confined
runner.
Neither place accepts a configurable executable path. A stock Windows PATH does
not resolve bash: Git for Windows puts cmd\git.exe on PATH, but not
bin\bash.exe. So the only seam that reaches both spawn sites is the process
PATH — which is what this plugin edits.
What it does
On win32 only, during apply():
- detects a Git installation (
%ProgramFiles%\Git\bin,
%ProgramFiles(x86)%\Git\bin, %LOCALAPPDATA%\Programs\Git\bin, then
C:\Program Files\Git\bin) and checks that it really holds bash.exe;
- prepends that directory to
process.env.PATH — but only when that directory
is not already a PATH entry, and never reordering an existing entry;
- records what it decided in
~/.dsh-tui/dsh-git-bash.log (bounded: past
128 KiB the older half is dropped, and node --test runs never write it);
- restores the previous PATH on unload — but only while the value is still its
own, so a PATH someone else edited afterwards is left alone.
- when no installation is found, reports it at error level with the
consequence and the three ways out. It does not fail the boot, so that
message is the only signal that the
bash tool will not work.
On other platforms it logs skipped: not win32 and does nothing.
It never throws: a missing installation, an unreadable log or a hostile config
leaves PATH exactly as it was. That is deliberately not the same as leaving
the machine as it was — the bundle patch has already swapped the shell stacks
by then, and no plugin can undo that. Hence the warning above and the
error-level report.
Enabling the bash stack: the bundle patch does both halves
A plugin cannot register a tool; it can only make the environment the official
tools need. So this package's own bundle patch does both halves, and installing
the package IS the installation:
- insert:
- id: dsh-git-bash
name: 'dsh-git-bash'
- id: bash-sandbox # enabled (config restated: a patch replaces it whole)
disabled: false
- id: pwsh-sandbox # disabled
disabled: true
- id: tool-bash # enabled -> the `bash` tool appears
disabled: false
- id: tool-pwsh # disabled
disabled: true
Both stacks provide ctx.shell, so exactly one may mount: this is a swap, not
an addition. pwsh remains reachable from bash (powershell -Command '…') if
you need it.
Reverting is removing the bundle (dsh plugin --profile <p> remove dsh-git-bash): every override above disappears with it and the platform gating
in @deepseek-ai/dsh-base applies again.
Do not put this swap in a LIVE profile's own cordis.patch.yml instead.
That file is watched by patchReload: live, so editing it re-configures
running sessions immediately — before this plugin's row is loaded, which
leaves them with a shell stack that cannot spawn bash. A bundle patch is
read at boot, which is the order this needs.
Install
# from npm (package name: dsh-git-bash)
dsh plugin --profile dsh-tui add dsh-git-bash
# from a local checkout (development)
dsh plugin --profile dsh-tui add file:/absolute/path/to/dsh-git-bash
Then restart the TUI (/restart) and confirm the composition before trusting
it:
dsh --profile dsh-tui --dump-config # composes the tree without starting the UI
Also check the detection result — ~/.dsh-tui/dsh-git-bash.log or the host log
records it, and a missing installation shows up there as a
SHELL TOOLS WILL NOT RUN error (see Diagnostics).
Configuration
| Key | Type | Default | Meaning |
|---|
gitBinDir | string | "" | Directory holding bash.exe. Empty = auto-detect. When set, it is the only candidate — a typo is reported at error level instead of being papered over. |
Set it on the plugin's row when detection cannot find your installation:
- id: dsh-git-bash
config:
gitBinDir: 'D:\PortableGit\bin'
Known limitations
- A machine without Git for Windows ends up with no working shell. The stack
swap is unconditional (it is a static patch, applied before this plugin runs),
so a missing or undiscoverable installation cannot be compensated for at
runtime. The plugin says so at error level, but it cannot restore the pwsh
rows. Install Git for Windows, set
gitBinDir, or remove the bundle.
- This enables a platform-gated stack. dsh disables the bash rows on Windows
by design; this plugin removes the reason it cannot work, but that composition
is not one upstream tests. Keep the
.bak of your cordis.patch.yml: rolling
back is deleting the four override lines above.
- Sandbox modes are the untested part. With
danger-full-access the
executor skips the confinement wrapper entirely, which is what has been
exercised here. Under workspace-write the sandbox layer wraps the command in
the Windows ACL restricted-token runner — a path built for POSIX. Treat
confined modes as unverified.
- A plugin cannot add tools; it can only make the environment the official tools
need. If the bash rows are not enabled, this plugin changes nothing visible.
- The PATH edit is process-wide inside the host process, which is exactly the
point: every consumer resolving
bash (the agent's own commands included)
benefits.
Development
pnpm install
pnpm test # node:test unit tests (pure discovery/PATH rules)
pnpm check:encoding # no UTF-8 BOM / damaged sequences / tab indentation
pnpm verify # both, in order
The tests are pure and injectable: resolveBinDir takes its environment and its
existence probe as arguments, so the discovery rules are pinned without touching
the machine. The win32 cases exercise the real installation when one is present
and skip otherwise.
Diagnostics
~/.dsh-tui/dsh-git-bash.log holds one line per decision: the detected
directory, already resolvable, SHELL TOOLS WILL NOT RUN … when no
installation was found, and the unload restore (or PATH left alone: it changed after this plugin). Every message is also sent to the host logger — the
missing-installation one at error level.
Publishing
License
MIT.
