The go Command Overview

Overview

The go command is the entry point for almost every development task in Go. It compiles your code, fetches dependencies, runs tests, formats source files, and more. It was designed from the start to work without build scripts, makefiles, or complex configuration files.

This philosophy came from a deliberate choice by the Go team. In the early days, Go projects used make and hand‑written makefiles to coordinate compilation. That approach worked, but it was fragile and required constant maintenance as the project grew. The go command replaced all of that by enforcing a simple, predictable set of conventions. Instead of configuring the build, you let the tool read your source code directly and figure out what to do.

The driving idea is that Go programs should compile using only the information already present in the code: the package declarations and the import blocks. If Go had required a separate configuration file to explain how to build, it would have failed its own design goals. The go command is the practical realisation of that promise.

For a beginner, the most helpful mental model is to think of the go command as a guide that already knows the layout of a Go project. You don’t tell it where your code lives or how to link things; you just write standard Go code, and the tool handles the rest. If you follow a few basic rules — one package per directory, import paths that match repository locations, and a go.mod file at the module root — the whole system works automatically.

Command Structure and Help

Every interaction with the go command follows the same pattern:

go <command> [arguments]

The word immediately after go is a subcommand that tells the tool which action to perform. For example, go build compiles packages, and go test runs tests. Most subcommands accept additional flags and target names (like package paths or .go files) after the subcommand.

To explore what’s available, use go help. Running it without arguments prints all top‑level subcommands and help topics:

$ go help
Go is a tool for managing Go source code.
Usage:
    go <command> [arguments]
The commands are:
    build       compile packages and dependencies
    clean       remove object files and cached files
    doc         show documentation for package or symbol
    env         print Go environment information
    bug         start a bug report
    fix         update packages to use new APIs
    fmt         gofmt (reformat) package sources
    generate    generate Go files by processing source
    get         add dependencies to current module and install them
    install     compile and install packages and dependencies
    list        list packages or modules
    mod         module maintenance
    work        workspace maintenance
    run         compile and run Go program
    test        test packages
    tool        run specified go tool
    version     print Go version
    vet         report likely mistakes in packages
...

You can dig deeper into any subcommand with go help <command>. For instance, go help build explains every build flag, and go help modules covers module concepts in detail. The -h flag also works: go build -h prints a shorter usage summary.

This built‑in help system is the fastest way to learn what each command does. It’s always up‑to‑date with your installed Go version, so you don’t need to search the web for flag meanings that might differ between releases.

Core Build Commands

The build commands translate source code into executable binaries. They share a common set of flags (like -o to name the output, or -v for verbose output) and all respect the module structure defined by go.mod.

go build

go build compiles the packages named by its arguments and their dependencies. It does not install the resulting binary into your $GOPATH/bin or $GOBIN; it just places the executable in the current working directory (or discards it for non‑main packages).

# Compile the package in the current directory
go build
# Build a specific package and place the output in bin/
go build -o bin/myapp ./cmd/myapp

When go build runs without errors, it silently produces an executable (for a main package) or performs a quick compilation check (for library packages). If you see no output at all, the compilation succeeded.

A beginner should remember that go build is safe to run at any time. It never modifies your source code, and its output is always a single file (or nothing, for libraries). It’s the quickest way to check whether your code compiles.

go run

go run compiles and immediately executes a main package in one step. It’s intended for development and quick experimentation, not for deploying to production.

# Run a single-file program
go run main.go
# Run a package from its import path
go run ./cmd/myapp

Under the hood, go run builds a temporary binary, runs it, and then cleans it up (unless you pass -work to keep the temporary directory). Because compilation happens every time, there is a small startup delay compared to running a pre‑built binary.

go install

go install works like go build, but it also places the resulting binary (or package archive) into the standard install locations, typically $GOPATH/bin for executables and $GOPATH/pkg for compiled packages. This makes the binary available from your shell’s PATH if $GOPATH/bin is in it.

go install ./cmd/myapp   # installs the binary into $GOPATH/bin

In module‑aware mode (which is the default since Go 1.16), go install can also install tools directly from a remote module path and version:

go install golang.org/x/tools/cmd/goimports@latest

After installation, you can run the command by typing its name, no go prefix needed. This is the standard way to keep development tools like linters or code generators available system‑wide while pinning them to a specific version.

go list and go clean

go list inspects packages and modules without building anything. It’s useful for understanding the structure of a large project or for scripting.

