# mvdan/sh architecture

> Architecture diagram of the GitHub repository mvdan/sh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mvdan/sh
- Repository: https://github.com/mvdan/sh

## Overview

This repository is a Go shell toolkit: it parses and formats POSIX/Bash-family scripts, provides shell-semantic string helpers, and interprets scripts without requiring a system shell. The main execution workflow is gosh input → syntax parsing → interpreter execution, with configurable handlers for command and filesystem access. shfmt is a separate formatting workflow through the syntax package. The README also documents globbing, matching, and expansion helpers. Relationships are limited to those shown in excerpts, indexed imports, or README statements; some internal details are not sampled.

Main entry points: [`interp/runner.go`](https://github.com/mvdan/sh/blob/master/interp/runner.go) (Interpreter runner), [`syntax/parser.go`](https://github.com/mvdan/sh/blob/master/syntax/parser.go) (Shell parser), [`syntax`](https://github.com/mvdan/sh/tree/master/syntax) (Syntax API), [`expand/param.go`](https://github.com/mvdan/sh/blob/master/expand/param.go) (Parameter expansion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_syntax["Shell syntax"]
  node_syntax_pkg["Syntax API"]
  node_lexer["Shell lexer<br/>[lexer.go]"]
  node_parser["Shell parser<br/>[parser.go]"]
  node_ast["Syntax tree<br/>[nodes.go]"]
  node_printer["Shell printer<br/>[printer.go]"]
  node_typedjson["Typed JSON<br/>[json.go]"]
end

subgraph group_helpers["Shell helpers"]
  node_expansion["Word expansion<br/>[expand.go]"]
  node_parameters["Parameter expansion<br/>[param.go]"]
  node_arithmetic["Arithmetic expansion<br/>[arith.go]"]
  node_pattern["Pattern matching<br/>[pattern.go]"]
  node_shell_split["Split and quote<br/>[split.go]"]
  node_shell_expand["String expansion<br/>[expand.go]"]
  node_shell_glob["Shell globbing<br/>[glob.go]"]
  node_shell_match["Case matching<br/>[match.go]"]
end

subgraph group_runtime["Script runtime"]
  node_runner["Interpreter runner<br/>[runner.go]"]
  node_interp_api["Runtime API<br/>[api.go]"]
  node_builtins["Shell builtins<br/>[builtin.go]"]
  node_handlers["Execution handlers<br/>[handler.go]"]
  node_variables["Runtime variables<br/>[vars.go]"]
  node_coreutils["Core utilities<br/>[coreutils.go]"]
end

subgraph group_tools["Command-line tools"]
  node_gosh["gosh runner<br/>[main.go]"]
  node_shfmt["shfmt formatter<br/>[main.go]"]
end

node_user(("Script user"))

node_user -->|"provides script"| node_gosh
node_gosh -->|"parses input"| node_parser
node_parser -->|"builds tree"| node_ast
node_gosh -->|"runs program"| node_runner
node_runner -->|"executes tree"| node_ast
node_runner -->|"expands words"| node_expansion
node_expansion -->|"expands parameters"| node_parameters
node_parameters -->|"evaluates arithmetic"| node_arithmetic
node_parameters -->|"uses patterns"| node_pattern
node_interp_api -->|"configures"| node_runner
node_runner -->|"dispatches builtins"| node_builtins
node_runner -->|"uses handlers"| node_handlers
node_runner -->|"accesses variables"| node_variables
node_coreutils -->|"integrates with"| node_interp_api
node_user -->|"requests formatting"| node_shfmt
node_shfmt -->|"formats scripts"| node_syntax_pkg
node_syntax_pkg -->|"parses scripts"| node_parser
node_syntax_pkg -->|"prints scripts"| node_printer
node_shfmt -->|"uses JSON trees"| node_typedjson
node_user -->|"uses helpers"| node_shell_split
node_shell_split -->|"parses words"| node_parser
node_shell_expand -->|"uses expansion"| node_expansion
node_user -->|"expands strings"| node_shell_expand
node_user -->|"globs paths"| node_shell_glob
node_user -->|"matches patterns"| node_shell_match

click node_syntax_pkg "https://github.com/mvdan/sh/tree/master/syntax"
click node_lexer "https://github.com/mvdan/sh/blob/master/syntax/lexer.go"
click node_parser "https://github.com/mvdan/sh/blob/master/syntax/parser.go"
click node_ast "https://github.com/mvdan/sh/blob/master/syntax/nodes.go"
click node_printer "https://github.com/mvdan/sh/blob/master/syntax/printer.go"
click node_typedjson "https://github.com/mvdan/sh/blob/master/syntax/typedjson/json.go"
click node_expansion "https://github.com/mvdan/sh/blob/master/expand/expand.go"
click node_parameters "https://github.com/mvdan/sh/blob/master/expand/param.go"
click node_arithmetic "https://github.com/mvdan/sh/blob/master/expand/arith.go"
click node_pattern "https://github.com/mvdan/sh/blob/master/pattern/pattern.go"
click node_shell_split "https://github.com/mvdan/sh/blob/master/shell/split.go"
click node_shell_expand "https://github.com/mvdan/sh/blob/master/shell/expand.go"
click node_shell_glob "https://github.com/mvdan/sh/blob/master/shell/glob.go"
click node_shell_match "https://github.com/mvdan/sh/blob/master/shell/match.go"
click node_gosh "https://github.com/mvdan/sh/blob/master/cmd/gosh/main.go"
click node_shfmt "https://github.com/mvdan/sh/blob/master/cmd/shfmt/main.go"
click node_runner "https://github.com/mvdan/sh/blob/master/interp/runner.go"
click node_interp_api "https://github.com/mvdan/sh/blob/master/interp/api.go"
click node_builtins "https://github.com/mvdan/sh/blob/master/interp/builtin.go"
click node_handlers "https://github.com/mvdan/sh/blob/master/interp/handler.go"
click node_variables "https://github.com/mvdan/sh/blob/master/interp/vars.go"
click node_coreutils "https://github.com/mvdan/sh/blob/master/x/coreutils/coreutils.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_syntax_pkg,node_lexer,node_parser,node_ast,node_printer,node_typedjson,node_user toneBlue
class node_expansion,node_parameters,node_arithmetic,node_pattern,node_shell_split,node_shell_expand,node_shell_glob,node_shell_match toneAmber
class node_runner,node_interp_api,node_builtins,node_handlers,node_variables,node_coreutils toneMint
class node_gosh,node_shfmt toneRose
```

## Components

### Shell syntax

- [Syntax API](https://github.com/mvdan/sh/tree/master/syntax): `syntax`
- [Shell lexer](https://github.com/mvdan/sh/blob/master/syntax/lexer.go): `syntax/lexer.go`
- [Shell parser](https://github.com/mvdan/sh/blob/master/syntax/parser.go): `syntax/parser.go`
- [Syntax tree](https://github.com/mvdan/sh/blob/master/syntax/nodes.go): `syntax/nodes.go`
- [Shell printer](https://github.com/mvdan/sh/blob/master/syntax/printer.go): `syntax/printer.go`
- [Typed JSON](https://github.com/mvdan/sh/blob/master/syntax/typedjson/json.go): `syntax/typedjson/json.go`

### Shell helpers

- [Word expansion](https://github.com/mvdan/sh/blob/master/expand/expand.go): `expand/expand.go`
- [Parameter expansion](https://github.com/mvdan/sh/blob/master/expand/param.go): `expand/param.go`
- [Arithmetic expansion](https://github.com/mvdan/sh/blob/master/expand/arith.go): `expand/arith.go`
- [Pattern matching](https://github.com/mvdan/sh/blob/master/pattern/pattern.go): `pattern/pattern.go`
- [Split and quote](https://github.com/mvdan/sh/blob/master/shell/split.go): `shell/split.go`
- [String expansion](https://github.com/mvdan/sh/blob/master/shell/expand.go): `shell/expand.go`
- [Shell globbing](https://github.com/mvdan/sh/blob/master/shell/glob.go): `shell/glob.go`
- [Case matching](https://github.com/mvdan/sh/blob/master/shell/match.go): `shell/match.go`

### Script runtime

- [Interpreter runner](https://github.com/mvdan/sh/blob/master/interp/runner.go): `interp/runner.go`
- [Runtime API](https://github.com/mvdan/sh/blob/master/interp/api.go): `interp/api.go`
- [Shell builtins](https://github.com/mvdan/sh/blob/master/interp/builtin.go): `interp/builtin.go`
- [Execution handlers](https://github.com/mvdan/sh/blob/master/interp/handler.go): `interp/handler.go`
- [Runtime variables](https://github.com/mvdan/sh/blob/master/interp/vars.go): `interp/vars.go`
- [Core utilities](https://github.com/mvdan/sh/blob/master/x/coreutils/coreutils.go): `x/coreutils/coreutils.go`

### Command-line tools

- [gosh runner](https://github.com/mvdan/sh/blob/master/cmd/gosh/main.go): `cmd/gosh/main.go`
- [shfmt formatter](https://github.com/mvdan/sh/blob/master/cmd/shfmt/main.go): `cmd/shfmt/main.go`

### Other components

- **Script user**

## Connections

- Script user → gosh runner: provides script
- gosh runner → Shell parser: parses input (evidence: `cmd/gosh/main.go`)
- Shell parser → Syntax tree: builds tree
- gosh runner → Interpreter runner: runs program (evidence: `cmd/gosh/main.go`)
- Interpreter runner → Syntax tree: executes tree (evidence: `interp/runner.go`)
- Interpreter runner → Word expansion: expands words (evidence: `interp/runner.go`)
- Word expansion → Parameter expansion: expands parameters (evidence: `expand/expand.go`)
- Parameter expansion → Arithmetic expansion: evaluates arithmetic (evidence: `expand/param.go`)
- Parameter expansion → Pattern matching: uses patterns (evidence: `expand/param.go`)
- Runtime API → Interpreter runner: configures (evidence: `interp/api.go`)
- Interpreter runner → Shell builtins: dispatches builtins (evidence: `interp/runner.go`)
- Interpreter runner → Execution handlers: uses handlers (evidence: `interp/handler.go`)
- Interpreter runner → Runtime variables: accesses variables (evidence: `interp/runner.go`)
- Core utilities → Runtime API: integrates with (evidence: `x/coreutils/coreutils.go`)
- Script user → shfmt formatter: requests formatting
- shfmt formatter → Syntax API: formats scripts (evidence: `cmd/shfmt/main.go`)
- Syntax API → Shell parser: parses scripts
- Syntax API → Shell printer: prints scripts
- shfmt formatter → Typed JSON: uses JSON trees (evidence: `cmd/shfmt/main.go`)
- Script user → Split and quote: uses helpers
- Split and quote → Shell parser: parses words (evidence: `shell/split.go`)
- String expansion → Word expansion: uses expansion (evidence: `shell/expand.go`)
- Script user → String expansion: expands strings
- Script user → Shell globbing: globs paths
- Script user → Case matching: matches patterns
