LinuxCommandLibrary

go-fmt

Format Go source code automatically

TLDR

Format Go source files in the current directory

$ go fmt
copy

Format a specific Go package in your import path ($GOPATH/src)
$ go fmt [path/to/package]
copy

Format the package in the current directory and all subdirectories (note the ...)
$ go fmt [./...]
copy

Print what format commands would've been run, without modifying anything
$ go fmt -n
copy

Print which format commands are run as they are run
$ go fmt -x
copy

SYNOPSIS

go fmt [flags] [packages or files]

Examples:
go fmt .
go fmt ./...
go fmt main.go another.go

PARAMETERS

-l
    List files whose formatting would change. This flag prints the names of the files that go fmt would modify to standard output, without actually changing them.

-r rule
    Apply a rewrite rule to the source before formatting. The rule is specified in the form "pattern -> replacement". This is an advanced feature primarily used for code transformations, not just style.

-s
    Simplify code before formatting. This applies basic AST simplifications, such as replacing `x[a:len(x)]` with `x[a:]`. This option is often used in conjunction with other `go tool` commands.

-x
    Print commands executed. This flag is useful for debugging as it shows the underlying commands go fmt invokes internally (e.g., `go tool fmt`).

DESCRIPTION

go fmt is a command-line utility that automatically reformats Go program source code according to the official Go programming language style guide. It's an essential part of the Go toolchain, ensuring code consistency across projects and developers. The tool parses the Go source file into an abstract syntax tree (AST) and then prints it back out in a standardized, canonical format. This deterministic process eliminates stylistic debates and promotes readability.

Unlike many formatters, go fmt is highly opinionated and offers very few configurable options. This design choice is fundamental to Go's philosophy of reducing bikeshedding over code style. When run without arguments, it processes the Go source files in the current directory. It can also accept specific files or package paths as arguments. By default, it modifies files in place, but options are available to preview changes or list affected files. Many Go development environments integrate go fmt (or its superset, goimports) to automatically format code upon saving.

CAVEATS

go fmt is intentionally opinionated and provides almost no configuration options for code style. This means developers cannot customize spacing, line breaks, or brace styles. Its primary purpose is to enforce a single, canonical Go style. By default, it modifies files in place, so it's advisable to use version control or the -l flag to preview changes before applying them.

IDEMPOTENCY

go fmt is idempotent. Running the command multiple times on the same source code will produce the identical output after the first run, assuming no manual changes were made in between.

IDE/EDITOR INTEGRATION

Most modern Go IDEs and text editors (like VS Code, GoLand, Vim, and Emacs) have built-in support or plugins to automatically run go fmt (or goimports) upon saving a Go file, ensuring continuous adherence to the standard style.

HISTORY

The concept of an automatic, opinionated code formatter like gofmt (the underlying tool) was central to the design philosophy of the Go language from its inception. It was developed by Rob Pike as part of the initial Go project at Google. Its aim was to eliminate arguments over code style, foster consistency, and improve code readability across all Go projects. go fmt, as part of the broader go toolchain, became available with early Go releases, solidifying its role as an indispensable tool for Go developers.

SEE ALSO

go(1): The primary Go command-line tool, used for building, testing, and managing Go projects., goimports(1): A tool similar to go fmt that also adds and removes Go package imports as necessary, making it a commonly used superset of go fmt., gofmt(1): The underlying, lower-level formatting command that go fmt typically invokes., go tool vet(1): A command that inspects Go source code and reports suspicious constructs, such as unused variables or unreachable code.

Copied to clipboard