go list ./...             # list all packages in the current module
go list -m all            # list all module dependencies

go clean removes object files, cached test results, and other generated artifacts. Use it when you want a fresh build or when you’re running low on disk space.

go clean -cache           # clear the entire build cache
go clean -testcache       # clear cached test results

Package and Module Commands

Modern Go projects are organised as modules — collections of packages with a shared version and dependency graph. The go mod subcommand manages the go.mod file at the module root, and go get adds or updates dependencies.

Creating a Module

A new module starts with go mod init:

go mod init github.com/yourname/project

This creates a go.mod file that records the module path and the Go version. The module path acts as the global identifier for your project. It’s usually the repository URL where your code will live.

Adding Dependencies

When you import a package from another module in your code, the go command automatically adds the required dependency to go.mod the next time you run go build, go test, or go run. You don’t need to manually edit the file.

If you want to add a dependency explicitly, use go get:

go get github.com/gin-gonic/gin@v1.9.0

This updates go.mod and go.sum (the checksum file that guarantees the integrity of downloaded modules). It also downloads the source into the module cache, located by default at $GOPATH/pkg/mod.

Tidying and Understanding Dependencies

go mod tidy removes any dependency from go.mod that is no longer imported and adds any missing ones that are actually used by your source code.

go mod tidy

A useful companion is go mod why, which explains why a particular module is needed. It prints the shortest import chain from a package in your module to the dependency.

go mod why github.com/pkg/errors

For a full dependency graph, go mod graph dumps every module and its requirements as text lines, which you can pipe into visualisation tools.

Vendoring

If you prefer to keep a copy of all dependencies inside your project (perhaps for offline builds or stricter control), go mod vendor copies the dependencies into a vendor directory. The go command will use that directory when you pass -mod=vendor or when a vendor directory exists and your Go version is 1.14 or higher.

go mod vendor

Quality and Generation Commands

The Go toolchain includes several subcommands that don’t produce binaries but instead enforce style, catch mistakes, or generate code automatically.

go fmt

go fmt reformats Go source files according to the standard style. It’s a wrapper around the gofmt tool, and it operates on all .go files in the packages you specify.

go fmt ./...              # format all packages in the module
go fmt ./handlers/...     # format only the handlers subtree

The command rewrites files in place. To see what it would change without modifying anything, use gofmt -d directly.

go vet

go vet runs a set of static analysis checks that look for suspicious constructs. It catches things like unreachable code, format string mismatches, and assignments that are effectively no‑ops.

go vet ./...

It’s designed to be fast enough to run as part of your regular edit‑build cycle. Unlike a full linter, it never produces false positives; if go vet flags something, it’s almost certainly a real problem.

go doc

go doc prints documentation for a package, symbol, or method directly in the terminal. It works offline and is often faster than opening a browser.

go doc fmt.Println         # documentation for a specific function
go doc encoding/json       # overview of the json package
go doc -src fmt.Println    # documentation plus the actual source code

This is an invaluable reference when you need to check the signature of a standard library function without leaving your editor.

go generate

go generate scans source files for special comments of the form //go:generate command and executes the specified commands. It’s a standardised way to trigger code generation steps — like generating mocks, stringer methods, or protocol buffer code — before a build.

//go:generate mockgen -source=user.go -destination=mocks/user_mock.go

Running go generate ./... in your module will run all such directives. The commands are executed in the order they appear, and the tool does not impose any restrictions on what the command is; it just runs whatever string follows the directive.

go fix

go fix rewrites Go source code to use newer APIs when the language or standard library changes. It was especially important during the early Go releases, when core APIs evolved rapidly. Today it’s less frequently needed, but it still handles things like migrating from golang.org/x/net/context to the built‑in context package.

go fix ./...

Always review the changes go fix makes (with go fix -diff first) before committing them. The transformation is syntax‑aware, but edge cases in large codebases can still produce unintended results.

Summary

The go command unifies tasks that in other ecosystems are spread across a dozen different tools. It builds, tests, formats, documents, and manages dependencies using the same underlying understanding of your code. This uniformity means you spend less time remembering tool‑specific syntax and more time writing.

The key takeaway is that the go command works because of conventions, not configuration. Once you structure your project as a module and follow Go’s natural package layout, the tooling just works. If you find yourself fighting the tool, it’s usually a sign that a convention is being broken — perhaps two packages in one directory or an unusual GOPATH setup.