Use when formatting shell scripts with shfmt. Covers consistent formatting patterns, shell dialect support, common issues, and editor integration.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
name: shfmt-formatting description: Use when formatting shell scripts with shfmt. Covers consistent formatting patterns, shell dialect support, common issues, and editor integration. allowed-tools:
Expert knowledge of shfmt's formatting capabilities, patterns, and integration with development workflows for consistent shell script formatting.
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.
shfmt supports multiple shell dialects with different syntax rules:
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
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))
Korn shell variant with its own extensions:
#!/bin/mksh
# mksh-specific syntax
typeset -A assoc
assoc[key]=value
For Bats test files:
#!/usr/bin/env bats
@test "example test" {
run my_command
[ "$status" -eq 0 ]
}
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
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
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-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
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 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
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
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
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
Problem: Unnecessary semicolons at end of lines
Before:
echo "hello";
x=1;
After (shfmt removes them):
echo "hello"
x=1
shfmt preserves quote style but normalizes unnecessary quotes:
Before:
echo 'single' "double" $'ansi'
x="simple"
After (preserved):
echo 'single' "double" $'ansi'
x="simple"
shfmt does not wrap long lines automatically. Use manual line continuation:
# Long command with continuation
very_long_command \
--option1 value1 \
--option2 value2 \
--option3 value3
Arrays are formatted on single or multiple lines as written:
# Single line (preserved)
array=(one two three)
# Multi-line (preserved)
array=(
one
two
three
)
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
}
}
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
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)
Install "Shell Script" plugin, configure in: Settings -> Tools -> Shell Scripts -> Formatter
Path to shfmt: /usr/local/bin/shfmt
Options: -i 2 -ci -bn
# 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
# Overwrite files with formatted version
shfmt -w script.sh
shfmt -w .
# Output formatted version to stdout
shfmt script.sh
# Output formatted version to file
shfmt script.sh > formatted.sh
# Format only staged shell scripts
git diff --cached --name-only --diff-filter=ACM | \
grep '\.sh$' | \
xargs -r shfmt -w
#!/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 files changed since main branch
git diff --name-only main...HEAD | \
grep '\.sh$' | \
xargs -r shfmt -w
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.
shfmt -d in CI pipelines.shfmt.toml to repositoryIf shfmt fails to parse a script:
# Check syntax first
bash -n script.sh
# Or for POSIX
sh -n script.sh
Force the correct dialect:
shfmt -ln bash script.sh
shfmt -ln posix script.sh
For code that should not be reformatted, consider:
# shfmt:ignore comments (not supported - use file exclusion)