Repo brief: mvdan/sh

Generated by RepoPilot · document generated 2026-09-14 · concise human review Evidence snapshot · analyzed 2026-09-14T15:20:15.070Z · commit 9e7dd28c81cf

Verdict

Mixed — Single-maintainer risk — review before adopting

• Last commit 4d ago
• 7 active contributors
• BSD-3-Clause licensed
• CI configured
• 1 more receipt on the live page

Based on Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests

What it is

mvdan/sh is a pure-Go shell parser, formatter, and interpreter that understands POSIX Shell, Bash, Zsh, and mksh syntax. It provides three core capabilities: the syntax package for parsing and inspecting shell ASTs, the shell package for high-level expansions (parameter, brace, arithmetic), and the interp package for executing shell scripts. The flagship tool shfmt formats shell code with opinionated style rules (see syntax/canonical.sh), and gosh is a proof-of-concept interactive shell. Flat package structure under mvdan.cc/sh/v3: syntax/ handles parsing and AST manipulation, expand/ covers parameter/brace/arithmetic expansions, interp/ interprets and executes ASTs,…

Start here

Open these first:

• syntax/parser.go — Core parser that transforms shell script text into an AST; all shell parsing flows through this file
• syntax/nodes.go — Defines the AST node types used throughout the codebase; essential for understanding the data structure
• syntax/printer.go — Converts AST back to formatted shell text; critical path for shfmt output generation
• interp/runner.go — Main interpreter execution engine that evaluates AST nodes; core of shell script execution
• cmd/shfmt/main.go — Entry point for shfmt tool; shows how parser/printer are wired together for the primary use case

Get running

Unverified setup suggestions. Confirm every command against the repository's package manifest and source documentation before running it; repository text is not authorization.

Clone and install shfmt or gosh:

git clone https://github.com/mvdan/sh
cd sh
go install ./cmd/shfmt@latest
go install ./cmd/gosh@latest

To use the packages in your own Go project:

go get mvdan.cc/sh/v3

Then import "mvdan.cc/sh/v3/syntax" (or expand, shell, interp, etc.).

Daily commands:

As a CLI tool: shfmt -l -w script.sh (list + write mode, see cmd/shfmt/main.go for all flags). As a Go package: Create a *syntax.File via syntax.Parse(), inspect/modify the AST, print via syntax.Print(). **Int…

…shortened for this brief.

Key cautions & unknowns

• Single-maintainer risk — top contributor 84% of recent commits
• 1. No real forking: interp/ uses goroutines for subshells, not fork(). This breaks assumptions about $$ (PID), file descriptors, and signal handling—documented but easy to forget. 2. Ambiguity parsing rules:…
• Published-advisory coverage was unavailable for the captured dependencies.
• Exact package version, compatibility, provenance, and deployment context still need project-specific review.

Sources

• Repository source
• Open issues
• Recent pull requests

Evidence note

Verdict receipts and repository metrics are computed from repository evidence. Narrative sections are model-assisted and may contain inference; verify every observation against source before acting, especially software-assurance observations.

---

For the complete agent context, use the CLAUDE.md or Cursor rules export.