shfmt — Shell Script Formatter and Parser in Go

Introduction

shfmt is a shell script formatter, parser, and interpreter written in Go. It supports POSIX Shell, Bash, and mksh dialects and provides consistent, opinionated formatting for shell scripts. Unlike linting tools that only flag issues, shfmt rewrites scripts to follow a uniform style, similar to what gofmt does for Go or Black does for Python.

What shfmt Does

• Formats shell scripts with consistent indentation, spacing, and style
• Parses shell code into an abstract syntax tree for programmatic analysis
• Supports POSIX Shell, Bash, and mksh script dialects
• Integrates with editors via plugins for VS Code, Vim, Emacs, and Sublime
• Provides a Go library for embedding shell parsing in other tools

Architecture Overview

The project is organized into several Go packages. The syntax package handles parsing shell scripts into an AST and printing them back. The interp package provides a shell interpreter. The cmd/shfmt package wraps these into a CLI tool. This modular design lets developers use the parser as a library in their own Go programs for tasks like static analysis or code generation.

Self-Hosting & Configuration

• Install via go install, Homebrew (brew install shfmt), or snap
• Configure indent size with -i flag (default uses tabs)
• Use -ln to set the language dialect: bash, posix, or mksh
• Add to CI pipelines with shfmt -d . to check formatting without writing
• Editor plugins available for VS Code, Vim, Neovim, Emacs, and Sublime Text

Key Features

• Supports three major shell dialects with automatic detection via shebang
• EditorConfig integration for per-project formatting preferences
• Minification mode to reduce script size for embedded use cases
• JSON output mode for integrating with other tooling
• Diff mode that shows proposed changes without modifying files

Comparison with Similar Tools

• ShellCheck — linter that finds bugs but does not format; often used alongside shfmt
• Prettier — multi-language formatter but does not support shell scripts
• Beautysh — Python-based shell formatter with fewer dialect options
• Google Shell Style Guide — manual style rules; shfmt automates enforcement
• Bash Language Server — IDE integration but no standalone formatting CLI

FAQ

Q: Can shfmt handle Zsh scripts? A: Partial support exists but Zsh is not a primary target. POSIX, Bash, and mksh are fully supported.

Q: How does shfmt detect which shell dialect to use? A: It reads the shebang line at the top of the script. You can also specify the dialect explicitly with the -ln flag.

Q: Does shfmt change the behavior of my scripts? A: No. shfmt only changes whitespace and formatting. The semantic meaning of the script is preserved.

Q: Can I use shfmt in a pre-commit hook? A: Yes. Run shfmt -d . to check for unformatted files and fail the hook if any are found.

Sources

• https://github.com/mvdan/sh
• https://pkg.go.dev/mvdan.cc/sh/v3