Deep Dive into Go's flag Package: Usage, Syntax, and Source Code Analysis

When developing Go applications, parsing command-line arguments is a common requirement, and the flag package in the Go standard library provides a straightforward solution. This article first introduces the basic usage of flag , showing how to define flags with flag.Int , flag.IntVar , and flag.Var , and how to retrieve flag values after calling flag.Parse() .

Example code demonstrates three ways to declare flags: using flag.Int to obtain a pointer to an int , using flag.IntVar to bind a variable directly, and using flag.Var with a custom type that implements the flag.Value interface. The example also shows how to display help with --help or -h and how to inspect remaining non‑flag arguments with flag.NFlag() , flag.NArg() , flag.Args() , and flag.Arg(i) .

The article lists all supported flag types (bool, time.Duration, float64, int/int64/uint/uint64, string, and custom flag.Value ) and explains the flag syntax variations such as -flag , --flag , -flag=x , and -flag x . It also clarifies how the parser stops at the first non‑flag argument or the -- terminator.

In the source‑code deep dive, the article follows the call chain from the user‑level flag.Int function down to the internal FlagSet methods. It explains the creation of the global CommandLine variable via NewFlagSet , the structure of FlagSet (including fields like name , parsed , actual , formal , args , and errorHandling ), and the definition of the Flag struct that stores each flag’s name, usage, value, and default string.

The implementation of FlagSet.Int , IntVar , and Var is shown, highlighting how each creates a concrete intValue that satisfies the flag.Value interface. The article walks through the parsing loop in FlagSet.Parse , the parseOne routine that extracts flag names, handles boolean flags, validates syntax, and assigns values to the appropriate Flag objects.

Finally, the article summarizes the utility functions NFlag , NArg , Args , and Arg(i) , and notes that similar patterns exist for other primitive types (e.g., stringValue , float64Value ). The conclusion reinforces that the flag package is a solid choice for building command‑line tools in Go, offering both simplicity for common cases and extensibility for custom flag types.