shfmt-formatting

name	shfmt-formatting
user-invocable	false
description	Use when formatting shell scripts with shfmt. Covers consistent formatting patterns, shell dialect support, common issues, and editor integration.
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob"]

shfmt Formatting

Expert knowledge of shfmt's formatting capabilities, patterns, and integration with development workflows for consistent shell script formatting.

Overview

shfmt formats shell scripts for readability and consistency. It parses scripts into an AST and prints them in a canonical format, eliminating style debates and ensuring uniformity across codebases.

Supported Shell Dialects

shfmt supports multiple shell dialects with different syntax rules:

POSIX Shell

Most portable, works with /bin/sh on any Unix system:

#!/bin/sh
# POSIX-compliant syntax only

# No arrays
# No [[ ]] tests
# No $() must work in all contexts

if [ "$var" = "value" ]; then
    echo "match"
fi

Bash

Most common for scripts, supports extended features:

#!/usr/bin/env bash
# Bash-specific features allowed

declare -a array=("one" "two" "three")

if [[ "$var" == "value" ]]; then
    echo "match"
fi

result=$((1 + 2))

mksh (MirBSD Korn Shell)

Korn shell variant with its own extensions:

#!/bin/mksh
# mksh-specific syntax

typeset -A assoc
assoc[key]=value

Bats (Bash Automated Testing System)

For Bats test files:

#!/usr/bin/env bats

@test "example test" {
    run my_command
    [ "$status" -eq 0 ]
}

Formatting Patterns

Indentation

shfmt normalizes indentation throughout scripts:

Before:

if [ "$x" = "y" ]; then
  echo "two spaces"
    echo "four spaces"
 echo "tab"
fi

After (with -i 2):

if [ "$x" = "y" ]; then
  echo "two spaces"
  echo "four spaces"
  echo "tab"
fi

Spacing

shfmt normalizes spacing around operators and keywords:

Before:

if[$x="y"];then
echo "no spaces"
fi
x=1;y=2;z=3

After:

if [ $x = "y" ]; then
    echo "no spaces"
fi
x=1
y=2
z=3

Semicolons and Newlines

Multiple statements are split to separate lines:

Before:

if [ "$x" ]; then echo "yes"; else echo "no"; fi

After:

if [ "$x" ]; then
    echo "yes"
else
    echo "no"
fi

Here Documents

Here-docs are preserved but indentation is normalized:

Before:

cat <<EOF
    line 1
    line 2
EOF

After (preserved):

cat <<EOF
    line 1
    line 2
EOF

Indented here-docs with <<- allow tab stripping:

if true; then
    cat <<-EOF
 indented content
 more content
 EOF
fi

Function Definitions

Functions are formatted consistently:

Before:

function my_func
{
echo "old style"
}
my_func2 () { echo "one liner"; }

After:

function my_func {
    echo "old style"
}
my_func2() {
    echo "one liner"
}

With -fn (function next line):

function my_func
{
    echo "brace on new line"
}

Case Statements

Case statements are formatted consistently:

Before:

case "$1" in
start) do_start;;
stop)
do_stop
;;
*) echo "unknown";;
esac

After:

case "$1" in
start)
    do_start
    ;;
stop)
    do_stop
    ;;
*)
    echo "unknown"
    ;;
esac

With -ci (case indent):

case "$1" in
    start)
        do_start
        ;;
    stop)
        do_stop
        ;;
esac

Binary Operators

Line continuation with binary operators:

Default:

if [ "$a" = "foo" ] &&
    [ "$b" = "bar" ]; then
    echo "match"
fi

With -bn (binary next line):

if [ "$a" = "foo" ] \
    && [ "$b" = "bar" ]; then
    echo "match"
fi

Redirections

Redirection formatting:

Default:

echo "hello" >file.txt
cat <input.txt 2>&1

With -sr (space redirects):

echo "hello" > file.txt
cat < input.txt 2>&1

Common Formatting Issues

Issue: Mixed Tabs and Spaces

Problem: Script has inconsistent indentation

Solution:

# Convert all to spaces (2-space indent)
shfmt -i 2 -w script.sh

# Or convert all to tabs
shfmt -i 0 -w script.sh

Issue: Trailing Semicolons

Problem: Unnecessary semicolons at end of lines

Before:

echo "hello";
x=1;

After (shfmt removes them):

echo "hello"
x=1

Issue: Inconsistent Quotes

shfmt preserves quote style but normalizes unnecessary quotes:

Before:

echo 'single' "double" $'ansi'
x="simple"

After (preserved):

