modfmt

🗂️ Formatter for go.mod and go.work files

What is this?

This repository provides modfmt, a super simple formatter for go.mod and go.work files.

Additionally, it implements some specific features:

• Consistent ordering of sections and directives.
• Supports formatting of both go.mod and go.work files.
• Supports all of the current go.mod and go.work directives.
  • See https://go.dev/ref/mod#go-mod-file.
  • See https://go.dev/ref/mod#go-work-file.
• Preserves both file header comments and directive comments.
• Can be used in a CI pipeline to verify that files are formatted.
• Can be used as a library with minimal dependencies.
• Can be used as an analysis.Analyzer. (planned)

Formatting

Each of the various go.mod and go.work directives are combined into a unified block, consistently sorted, and rendered along with any associated comments. The ordering of directive blocks was based off of ecosystem conventions.

Ordering of go.mod directives

Section	Explanation
// Header comments	All header or unattached comments.
module …	The module directive.
go …	The go directive.
toolchain …	The toolchain directive.
godebug (…)	A block of godebug directives.
retract (…)	A block of retract directives.
require (…)	A block of require directives.
require (…)	A block of require directives. (for indirect dependencies)
ignore (…)	A block of ignore directives.
exclude (…)	A block of exclude directives.
replace (…)	A block of replace directives.
replace (…)	A block of replace directives. (for local replacements)
tool (…)	A block of tool directives.

Ordering of go.work directives

Section	Explanation
// Header comments	All header or unattached comments.
go …	The go directive.
toolchain …	The toolchain directive.
godebug (…)	A block of godebug directives.
use (…)	A block of use directives.
replace (…)	A block of replace directives.
replace (…)	A block of replace directives. (for local replacements)

Installation

Release artifact

Binaries for various architectures are published on the releases page.

The latest release can be installed by running:

OS=$(uname | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
wget -O modfmt.tar.gz https://github.com/joshdk/modfmt/releases/latest/download/modfmt-${OS}-${ARCH}.tar.gz
tar -xf modfmt.tar.gz
sudo install modfmt /usr/local/bin/modfmt

Brew

Release binaries are also available via Brew.

The latest release can be installed by running:

brew tap joshdk/tap
brew install joshdk/tap/modfmt

Go install

Installation can also be done directly from this repository.

The latest commit can be installed by running:

go install github.com/joshdk/modfmt@master

Usage

Showing unformatted files

Show unformatted go.mod or go.work files in the current directory:

modfmt

Show unformatted files anywhere under the directory pkg:

modfmt pkg/...

List unformatted filenames anywhere under the directory pkg:

modfmt -l pkg/...

Fixing unformatted files

Format and update all files under the current directory:

modfmt -w ./...

Important

You should always run go mod tidy prior to modfmt.

Exit with an error if any files were unformatted.

Verifying that files are formatted

modfmt -c ./...

Tip

This command should be run in CI during a linting pass.

License

This code is distributed under the MIT License, see LICENSE.txt for more information.

---

Created by Josh Komoroske ☕