pflag

You can use pflag as a replacement for the standard Go flag package by importing it under the name flag. Most code will function without changes.

Exception: If you directly instantiate the Flag struct, you must manually set the Shorthand field.

import flag "github.com/spf13/pflag"

Install pflag using the standard go get command.

go get github.com/spf13/pflag@latest

When using pflag in TestMain, pflag.Parse() might skip over go test's built-in shorthand flags (those starting with -test.). To ensure these are parsed correctly, use ParseSkippedFlags to parse the standard Go flags separately.

package main

import (
	goflag "flag"
    "os"
	flag "github.com/spf13/pflag"
)

var ip = flag.Int("flagname", 1234, "help message for flagname")

func main() {
	flag.CommandLine.AddGoFlagSet(goflag.CommandLine)
	flag.ParseSkippedFlags(os.Args[1:], goflag.CommandLine)
	flag.Parse()
}

By default, pflag sorts flags in the help/usage message. You can disable this by setting the SortFlags field to false on a FlagSet. To disable it for the global command line, use pflag.CommandLine.SortFlags = false.

flags := pflag.NewFlagSet("example", pflag.ContinueOnError)
flags.BoolP("verbose", "v", false, "verbose output")
flags.SortFlags = false
flags.PrintDefaults()

To provide one-letter shorthands for flags, use the functions that end with P. These allow users to use single-dash shorthand syntax (e.g., -f).

var ip = flag.IntP("flagname", "f", 1234, "help message")
var flagvar bool
func init() {
    flag.BoolVarP(&flagvar, "boolname", "b", true, "help message")
}
flag.VarP(&flagVal, "varname", "v", "help message")

You can implement a custom normalization function using SetNormalizeFunc on a FlagSet. This allows you to treat different flag names (e.g., using -, _, or .) as the same flag during comparison.

func wordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
	from := []string{"-", "_"}
	to := "."
	for _, sep := range from {
		name = strings.Replace(name, sep, to, -1)
	}
	return pflag.NormalizedName(name)
}

myFlagSet.SetNormalizeFunc(wordSepNormalizeFunc)

To support flags defined by the standard flag package (often used by third-party dependencies), add the Go flag set to your pflag flag set using AddGoFlagSet.

package main

import (
	goflag "flag"
	flag "github.com/spf13/pflag"
)

var ip = flag.Int("flagname", 1234, "help message for flagname")

func main() {
	flag.CommandLine.AddGoFlagSet(goflag.CommandLine)
	flag.Parse()
}

Use MarkHidden to make a flag functional but invisible in the usage/help output.

flags.MarkHidden("secretFlag")

Define flags using standard types like String(), Bool(), Int(), etc. You can also bind flags to existing variables using Var() functions (e.g., IntVar()). After defining all flags, call flag.Parse() to process command-line arguments.

var ip *int = flag.Int("flagname", 1234, "help message for flagname")

var flagvar int
func init() {
    flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}

func main() {
    flag.Parse()
    fmt.Println("ip has value ", *ip)
    fmt.Println("flagvar has value ", flagvar)
}