echo 'single' "double" $'ansi'
x="simple"

Issue: Long Lines

shfmt does not wrap long lines automatically. Use manual line continuation:

# Long command with continuation
very_long_command \
    --option1 value1 \
    --option2 value2 \
    --option3 value3

Issue: Array Formatting

Arrays are formatted on single or multiple lines as written:

# Single line (preserved)
array=(one two three)

# Multi-line (preserved)
array=(
    one
    two
    three
)

Editor Integration

VS Code

Install "shell-format" extension:

// settings.json
{
  "shellformat.path": "/usr/local/bin/shfmt",
  "shellformat.flag": "-i 2 -ci -bn",
  "[shellscript]": {
    "editor.defaultFormatter": "foxundermoon.shell-format",
    "editor.formatOnSave": true
  }
}

Vim/Neovim

Using ALE:

" .vimrc
let g:ale_fixers = {
\   'sh': ['shfmt'],
\}
let g:ale_sh_shfmt_options = '-i 2 -ci -bn'
let g:ale_fix_on_save = 1

Using native formatting:

" .vimrc
autocmd FileType sh setlocal formatprg=shfmt\ -i\ 2\ -ci

Emacs

Using reformatter:

;; init.el
(use-package reformatter
  :config
  (reformatter-define shfmt
    :program "shfmt"
    :args '("-i" "2" "-ci")))

(add-hook 'sh-mode-hook 'shfmt-on-save-mode)

JetBrains IDEs

Install "Shell Script" plugin, configure in: Settings -> Tools -> Shell Scripts -> Formatter

Path to shfmt: /usr/local/bin/shfmt
Options: -i 2 -ci -bn

Diff and Check Modes

Check Formatting (CI Mode)

# Show diff of what would change (exit 1 if changes needed)
shfmt -d script.sh
shfmt -d .

# List files that need formatting
shfmt -l .

# Exit codes:
# 0 = no changes needed
# 1 = changes needed or error

Format in Place

# Overwrite files with formatted version
shfmt -w script.sh
shfmt -w .

Preview Changes

# Output formatted version to stdout
shfmt script.sh

# Output formatted version to file
shfmt script.sh > formatted.sh

Working with Git

Format Staged Files

# Format only staged shell scripts
git diff --cached --name-only --diff-filter=ACM | \
    grep '\.sh$' | \
    xargs -r shfmt -w

Pre-commit Hook

#!/usr/bin/env bash
# .git/hooks/pre-commit

# Check if shfmt is available
if ! command -v shfmt &>/dev/null; then
    echo "shfmt not found, skipping format check"
    exit 0
fi

# Get staged shell files
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.sh$')

if [ -n "$files" ]; then
    # Check formatting
    if ! echo "$files" | xargs shfmt -d; then
        echo "Shell scripts need formatting. Run: shfmt -w <files>"
        exit 1
    fi
fi

Format Changed Files

# Format files changed since main branch
git diff --name-only main...HEAD | \
    grep '\.sh$' | \
    xargs -r shfmt -w

Minification (Advanced)

shfmt can minify scripts by removing whitespace:

# Minify script
shfmt -mn script.sh > script.min.sh

Before:

#!/bin/bash
# Comment
function hello {
    echo "Hello, World!"
}
hello

After (minified):

#!/bin/bash
function hello { echo "Hello, World!"; }
hello

Note: Minification removes comments and most whitespace. Use only for distribution, not development.

Best Practices

1. Format on Save - Configure editor to format automatically
2. CI Validation - Run shfmt -d in CI pipelines
3. Consistent Team Settings - Commit .shfmt.toml to repository
4. Match Shebang - Ensure shell dialect matches script shebang
5. Review After Formatting - Verify changes make sense
6. Don't Mix Styles - Use same settings across all scripts
7. Pre-commit Hooks - Prevent unformatted code from being committed

Troubleshooting

Parse Errors

If shfmt fails to parse a script:

# Check syntax first
bash -n script.sh

# Or for POSIX
sh -n script.sh

Wrong Dialect Detection

Force the correct dialect:

shfmt -ln bash script.sh
shfmt -ln posix script.sh

Preserving Intentional Formatting

For code that should not be reformatted, consider:

1. Moving it to a separate file not processed by shfmt
2. Using # shfmt:ignore comments (not supported - use file exclusion)
3. Accepting the formatted version

When to Use This Skill

• Formatting shell scripts for consistency
• Integrating shfmt into development workflow
• Resolving formatting issues in scripts
• Setting up format-on-save in editors
• Configuring CI/CD format checks
• Understanding shfmt's formatting decisions