modfmt

September 7, 2025 · View on GitHub

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)

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 ☕