Pull requests that touch the team's bash scripts keep collecting comments about indentation and where `then` should go. What does the shfmt formatter do that ShellCheck does not, and how would you run it so CI fails on unformatted files without rewriting them?

## Two tools, two jobs The distinction is the same one every ecosystem eventually draws: a **linter** judges whether the code is *correct*, a **formatter** decides how it is *laid out*. - **ShellCheck** parses the script and reports findings — unquoted expansions, unchecked `cd`, masked exit statuses. It emits messages. It does not modify your file. - **shfmt** parses the script and re-prints it. It is layout-only: it will not change what the script does, and it has no opinion about whether a variable should be quoted. Running only the linter leaves indentation as a matter of taste and therefore a matter of review comments. Running only the formatter gives you tidy scripts with the same silent bugs. The two are complementary and cheap enough to run together. ## Making formatting a non-discussion The point of a formatter is to remove a category of review comment entirely. That only works if the tool, not the reviewer, is the authority — which means it must run automatically in two places: ```bash shfmt -w . # locally / pre-commit: rewrite files in place shfmt -d . # CI: print the diff, exit non-zero, change nothing ``` `-d` (`--diff`) is the CI mode. It shows exactly what would change, which makes the failure self-explanatory — the developer copies the fix by running `-w`. A CI job must not use `-w`: a job that mutates the checkout either has nothing to commit the change to, or commits on the author's behalf, which surprises people. `-l` lists the paths whose formatting differs, which is handy when you only want the file names. Given a directory, shfmt walks it and identifies shell files by extension and by shebang, so a `deploy` script with no `.sh` suffix is still covered. That shebang-driven detection is worth knowing because the same principle applies to how you build the file list for ShellCheck. ## The flags that encode a house style The defaults follow the layout of the POSIX shell grammar with tab indentation. Teams usually pin a few options and check them in: - `-i N` — indent with N spaces (`-i 0`, the default, means tabs). - `-ci` — indent the branches of a `case` statement. - `-bn` — put binary operators such as `&&` at the beginning of the continuation line rather than the end of the previous one. - `-sr` — put a space after a redirection operator. - `-s` — simplify: remove redundant syntax, such as needless quotes or `${x}` where `$x` suffices. - `-ln DIALECT` — the language variant: `bash`, `posix`, `mksh`, `bats`. Otherwise the shebang decides. A typical invocation a repository standardises on looks like `shfmt -i 2 -ci -bn -d .`. Whatever you choose, put it in one place — a Makefile target, a pre-commit configuration, or an `.editorconfig`, which shfmt reads for indentation settings — so the local run and the CI run cannot drift apart. A formatter whose CI settings differ from the developers' settings is worse than none, because it produces failures nobody can reproduce. ## Where each one runs The usual arrangement is a single `lint` entry point that runs both: ```bash #!/usr/bin/env bash set -euo pipefail shfmt -i 2 -ci -d . shfmt -f . | xargs -r shellcheck -x --severity=warning ``` `shfmt -f` lists the shell files it finds — a convenient, shebang-aware way to build the file list for ShellCheck, which otherwise needs an explicit glob and will miss extensionless scripts. Pin both tools to a specific version, because a formatter upgrade that changes one layout rule turns every file in the repository into a diff. ## What a formatter cannot do shfmt reformats; it does not refactor and it does not judge. It will happily produce beautifully indented code that word-splits on the first filename with a space in it. Nothing about running it reduces the need for ShellCheck, tests, or review of the actual logic — it just removes the layout argument from the review so the remaining comments are about substance.