How to use the go mod command line

Created

Initialize new module in current directory. If you plan to publish your module for others to use, the module path must be a location from which Go tools can download your module.

go mod init example.com/hello
go: creating new go.mod: module example.com/hello
Usage: 
  go mod <command> [arguments]

Commands:
download
download modules to local cache
edit
edit go.mod from tools or scripts
graph
print module requirement graph
init
initialize new module in current directory
tidy
add missing and remove unused modules
vendor
make vendored copy of dependencies
verify
verify dependencies have expected content
why
explain why packages or modules are needed

Download modules to local cache

The go command will automatically download modules as needed during ordinary execution. The "go mod download" command is useful mainly for pre-filling the local cache or to compute the answers for a Go module proxy.

Usage: 
  go mod download [-x] [-json] [modules]

Options:
-x
The -x flag causes download to print the commands download executes.

Edit go.mod from tools or scripts

Edit provides a command-line interface for editing go.mod, for use primarily by tools or scripts. It reads only go.mod; it does not look up information about the modules involved. By default, edit reads and writes the go.mod file of the main module, but a different target file can be specified after the editing flags.

Usage: 
  go mod edit [editing flags] [go.mod]

flags:
-fmt
The -fmt flag reformats the go.mod file without making other changes. This reformatting is also implied by any other modifications that use or rewrite the go.mod file. The only time this flag is needed is if no other flags are specified, as in 'go mod edit -fmt'.
-module
The -module flag changes the module's path (the go.mod file's module line).
-require
The [email protected] and -droprequire=path flags add and drop a requirement on the given module path and version. Note that -require overrides any existing requirements on path. These flags are mainly for tools that understand the module graph. Users should prefer 'go get [email protected]' or 'go get [email protected]', which make other go.mod adjustments as needed to satisfy constraints imposed by other modules.
The [email protected] and [email protected] flags add and drop an exclusion for the given module path and version. Note that [email protected] is a no-op if that exclusion already exists.
-replace=old[@v]=new[@v]
The -replace=old[@v]=new[@v] flag adds a replacement of the given module path and version pair. If the @v in [email protected] is omitted, a replacement without a version on the left side is added, which applies to all versions of the old module path. If the @v in [email protected] is omitted, the new path should be a local module root directory, not a module path. Note that -replace overrides any redundant replacements for old[@v], so omitting @v will drop existing replacements for specific versions.
-dropreplace=old[@v]
The -dropreplace=old[@v] flag drops a replacement of the given module path and version pair. If the @v is omitted, a replacement without a version on the left side is dropped.
-retract=version and -dropretract=version
The -retract=version and -dropretract=version flags add and drop a retraction on the given version. The version may be a single version like "v1.2.3" or a closed interval like "[v1.1.0,v1.1.9]". Note that -retract=version is a no-op if that retraction already exists.
-require, -droprequire, -exclude, -dropexclude, -replace, -dropreplace, -retract, and -dropretract editing
The -require, -droprequire, -exclude, -dropexclude, -replace, -dropreplace, -retract, and -dropretract editing flags may be repeated, and the changes are applied in the order given.
-go=version
The -go=version flag sets the expected Go language version.
-print
The -print flag prints the final go.mod in its text format instead of writing it back to go.mod.
-json
The -json flag prints the final go.mod file in JSON format instead of writing it back to go.mod. The JSON output corresponds to these Go types:

Print module requirement graph

Graph prints the module requirement graph (with replacements applied) in text form. Each line in the output has two space-separated fields: a module and one of its requirements. Each module is identified as a string of the form [email protected], except for the main module, which has no @version suffix.

Usage: 
  go mod graph

go mod graph
golang.org/x/[email protected] golang.org/x/[email protected]
golang.org/x/[email protected] golang.org/x/[email protected]
golang.org/x/[email protected] golang.org/x/[email protected]

Initialize new module in current directory

Init initializes and writes a new go.mod file in the current directory, in effect creating a new module rooted at the current directory. The go.mod file must not already exist.

Usage: 
  go mod init [module]

Add missing and remove unused modules

Tidy makes sure go.mod matches the source code in the module. It adds any missing modules necessary to build the current module's packages and dependencies, and it removes unused modules that don't provide any relevant packages. It also adds any missing entries to go.sum and removes any unnecessary ones.

Usage: 
  go mod tidy [-e] [-v]

flags:
-v
The -v flag causes tidy to print information about removed modules to standard error.
-e
The -e flag causes tidy to attempt to proceed despite errors encountered while loading packages.

Make vendored copy of dependencies

Vendor resets the main module's vendor directory to include all packages needed to build and test all the main module's packages. It does not include test code for vendored packages.

Usage: 
  go mod vendor [-e] [-v]

flags:
-v
The -v flag causes vendor to print the names of vendored modules and packages to standard error.
-e
The -e flag causes vendor to attempt to proceed despite errors encountered while loading packages.

Verify dependencies have expected content

Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded. If all the modules are unmodified, verify prints "all modules verified." Otherwise it reports which modules have been changed and causes 'go mod' to exit with a non-zero status.

Usage: 
  go mod verify

Explain why packages or modules are needed

Why shows a shortest path in the import graph from the main module to each of the listed packages.

Usage: 
  go mod why [-m] [-vendor] packages...

flags:
-m
If the -m flag is given, why treats the arguments as a list of modules and finds a path to any package in each of the modules.
-vendor
The -vendor flag causes why to exclude tests of dependencies.

Related Tags

#go# #go mod#