mirror of
https://github.com/golang/go
synced 2024-11-11 20:20:23 -07:00
cmd/go: revise 'go help' documentation for modules
Module-related help pages now contain a brief summary and point to the reference documentation at golang.org/ref/mod for details. Help pages for commands like 'go get' still describe the basic usage and summarize flags but don't provide as much background detail. Fixes #41427 Fixes #43419 Change-Id: Icacd38e0f33c352c447cc5a496c99674493abde2 Reviewed-on: https://go-review.googlesource.com/c/go/+/282615 Trust: Jay Conrod <jayconrod@google.com> Run-TryBot: Jay Conrod <jayconrod@google.com> TryBot-Result: Go Bot <gobot@golang.org> Reviewed-by: Bryan C. Mills <bcmills@google.com>
This commit is contained in:
parent
6192b98751
commit
cd6f3a54e4
File diff suppressed because it is too large
Load Diff
@ -266,7 +266,7 @@ listed in the GOPATH environment variable.
|
|||||||
(See 'go help gopath-get' and 'go help gopath'.)
|
(See 'go help gopath-get' and 'go help gopath'.)
|
||||||
|
|
||||||
When using modules, downloaded packages are stored in the module cache.
|
When using modules, downloaded packages are stored in the module cache.
|
||||||
(See 'go help module-get' and 'go help goproxy'.)
|
See https://golang.org/ref/mod#module-cache.
|
||||||
|
|
||||||
When using modules, an additional variant of the go-import meta tag is
|
When using modules, an additional variant of the go-import meta tag is
|
||||||
recognized and is preferred over those listing version control systems.
|
recognized and is preferred over those listing version control systems.
|
||||||
@ -276,7 +276,8 @@ That variant uses "mod" as the vcs in the content value, as in:
|
|||||||
|
|
||||||
This tag means to fetch modules with paths beginning with example.org
|
This tag means to fetch modules with paths beginning with example.org
|
||||||
from the module proxy available at the URL https://code.org/moduleproxy.
|
from the module proxy available at the URL https://code.org/moduleproxy.
|
||||||
See 'go help goproxy' for details about the proxy protocol.
|
See https://golang.org/ref/mod#goproxy-protocol for details about the
|
||||||
|
proxy protocol.
|
||||||
|
|
||||||
Import path checking
|
Import path checking
|
||||||
|
|
||||||
@ -483,6 +484,10 @@ See 'go help env' for details.
|
|||||||
|
|
||||||
General-purpose environment variables:
|
General-purpose environment variables:
|
||||||
|
|
||||||
|
GO111MODULE
|
||||||
|
Controls whether the go command runs in module-aware mode or GOPATH mode.
|
||||||
|
May be "off", "on", or "auto".
|
||||||
|
See https://golang.org/ref/mod#mod-commands.
|
||||||
GCCGO
|
GCCGO
|
||||||
The gccgo command to run for 'go build -compiler=gccgo'.
|
The gccgo command to run for 'go build -compiler=gccgo'.
|
||||||
GOARCH
|
GOARCH
|
||||||
@ -521,20 +526,24 @@ General-purpose environment variables:
|
|||||||
GOPATH
|
GOPATH
|
||||||
For more details see: 'go help gopath'.
|
For more details see: 'go help gopath'.
|
||||||
GOPROXY
|
GOPROXY
|
||||||
URL of Go module proxy. See 'go help modules'.
|
URL of Go module proxy. See https://golang.org/ref/mod#environment-variables
|
||||||
|
and https://golang.org/ref/mod#module-proxy for details.
|
||||||
GOPRIVATE, GONOPROXY, GONOSUMDB
|
GOPRIVATE, GONOPROXY, GONOSUMDB
|
||||||
Comma-separated list of glob patterns (in the syntax of Go's path.Match)
|
Comma-separated list of glob patterns (in the syntax of Go's path.Match)
|
||||||
of module path prefixes that should always be fetched directly
|
of module path prefixes that should always be fetched directly
|
||||||
or that should not be compared against the checksum database.
|
or that should not be compared against the checksum database.
|
||||||
See 'go help private'.
|
See https://golang.org/ref/mod#private-modules.
|
||||||
GOROOT
|
GOROOT
|
||||||
The root of the go tree.
|
The root of the go tree.
|
||||||
GOSUMDB
|
GOSUMDB
|
||||||
The name of checksum database to use and optionally its public key and
|
The name of checksum database to use and optionally its public key and
|
||||||
URL. See 'go help module-auth'.
|
URL. See https://golang.org/ref/mod#authenticating.
|
||||||
GOTMPDIR
|
GOTMPDIR
|
||||||
The directory where the go command will write
|
The directory where the go command will write
|
||||||
temporary source files, packages, and binaries.
|
temporary source files, packages, and binaries.
|
||||||
|
GOVCS
|
||||||
|
Lists version control commands that may be used with matching servers.
|
||||||
|
See 'go help vcs'.
|
||||||
|
|
||||||
Environment variables for use with cgo:
|
Environment variables for use with cgo:
|
||||||
|
|
||||||
|
@ -304,7 +304,7 @@ For more about build flags, see 'go help build'.
|
|||||||
|
|
||||||
For more about specifying packages, see 'go help packages'.
|
For more about specifying packages, see 'go help packages'.
|
||||||
|
|
||||||
For more about modules, see 'go help modules'.
|
For more about modules, see https://golang.org/ref/mod.
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -52,7 +52,9 @@ corresponding to this Go struct:
|
|||||||
|
|
||||||
The -x flag causes download to print the commands download executes.
|
The -x flag causes download to print the commands download executes.
|
||||||
|
|
||||||
See 'go help modules' for more about module queries.
|
See https://golang.org/ref/mod#go-mod-download for more about 'go mod download'.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#version-queries for more about version queries.
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -122,9 +122,7 @@ Note that this only describes the go.mod file itself, not other modules
|
|||||||
referred to indirectly. For the full set of modules available to a build,
|
referred to indirectly. For the full set of modules available to a build,
|
||||||
use 'go list -m -json all'.
|
use 'go list -m -json all'.
|
||||||
|
|
||||||
For example, a tool can obtain the go.mod as a data structure by
|
See https://golang.org/ref/mod#go-mod-edit for more about 'go mod edit'.
|
||||||
parsing the output of 'go mod edit -json' and can then make changes
|
|
||||||
by invoking 'go mod edit' with -require, -exclude, and so on.
|
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -26,6 +26,8 @@ Graph prints the module requirement graph (with replacements applied)
|
|||||||
in text form. Each line in the output has two space-separated fields: a module
|
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
|
and one of its requirements. Each module is identified as a string of the form
|
||||||
path@version, except for the main module, which has no @version suffix.
|
path@version, except for the main module, which has no @version suffix.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-graph for more about 'go mod graph'.
|
||||||
`,
|
`,
|
||||||
Run: runGraph,
|
Run: runGraph,
|
||||||
}
|
}
|
||||||
|
@ -27,6 +27,8 @@ Gopkg.lock), and the current directory (if in GOPATH).
|
|||||||
|
|
||||||
If a configuration file for a vendoring tool is present, init will attempt to
|
If a configuration file for a vendoring tool is present, init will attempt to
|
||||||
import module requirements from it.
|
import module requirements from it.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-init for more about 'go mod init'.
|
||||||
`,
|
`,
|
||||||
Run: runInit,
|
Run: runInit,
|
||||||
}
|
}
|
||||||
|
@ -29,6 +29,8 @@ to standard error.
|
|||||||
|
|
||||||
The -e flag causes tidy to attempt to proceed despite errors
|
The -e flag causes tidy to attempt to proceed despite errors
|
||||||
encountered while loading packages.
|
encountered while loading packages.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-tidy for more about 'go mod tidy'.
|
||||||
`,
|
`,
|
||||||
Run: runTidy,
|
Run: runTidy,
|
||||||
}
|
}
|
||||||
|
@ -38,6 +38,8 @@ modules and packages to standard error.
|
|||||||
|
|
||||||
The -e flag causes vendor to attempt to proceed despite errors
|
The -e flag causes vendor to attempt to proceed despite errors
|
||||||
encountered while loading packages.
|
encountered while loading packages.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-vendor for more about 'go mod vendor'.
|
||||||
`,
|
`,
|
||||||
Run: runVendor,
|
Run: runVendor,
|
||||||
}
|
}
|
||||||
|
@ -31,6 +31,8 @@ modified since being downloaded. If all the modules are unmodified,
|
|||||||
verify prints "all modules verified." Otherwise it reports which
|
verify prints "all modules verified." Otherwise it reports which
|
||||||
modules have been changed and causes 'go mod' to exit with a
|
modules have been changed and causes 'go mod' to exit with a
|
||||||
non-zero status.
|
non-zero status.
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-verify for more about 'go mod verify'.
|
||||||
`,
|
`,
|
||||||
Run: runVerify,
|
Run: runVerify,
|
||||||
}
|
}
|
||||||
|
@ -48,6 +48,8 @@ For example:
|
|||||||
# golang.org/x/text/encoding
|
# golang.org/x/text/encoding
|
||||||
(main module does not need package golang.org/x/text/encoding)
|
(main module does not need package golang.org/x/text/encoding)
|
||||||
$
|
$
|
||||||
|
|
||||||
|
See https://golang.org/ref/mod#go-mod-why for more about 'go mod why'.
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -768,90 +768,14 @@ var HelpModuleAuth = &base.Command{
|
|||||||
UsageLine: "module-auth",
|
UsageLine: "module-auth",
|
||||||
Short: "module authentication using go.sum",
|
Short: "module authentication using go.sum",
|
||||||
Long: `
|
Long: `
|
||||||
The go command tries to authenticate every downloaded module,
|
When the go command downloads a module zip file or go.mod file into the
|
||||||
checking that the bits downloaded for a specific module version today
|
module cache, it computes a cryptographic hash and compares it with a known
|
||||||
match bits downloaded yesterday. This ensures repeatable builds
|
value to verify the file hasn't changed since it was first downloaded. Known
|
||||||
and detects introduction of unexpected changes, malicious or not.
|
hashes are stored in a file in the module root directory named go.sum. Hashes
|
||||||
|
may also be downloaded from the checksum database depending on the values of
|
||||||
|
GOSUMDB, GOPRIVATE, and GONOSUMDB.
|
||||||
|
|
||||||
In each module's root, alongside go.mod, the go command maintains
|
For details, see https://golang.org/ref/mod#authenticating.
|
||||||
a file named go.sum containing the cryptographic checksums of the
|
|
||||||
module's dependencies.
|
|
||||||
|
|
||||||
The form of each line in go.sum is three fields:
|
|
||||||
|
|
||||||
<module> <version>[/go.mod] <hash>
|
|
||||||
|
|
||||||
Each known module version results in two lines in the go.sum file.
|
|
||||||
The first line gives the hash of the module version's file tree.
|
|
||||||
The second line appends "/go.mod" to the version and gives the hash
|
|
||||||
of only the module version's (possibly synthesized) go.mod file.
|
|
||||||
The go.mod-only hash allows downloading and authenticating a
|
|
||||||
module version's go.mod file, which is needed to compute the
|
|
||||||
dependency graph, without also downloading all the module's source code.
|
|
||||||
|
|
||||||
The hash begins with an algorithm prefix of the form "h<N>:".
|
|
||||||
The only defined algorithm prefix is "h1:", which uses SHA-256.
|
|
||||||
|
|
||||||
Module authentication failures
|
|
||||||
|
|
||||||
The go command maintains a cache of downloaded packages and computes
|
|
||||||
and records the cryptographic checksum of each package at download time.
|
|
||||||
In normal operation, the go command checks the main module's go.sum file
|
|
||||||
against these precomputed checksums instead of recomputing them on
|
|
||||||
each command invocation. The 'go mod verify' command checks that
|
|
||||||
the cached copies of module downloads still match both their recorded
|
|
||||||
checksums and the entries in go.sum.
|
|
||||||
|
|
||||||
In day-to-day development, the checksum of a given module version
|
|
||||||
should never change. Each time a dependency is used by a given main
|
|
||||||
module, the go command checks its local cached copy, freshly
|
|
||||||
downloaded or not, against the main module's go.sum. If the checksums
|
|
||||||
don't match, the go command reports the mismatch as a security error
|
|
||||||
and refuses to run the build. When this happens, proceed with caution:
|
|
||||||
code changing unexpectedly means today's build will not match
|
|
||||||
yesterday's, and the unexpected change may not be beneficial.
|
|
||||||
|
|
||||||
If the go command reports a mismatch in go.sum, the downloaded code
|
|
||||||
for the reported module version does not match the one used in a
|
|
||||||
previous build of the main module. It is important at that point
|
|
||||||
to find out what the right checksum should be, to decide whether
|
|
||||||
go.sum is wrong or the downloaded code is wrong. Usually go.sum is right:
|
|
||||||
you want to use the same code you used yesterday.
|
|
||||||
|
|
||||||
If a downloaded module is not yet included in go.sum and it is a publicly
|
|
||||||
available module, the go command consults the Go checksum database to fetch
|
|
||||||
the expected go.sum lines. If the downloaded code does not match those
|
|
||||||
lines, the go command reports the mismatch and exits. Note that the
|
|
||||||
database is not consulted for module versions already listed in go.sum.
|
|
||||||
|
|
||||||
If a go.sum mismatch is reported, it is always worth investigating why
|
|
||||||
the code downloaded today differs from what was downloaded yesterday.
|
|
||||||
|
|
||||||
The GOSUMDB environment variable identifies the name of checksum database
|
|
||||||
to use and optionally its public key and URL, as in:
|
|
||||||
|
|
||||||
GOSUMDB="sum.golang.org"
|
|
||||||
GOSUMDB="sum.golang.org+<publickey>"
|
|
||||||
GOSUMDB="sum.golang.org+<publickey> https://sum.golang.org"
|
|
||||||
|
|
||||||
The go command knows the public key of sum.golang.org, and also that the name
|
|
||||||
sum.golang.google.cn (available inside mainland China) connects to the
|
|
||||||
sum.golang.org checksum database; use of any other database requires giving
|
|
||||||
the public key explicitly.
|
|
||||||
The URL defaults to "https://" followed by the database name.
|
|
||||||
|
|
||||||
GOSUMDB defaults to "sum.golang.org", the Go checksum database run by Google.
|
|
||||||
See https://sum.golang.org/privacy for the service's privacy policy.
|
|
||||||
|
|
||||||
If GOSUMDB is set to "off", or if "go get" is invoked with the -insecure flag,
|
|
||||||
the checksum database is not consulted, and all unrecognized modules are
|
|
||||||
accepted, at the cost of giving up the security guarantee of verified repeatable
|
|
||||||
downloads for all modules. A better way to bypass the checksum database
|
|
||||||
for specific modules is to use the GOPRIVATE or GONOSUMDB environment
|
|
||||||
variables. See 'go help private' for details.
|
|
||||||
|
|
||||||
The 'go env -w' command (see 'go help env') can be used to set these variables
|
|
||||||
for future go command invocations.
|
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -865,8 +789,8 @@ regardless of source, against the public Go checksum database at sum.golang.org.
|
|||||||
These defaults work well for publicly available source code.
|
These defaults work well for publicly available source code.
|
||||||
|
|
||||||
The GOPRIVATE environment variable controls which modules the go command
|
The GOPRIVATE environment variable controls which modules the go command
|
||||||
considers to be private (not available publicly) and should therefore not use the
|
considers to be private (not available publicly) and should therefore not use
|
||||||
proxy or checksum database. The variable is a comma-separated list of
|
the proxy or checksum database. The variable is a comma-separated list of
|
||||||
glob patterns (in the syntax of Go's path.Match) of module path prefixes.
|
glob patterns (in the syntax of Go's path.Match) of module path prefixes.
|
||||||
For example,
|
For example,
|
||||||
|
|
||||||
@ -876,10 +800,6 @@ causes the go command to treat as private any module with a path prefix
|
|||||||
matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private,
|
matching either pattern, including git.corp.example.com/xyzzy, rsc.io/private,
|
||||||
and rsc.io/private/quux.
|
and rsc.io/private/quux.
|
||||||
|
|
||||||
The GOPRIVATE environment variable may be used by other tools as well to
|
|
||||||
identify non-public modules. For example, an editor could use GOPRIVATE
|
|
||||||
to decide whether to hyperlink a package import to a godoc.org page.
|
|
||||||
|
|
||||||
For fine-grained control over module download and validation, the GONOPROXY
|
For fine-grained control over module download and validation, the GONOPROXY
|
||||||
and GONOSUMDB environment variables accept the same kind of glob list
|
and GONOSUMDB environment variables accept the same kind of glob list
|
||||||
and override GOPRIVATE for the specific decision of whether to use the proxy
|
and override GOPRIVATE for the specific decision of whether to use the proxy
|
||||||
@ -892,12 +812,6 @@ users would configure go using:
|
|||||||
GOPROXY=proxy.example.com
|
GOPROXY=proxy.example.com
|
||||||
GONOPROXY=none
|
GONOPROXY=none
|
||||||
|
|
||||||
This would tell the go command and other tools that modules beginning with
|
|
||||||
a corp.example.com subdomain are private but that the company proxy should
|
|
||||||
be used for downloading both public and private modules, because
|
|
||||||
GONOPROXY has been set to a pattern that won't match any modules,
|
|
||||||
overriding GOPRIVATE.
|
|
||||||
|
|
||||||
The GOPRIVATE variable is also used to define the "public" and "private"
|
The GOPRIVATE variable is also used to define the "public" and "private"
|
||||||
patterns for the GOVCS variable; see 'go help vcs'. For that usage,
|
patterns for the GOVCS variable; see 'go help vcs'. For that usage,
|
||||||
GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths
|
GOPRIVATE applies even in GOPATH mode. In that case, it matches import paths
|
||||||
@ -905,5 +819,7 @@ instead of module paths.
|
|||||||
|
|
||||||
The 'go env -w' command (see 'go help env') can be used to set these variables
|
The 'go env -w' command (see 'go help env') can be used to set these variables
|
||||||
for future go command invocations.
|
for future go command invocations.
|
||||||
|
|
||||||
|
For more details, see https://golang.org/ref/mod#private-modules.
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
@ -36,65 +36,8 @@ URLs of a specified form. The requests have no query parameters, so even
|
|||||||
a site serving from a fixed file system (including a file:/// URL)
|
a site serving from a fixed file system (including a file:/// URL)
|
||||||
can be a module proxy.
|
can be a module proxy.
|
||||||
|
|
||||||
The GET requests sent to a Go module proxy are:
|
For details on the GOPROXY protocol, see
|
||||||
|
https://golang.org/ref/mod#goproxy-protocol.
|
||||||
GET $GOPROXY/<module>/@v/list returns a list of known versions of the given
|
|
||||||
module, one per line.
|
|
||||||
|
|
||||||
GET $GOPROXY/<module>/@v/<version>.info returns JSON-formatted metadata
|
|
||||||
about that version of the given module.
|
|
||||||
|
|
||||||
GET $GOPROXY/<module>/@v/<version>.mod returns the go.mod file
|
|
||||||
for that version of the given module.
|
|
||||||
|
|
||||||
GET $GOPROXY/<module>/@v/<version>.zip returns the zip archive
|
|
||||||
for that version of the given module.
|
|
||||||
|
|
||||||
GET $GOPROXY/<module>/@latest returns JSON-formatted metadata about the
|
|
||||||
latest known version of the given module in the same format as
|
|
||||||
<module>/@v/<version>.info. The latest version should be the version of
|
|
||||||
the module the go command may use if <module>/@v/list is empty or no
|
|
||||||
listed version is suitable. <module>/@latest is optional and may not
|
|
||||||
be implemented by a module proxy.
|
|
||||||
|
|
||||||
When resolving the latest version of a module, the go command will request
|
|
||||||
<module>/@v/list, then, if no suitable versions are found, <module>/@latest.
|
|
||||||
The go command prefers, in order: the semantically highest release version,
|
|
||||||
the semantically highest pre-release version, and the chronologically
|
|
||||||
most recent pseudo-version. In Go 1.12 and earlier, the go command considered
|
|
||||||
pseudo-versions in <module>/@v/list to be pre-release versions, but this is
|
|
||||||
no longer true since Go 1.13.
|
|
||||||
|
|
||||||
To avoid problems when serving from case-sensitive file systems,
|
|
||||||
the <module> and <version> elements are case-encoded, replacing every
|
|
||||||
uppercase letter with an exclamation mark followed by the corresponding
|
|
||||||
lower-case letter: github.com/Azure encodes as github.com/!azure.
|
|
||||||
|
|
||||||
The JSON-formatted metadata about a given module corresponds to
|
|
||||||
this Go data structure, which may be expanded in the future:
|
|
||||||
|
|
||||||
type Info struct {
|
|
||||||
Version string // version string
|
|
||||||
Time time.Time // commit time
|
|
||||||
}
|
|
||||||
|
|
||||||
The zip archive for a specific version of a given module is a
|
|
||||||
standard zip file that contains the file tree corresponding
|
|
||||||
to the module's source code and related files. The archive uses
|
|
||||||
slash-separated paths, and every file path in the archive must
|
|
||||||
begin with <module>@<version>/, where the module and version are
|
|
||||||
substituted directly, not case-encoded. The root of the module
|
|
||||||
file tree corresponds to the <module>@<version>/ prefix in the
|
|
||||||
archive.
|
|
||||||
|
|
||||||
Even when downloading directly from version control systems,
|
|
||||||
the go command synthesizes explicit info, mod, and zip files
|
|
||||||
and stores them in its local cache, $GOPATH/pkg/mod/cache/download,
|
|
||||||
the same as if it had downloaded them directly from a proxy.
|
|
||||||
The cache layout is the same as the proxy URL space, so
|
|
||||||
serving $GOPATH/pkg/mod/cache/download at (or copying it to)
|
|
||||||
https://example.com/proxy would let other users access those
|
|
||||||
cached module versions with GOPROXY=https://example.com/proxy.
|
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -56,85 +56,49 @@ var CmdGet = &base.Command{
|
|||||||
UsageLine: "go get [-d] [-t] [-u] [-v] [-insecure] [build flags] [packages]",
|
UsageLine: "go get [-d] [-t] [-u] [-v] [-insecure] [build flags] [packages]",
|
||||||
Short: "add dependencies to current module and install them",
|
Short: "add dependencies to current module and install them",
|
||||||
Long: `
|
Long: `
|
||||||
Get resolves and adds dependencies to the current development module
|
Get resolves its command-line arguments to packages at specific module versions,
|
||||||
and then builds and installs them.
|
updates go.mod to require those versions, downloads source code into the
|
||||||
|
module cache, then builds and installs the named packages.
|
||||||
|
|
||||||
The first step is to resolve which dependencies to add.
|
To add a dependency for a package or upgrade it to its latest version:
|
||||||
|
|
||||||
For each named package or package pattern, get must decide which version of
|
go get example.com/pkg
|
||||||
the corresponding module to use. By default, get looks up the latest tagged
|
|
||||||
release version, such as v0.4.5 or v1.2.3. If there are no tagged release
|
|
||||||
versions, get looks up the latest tagged pre-release version, such as
|
|
||||||
v0.0.1-pre1. If there are no tagged versions at all, get looks up the latest
|
|
||||||
known commit. If the module is not already required at a later version
|
|
||||||
(for example, a pre-release newer than the latest release), get will use
|
|
||||||
the version it looked up. Otherwise, get will use the currently
|
|
||||||
required version.
|
|
||||||
|
|
||||||
This default version selection can be overridden by adding an @version
|
To upgrade or downgrade a package to a specific version:
|
||||||
suffix to the package argument, as in 'go get golang.org/x/text@v0.3.0'.
|
|
||||||
The version may be a prefix: @v1 denotes the latest available version starting
|
|
||||||
with v1. See 'go help modules' under the heading 'Module queries' for the
|
|
||||||
full query syntax.
|
|
||||||
|
|
||||||
For modules stored in source control repositories, the version suffix can
|
go get example.com/pkg@v1.2.3
|
||||||
also be a commit hash, branch identifier, or other syntax known to the
|
|
||||||
source control system, as in 'go get golang.org/x/text@master'. Note that
|
|
||||||
branches with names that overlap with other module query syntax cannot be
|
|
||||||
selected explicitly. For example, the suffix @v2 means the latest version
|
|
||||||
starting with v2, not the branch named v2.
|
|
||||||
|
|
||||||
If a module under consideration is already a dependency of the current
|
To remove a dependency on a module and downgrade modules that require it:
|
||||||
development module, then get will update the required version.
|
|
||||||
Specifying a version earlier than the current required version is valid and
|
|
||||||
downgrades the dependency. The version suffix @none indicates that the
|
|
||||||
dependency should be removed entirely, downgrading or removing modules
|
|
||||||
depending on it as needed.
|
|
||||||
|
|
||||||
The version suffix @latest explicitly requests the latest minor release of
|
go get example.com/mod@none
|
||||||
the module named by the given path. The suffix @upgrade is like @latest but
|
|
||||||
will not downgrade a module if it is already required at a revision or
|
|
||||||
pre-release version newer than the latest released version. The suffix
|
|
||||||
@patch requests the latest patch release: the latest released version
|
|
||||||
with the same major and minor version numbers as the currently required
|
|
||||||
version. Like @upgrade, @patch will not downgrade a module already required
|
|
||||||
at a newer version. If the path is not already required, @upgrade is
|
|
||||||
equivalent to @latest, and @patch is disallowed.
|
|
||||||
|
|
||||||
Although get defaults to using the latest version of the module containing
|
See https://golang.org/ref/mod#go-get for details.
|
||||||
a named package, it does not use the latest version of that module's
|
|
||||||
dependencies. Instead it prefers to use the specific dependency versions
|
The 'go install' command may be used to build and install packages. When a
|
||||||
requested by that module. For example, if the latest A requires module
|
version is specified, 'go install' runs in module-aware mode and ignores
|
||||||
B v1.2.3, while B v1.2.4 and v1.3.1 are also available, then 'go get A'
|
the go.mod file in the current directory. For example:
|
||||||
will use the latest A but then use B v1.2.3, as requested by A. (If there
|
|
||||||
are competing requirements for a particular module, then 'go get' resolves
|
go install example.com/pkg@v1.2.3
|
||||||
those requirements by taking the maximum requested version.)
|
go install example.com/pkg@latest
|
||||||
|
|
||||||
|
See 'go help install' or https://golang.org/ref/mod#go-install for details.
|
||||||
|
|
||||||
|
In addition to build flags (listed in 'go help build') 'go get' accepts the
|
||||||
|
following flags.
|
||||||
|
|
||||||
The -t flag instructs get to consider modules needed to build tests of
|
The -t flag instructs get to consider modules needed to build tests of
|
||||||
packages specified on the command line.
|
packages specified on the command line.
|
||||||
|
|
||||||
The -u flag instructs get to update modules providing dependencies
|
The -u flag instructs get to update modules providing dependencies
|
||||||
of packages named on the command line to use newer minor or patch
|
of packages named on the command line to use newer minor or patch
|
||||||
releases when available. Continuing the previous example, 'go get -u A'
|
releases when available.
|
||||||
will use the latest A with B v1.3.1 (not B v1.2.3). If B requires module C,
|
|
||||||
but C does not provide any packages needed to build packages in A
|
|
||||||
(not including tests), then C will not be updated.
|
|
||||||
|
|
||||||
The -u=patch flag (not -u patch) also instructs get to update dependencies,
|
The -u=patch flag (not -u patch) also instructs get to update dependencies,
|
||||||
but changes the default to select patch releases.
|
but changes the default to select patch releases.
|
||||||
Continuing the previous example,
|
|
||||||
'go get -u=patch A@latest' will use the latest A with B v1.2.4 (not B v1.2.3),
|
|
||||||
while 'go get -u=patch A' will use a patch release of A instead.
|
|
||||||
|
|
||||||
When the -t and -u flags are used together, get will update
|
When the -t and -u flags are used together, get will update
|
||||||
test dependencies as well.
|
test dependencies as well.
|
||||||
|
|
||||||
In general, adding a new dependency may require upgrading
|
|
||||||
existing dependencies to keep a working build, and 'go get' does
|
|
||||||
this automatically. Similarly, downgrading one dependency may
|
|
||||||
require downgrading other dependencies, and 'go get' does
|
|
||||||
this automatically as well.
|
|
||||||
|
|
||||||
The -insecure flag permits fetching from repositories and resolving
|
The -insecure flag permits fetching from repositories and resolving
|
||||||
custom domains using insecure schemes such as HTTP, and also bypassess
|
custom domains using insecure schemes such as HTTP, and also bypassess
|
||||||
module sum validation using the checksum database. Use with caution.
|
module sum validation using the checksum database. Use with caution.
|
||||||
@ -143,12 +107,8 @@ To permit the use of insecure schemes, use the GOINSECURE environment
|
|||||||
variable instead. To bypass module sum validation, use GOPRIVATE or
|
variable instead. To bypass module sum validation, use GOPRIVATE or
|
||||||
GONOSUMDB. See 'go help environment' for details.
|
GONOSUMDB. See 'go help environment' for details.
|
||||||
|
|
||||||
The second step is to download (if needed), build, and install
|
The -d flag instructs get not to build or install packages. get will only
|
||||||
the named packages.
|
update go.mod and download source code needed to build packages.
|
||||||
|
|
||||||
The -d flag instructs get to skip this step, downloading source code
|
|
||||||
needed to build the named packages and their dependencies, but not
|
|
||||||
building or installing.
|
|
||||||
|
|
||||||
Building and installing packages with get is deprecated. In a future release,
|
Building and installing packages with get is deprecated. In a future release,
|
||||||
the -d flag will be enabled by default, and 'go get' will be only be used to
|
the -d flag will be enabled by default, and 'go get' will be only be used to
|
||||||
@ -157,31 +117,14 @@ dependencies from the current module, use 'go install'. To install a package
|
|||||||
ignoring the current module, use 'go install' with an @version suffix like
|
ignoring the current module, use 'go install' with an @version suffix like
|
||||||
"@latest" after each argument.
|
"@latest" after each argument.
|
||||||
|
|
||||||
If an argument names a module but not a package (because there is no
|
For more about modules, see https://golang.org/ref/mod.
|
||||||
Go source code in the module's root directory), then the install step
|
|
||||||
is skipped for that argument, instead of causing a build failure.
|
|
||||||
For example 'go get golang.org/x/perf' succeeds even though there
|
|
||||||
is no code corresponding to that import path.
|
|
||||||
|
|
||||||
Note that package patterns are allowed and are expanded after resolving
|
|
||||||
the module versions. For example, 'go get golang.org/x/perf/cmd/...'
|
|
||||||
adds the latest golang.org/x/perf and then installs the commands in that
|
|
||||||
latest version.
|
|
||||||
|
|
||||||
With no package arguments, 'go get' applies to Go package in the
|
|
||||||
current directory, if any. In particular, 'go get -u' and
|
|
||||||
'go get -u=patch' update all the dependencies of that package.
|
|
||||||
With no package arguments and also without -u, 'go get' is not much more
|
|
||||||
than 'go install', and 'go get -d' not much more than 'go list'.
|
|
||||||
|
|
||||||
For more about modules, see 'go help modules'.
|
|
||||||
|
|
||||||
For more about specifying packages, see 'go help packages'.
|
For more about specifying packages, see 'go help packages'.
|
||||||
|
|
||||||
This text describes the behavior of get using modules to manage source
|
This text describes the behavior of get using modules to manage source
|
||||||
code and dependencies. If instead the go command is running in GOPATH
|
code and dependencies. If instead the go command is running in GOPATH
|
||||||
mode, the details of get's flags and effects change, as does 'go help get'.
|
mode, the details of get's flags and effects change, as does 'go help get'.
|
||||||
See 'go help modules' and 'go help gopath-get'.
|
See 'go help gopath-get'.
|
||||||
|
|
||||||
See also: go build, go install, go clean, go mod.
|
See also: go build, go install, go clean, go mod.
|
||||||
`,
|
`,
|
||||||
|
@ -12,395 +12,16 @@ var HelpModules = &base.Command{
|
|||||||
UsageLine: "modules",
|
UsageLine: "modules",
|
||||||
Short: "modules, module versions, and more",
|
Short: "modules, module versions, and more",
|
||||||
Long: `
|
Long: `
|
||||||
A module is a collection of related Go packages.
|
Modules are how Go manages dependencies.
|
||||||
Modules are the unit of source code interchange and versioning.
|
|
||||||
The go command has direct support for working with modules,
|
|
||||||
including recording and resolving dependencies on other modules.
|
|
||||||
Modules replace the old GOPATH-based approach to specifying
|
|
||||||
which source files are used in a given build.
|
|
||||||
|
|
||||||
Module support
|
A module is a collection of packages that are released, versioned, and
|
||||||
|
distributed together. Modules may be downloaded directly from version control
|
||||||
|
repositories or from module proxy servers.
|
||||||
|
|
||||||
The go command includes support for Go modules. Module-aware mode is active
|
For a series of tutorials on modules, see
|
||||||
by default whenever a go.mod file is found in the current directory or in
|
https://golang.org/doc/tutorial/create-module.
|
||||||
any parent directory.
|
|
||||||
|
|
||||||
The quickest way to take advantage of module support is to check out your
|
For a detailed reference on modules, see https://golang.org/ref/mod.
|
||||||
repository, create a go.mod file (described in the next section) there, and run
|
|
||||||
go commands from within that file tree.
|
|
||||||
|
|
||||||
For more fine-grained control, the go command continues to respect
|
|
||||||
a temporary environment variable, GO111MODULE, which can be set to one
|
|
||||||
of three string values: off, on, or auto (the default).
|
|
||||||
If GO111MODULE=on, then the go command requires the use of modules,
|
|
||||||
never consulting GOPATH. We refer to this as the command
|
|
||||||
being module-aware or running in "module-aware mode".
|
|
||||||
If GO111MODULE=off, then the go command never uses
|
|
||||||
module support. Instead it looks in vendor directories and GOPATH
|
|
||||||
to find dependencies; we now refer to this as "GOPATH mode."
|
|
||||||
If GO111MODULE=auto or is unset, then the go command enables or disables
|
|
||||||
module support based on the current directory.
|
|
||||||
Module support is enabled only when the current directory contains a
|
|
||||||
go.mod file or is below a directory containing a go.mod file.
|
|
||||||
|
|
||||||
In module-aware mode, GOPATH no longer defines the meaning of imports
|
|
||||||
during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod)
|
|
||||||
and installed commands (in GOPATH/bin, unless GOBIN is set).
|
|
||||||
|
|
||||||
Defining a module
|
|
||||||
|
|
||||||
A module is defined by a tree of Go source files with a go.mod file
|
|
||||||
in the tree's root directory. The directory containing the go.mod file
|
|
||||||
is called the module root. Typically the module root will also correspond
|
|
||||||
to a source code repository root (but in general it need not).
|
|
||||||
The module is the set of all Go packages in the module root and its
|
|
||||||
subdirectories, but excluding subtrees with their own go.mod files.
|
|
||||||
|
|
||||||
The "module path" is the import path prefix corresponding to the module root.
|
|
||||||
The go.mod file defines the module path and lists the specific versions
|
|
||||||
of other modules that should be used when resolving imports during a build,
|
|
||||||
by giving their module paths and versions.
|
|
||||||
|
|
||||||
For example, this go.mod declares that the directory containing it is the root
|
|
||||||
of the module with path example.com/m, and it also declares that the module
|
|
||||||
depends on specific versions of golang.org/x/text and gopkg.in/yaml.v2:
|
|
||||||
|
|
||||||
module example.com/m
|
|
||||||
|
|
||||||
require (
|
|
||||||
golang.org/x/text v0.3.0
|
|
||||||
gopkg.in/yaml.v2 v2.1.0
|
|
||||||
)
|
|
||||||
|
|
||||||
The go.mod file can also specify replacements and excluded versions
|
|
||||||
that only apply when building the module directly; they are ignored
|
|
||||||
when the module is incorporated into a larger build.
|
|
||||||
For more about the go.mod file, see 'go help go.mod'.
|
|
||||||
|
|
||||||
To start a new module, simply create a go.mod file in the root of the
|
|
||||||
module's directory tree, containing only a module statement.
|
|
||||||
The 'go mod init' command can be used to do this:
|
|
||||||
|
|
||||||
go mod init example.com/m
|
|
||||||
|
|
||||||
In a project already using an existing dependency management tool like
|
|
||||||
godep, glide, or dep, 'go mod init' will also add require statements
|
|
||||||
matching the existing configuration.
|
|
||||||
|
|
||||||
Once the go.mod file exists, no additional steps are required:
|
|
||||||
go commands like 'go build', 'go test', or even 'go list' will automatically
|
|
||||||
add new dependencies as needed to satisfy imports.
|
|
||||||
|
|
||||||
The main module and the build list
|
|
||||||
|
|
||||||
The "main module" is the module containing the directory where the go command
|
|
||||||
is run. The go command finds the module root by looking for a go.mod in the
|
|
||||||
current directory, or else the current directory's parent directory,
|
|
||||||
or else the parent's parent directory, and so on.
|
|
||||||
|
|
||||||
The main module's go.mod file defines the precise set of packages available
|
|
||||||
for use by the go command, through require, replace, and exclude statements.
|
|
||||||
Dependency modules, found by following require statements, also contribute
|
|
||||||
to the definition of that set of packages, but only through their go.mod
|
|
||||||
files' require statements: any replace and exclude statements in dependency
|
|
||||||
modules are ignored. The replace and exclude statements therefore allow the
|
|
||||||
main module complete control over its own build, without also being subject
|
|
||||||
to complete control by dependencies.
|
|
||||||
|
|
||||||
The set of modules providing packages to builds is called the "build list".
|
|
||||||
The build list initially contains only the main module. Then the go command
|
|
||||||
adds to the list the exact module versions required by modules already
|
|
||||||
on the list, recursively, until there is nothing left to add to the list.
|
|
||||||
If multiple versions of a particular module are added to the list,
|
|
||||||
then at the end only the latest version (according to semantic version
|
|
||||||
ordering) is kept for use in the build.
|
|
||||||
|
|
||||||
The 'go list' command provides information about the main module
|
|
||||||
and the build list. For example:
|
|
||||||
|
|
||||||
go list -m # print path of main module
|
|
||||||
go list -m -f={{.Dir}} # print root directory of main module
|
|
||||||
go list -m all # print build list
|
|
||||||
|
|
||||||
Maintaining module requirements
|
|
||||||
|
|
||||||
The go.mod file is meant to be readable and editable by both programmers and
|
|
||||||
tools. Most updates to dependencies can be performed using "go get" and
|
|
||||||
"go mod tidy". Other module-aware build commands may be invoked using the
|
|
||||||
-mod=mod flag to automatically add missing requirements and fix inconsistencies.
|
|
||||||
|
|
||||||
The "go get" command updates go.mod to change the module versions used in a
|
|
||||||
build. An upgrade of one module may imply upgrading others, and similarly a
|
|
||||||
downgrade of one module may imply downgrading others. The "go get" command
|
|
||||||
makes these implied changes as well. See "go help module-get".
|
|
||||||
|
|
||||||
The "go mod" command provides other functionality for use in maintaining
|
|
||||||
and understanding modules and go.mod files. See "go help mod", particularly
|
|
||||||
"go help mod tidy" and "go help mod edit".
|
|
||||||
|
|
||||||
As part of maintaining the require statements in go.mod, the go command
|
|
||||||
tracks which ones provide packages imported directly by the current module
|
|
||||||
and which ones provide packages only used indirectly by other module
|
|
||||||
dependencies. Requirements needed only for indirect uses are marked with a
|
|
||||||
"// indirect" comment in the go.mod file. Indirect requirements may be
|
|
||||||
automatically removed from the go.mod file once they are implied by other
|
|
||||||
direct requirements. Indirect requirements only arise when using modules
|
|
||||||
that fail to state some of their own dependencies or when explicitly
|
|
||||||
upgrading a module's dependencies ahead of its own stated requirements.
|
|
||||||
|
|
||||||
The -mod build flag provides additional control over the updating and use of
|
|
||||||
go.mod for commands that build packages like "go build" and "go test".
|
|
||||||
|
|
||||||
If invoked with -mod=readonly (the default in most situations), the go command
|
|
||||||
reports an error if a package named on the command line or an imported package
|
|
||||||
is not provided by any module in the build list computed from the main module's
|
|
||||||
requirements. The go command also reports an error if a module's checksum is
|
|
||||||
missing from go.sum (see Module downloading and verification). Either go.mod or
|
|
||||||
go.sum must be updated in these situations.
|
|
||||||
|
|
||||||
If invoked with -mod=mod, the go command automatically updates go.mod and
|
|
||||||
go.sum, fixing inconsistencies and adding missing requirements and checksums
|
|
||||||
as needed. If the go command finds an unfamiliar import, it looks up the
|
|
||||||
module containing that import and adds a requirement for the latest version
|
|
||||||
of that module to go.mod. In most cases, therefore, one may add an import to
|
|
||||||
source code and run "go build", "go test", or even "go list" with -mod=mod:
|
|
||||||
as part of analyzing the package, the go command will resolve the import and
|
|
||||||
update the go.mod file.
|
|
||||||
|
|
||||||
If invoked with -mod=vendor, the go command loads packages from the main
|
|
||||||
module's vendor directory instead of downloading modules to and loading packages
|
|
||||||
from the module cache. The go command assumes the vendor directory holds
|
|
||||||
correct copies of dependencies, and it does not compute the set of required
|
|
||||||
module versions from go.mod files. However, the go command does check that
|
|
||||||
vendor/modules.txt (generated by "go mod vendor") contains metadata consistent
|
|
||||||
with go.mod.
|
|
||||||
|
|
||||||
If the go command is not invoked with a -mod flag, and the vendor directory
|
|
||||||
is present, and the "go" version in go.mod is 1.14 or higher, the go command
|
|
||||||
will act as if it were invoked with -mod=vendor. Otherwise, the -mod flag
|
|
||||||
defaults to -mod=readonly.
|
|
||||||
|
|
||||||
Note that neither "go get" nor the "go mod" subcommands accept the -mod flag.
|
|
||||||
|
|
||||||
Pseudo-versions
|
|
||||||
|
|
||||||
The go.mod file and the go command more generally use semantic versions as
|
|
||||||
the standard form for describing module versions, so that versions can be
|
|
||||||
compared to determine which should be considered earlier or later than another.
|
|
||||||
A module version like v1.2.3 is introduced by tagging a revision in the
|
|
||||||
underlying source repository. Untagged revisions can be referred to
|
|
||||||
using a "pseudo-version" like v0.0.0-yyyymmddhhmmss-abcdefabcdef,
|
|
||||||
where the time is the commit time in UTC and the final suffix is the prefix
|
|
||||||
of the commit hash. The time portion ensures that two pseudo-versions can
|
|
||||||
be compared to determine which happened later, the commit hash identifes
|
|
||||||
the underlying commit, and the prefix (v0.0.0- in this example) is derived from
|
|
||||||
the most recent tagged version in the commit graph before this commit.
|
|
||||||
|
|
||||||
There are three pseudo-version forms:
|
|
||||||
|
|
||||||
vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no earlier
|
|
||||||
versioned commit with an appropriate major version before the target commit.
|
|
||||||
(This was originally the only form, so some older go.mod files use this form
|
|
||||||
even for commits that do follow tags.)
|
|
||||||
|
|
||||||
vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the most
|
|
||||||
recent versioned commit before the target commit is vX.Y.Z-pre.
|
|
||||||
|
|
||||||
vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the most
|
|
||||||
recent versioned commit before the target commit is vX.Y.Z.
|
|
||||||
|
|
||||||
Pseudo-versions never need to be typed by hand: the go command will accept
|
|
||||||
the plain commit hash and translate it into a pseudo-version (or a tagged
|
|
||||||
version if available) automatically. This conversion is an example of a
|
|
||||||
module query.
|
|
||||||
|
|
||||||
Module queries
|
|
||||||
|
|
||||||
The go command accepts a "module query" in place of a module version
|
|
||||||
both on the command line and in the main module's go.mod file.
|
|
||||||
(After evaluating a query found in the main module's go.mod file,
|
|
||||||
the go command updates the file to replace the query with its result.)
|
|
||||||
|
|
||||||
A fully-specified semantic version, such as "v1.2.3",
|
|
||||||
evaluates to that specific version.
|
|
||||||
|
|
||||||
A semantic version prefix, such as "v1" or "v1.2",
|
|
||||||
evaluates to the latest available tagged version with that prefix.
|
|
||||||
|
|
||||||
A semantic version comparison, such as "<v1.2.3" or ">=v1.5.6",
|
|
||||||
evaluates to the available tagged version nearest to the comparison target
|
|
||||||
(the latest version for < and <=, the earliest version for > and >=).
|
|
||||||
|
|
||||||
The string "latest" matches the latest available tagged version,
|
|
||||||
or else the underlying source repository's latest untagged revision.
|
|
||||||
|
|
||||||
The string "upgrade" is like "latest", but if the module is
|
|
||||||
currently required at a later version than the version "latest"
|
|
||||||
would select (for example, a newer pre-release version), "upgrade"
|
|
||||||
will select the later version instead.
|
|
||||||
|
|
||||||
The string "patch" matches the latest available tagged version
|
|
||||||
of a module with the same major and minor version numbers as the
|
|
||||||
currently required version. If no version is currently required,
|
|
||||||
"patch" is equivalent to "latest".
|
|
||||||
|
|
||||||
A revision identifier for the underlying source repository, such as
|
|
||||||
a commit hash prefix, revision tag, or branch name, selects that
|
|
||||||
specific code revision. If the revision is also tagged with a
|
|
||||||
semantic version, the query evaluates to that semantic version.
|
|
||||||
Otherwise the query evaluates to a pseudo-version for the commit.
|
|
||||||
Note that branches and tags with names that are matched by other
|
|
||||||
query syntax cannot be selected this way. For example, the query
|
|
||||||
"v2" means the latest version starting with "v2", not the branch
|
|
||||||
named "v2".
|
|
||||||
|
|
||||||
All queries prefer release versions to pre-release versions.
|
|
||||||
For example, "<v1.2.3" will prefer to return "v1.2.2"
|
|
||||||
instead of "v1.2.3-pre1", even though "v1.2.3-pre1" is nearer
|
|
||||||
to the comparison target.
|
|
||||||
|
|
||||||
Module versions disallowed by exclude statements in the
|
|
||||||
main module's go.mod are considered unavailable and cannot
|
|
||||||
be returned by queries.
|
|
||||||
|
|
||||||
For example, these commands are all valid:
|
|
||||||
|
|
||||||
go get github.com/gorilla/mux@latest # same (@latest is default for 'go get')
|
|
||||||
go get github.com/gorilla/mux@v1.6.2 # records v1.6.2
|
|
||||||
go get github.com/gorilla/mux@e3702bed2 # records v1.6.2
|
|
||||||
go get github.com/gorilla/mux@c856192 # records v0.0.0-20180517173623-c85619274f5d
|
|
||||||
go get github.com/gorilla/mux@master # records current meaning of master
|
|
||||||
|
|
||||||
Module compatibility and semantic versioning
|
|
||||||
|
|
||||||
The go command requires that modules use semantic versions and expects that
|
|
||||||
the versions accurately describe compatibility: it assumes that v1.5.4 is a
|
|
||||||
backwards-compatible replacement for v1.5.3, v1.4.0, and even v1.0.0.
|
|
||||||
More generally the go command expects that packages follow the
|
|
||||||
"import compatibility rule", which says:
|
|
||||||
|
|
||||||
"If an old package and a new package have the same import path,
|
|
||||||
the new package must be backwards compatible with the old package."
|
|
||||||
|
|
||||||
Because the go command assumes the import compatibility rule,
|
|
||||||
a module definition can only set the minimum required version of one
|
|
||||||
of its dependencies: it cannot set a maximum or exclude selected versions.
|
|
||||||
Still, the import compatibility rule is not a guarantee: it may be that
|
|
||||||
v1.5.4 is buggy and not a backwards-compatible replacement for v1.5.3.
|
|
||||||
Because of this, the go command never updates from an older version
|
|
||||||
to a newer version of a module unasked.
|
|
||||||
|
|
||||||
In semantic versioning, changing the major version number indicates a lack
|
|
||||||
of backwards compatibility with earlier versions. To preserve import
|
|
||||||
compatibility, the go command requires that modules with major version v2
|
|
||||||
or later use a module path with that major version as the final element.
|
|
||||||
For example, version v2.0.0 of example.com/m must instead use module path
|
|
||||||
example.com/m/v2, and packages in that module would use that path as
|
|
||||||
their import path prefix, as in example.com/m/v2/sub/pkg. Including the
|
|
||||||
major version number in the module path and import paths in this way is
|
|
||||||
called "semantic import versioning". Pseudo-versions for modules with major
|
|
||||||
version v2 and later begin with that major version instead of v0, as in
|
|
||||||
v2.0.0-20180326061214-4fc5987536ef.
|
|
||||||
|
|
||||||
As a special case, module paths beginning with gopkg.in/ continue to use the
|
|
||||||
conventions established on that system: the major version is always present,
|
|
||||||
and it is preceded by a dot instead of a slash: gopkg.in/yaml.v1
|
|
||||||
and gopkg.in/yaml.v2, not gopkg.in/yaml and gopkg.in/yaml/v2.
|
|
||||||
|
|
||||||
The go command treats modules with different module paths as unrelated:
|
|
||||||
it makes no connection between example.com/m and example.com/m/v2.
|
|
||||||
Modules with different major versions can be used together in a build
|
|
||||||
and are kept separate by the fact that their packages use different
|
|
||||||
import paths.
|
|
||||||
|
|
||||||
In semantic versioning, major version v0 is for initial development,
|
|
||||||
indicating no expectations of stability or backwards compatibility.
|
|
||||||
Major version v0 does not appear in the module path, because those
|
|
||||||
versions are preparation for v1.0.0, and v1 does not appear in the
|
|
||||||
module path either.
|
|
||||||
|
|
||||||
Code written before the semantic import versioning convention
|
|
||||||
was introduced may use major versions v2 and later to describe
|
|
||||||
the same set of unversioned import paths as used in v0 and v1.
|
|
||||||
To accommodate such code, if a source code repository has a
|
|
||||||
v2.0.0 or later tag for a file tree with no go.mod, the version is
|
|
||||||
considered to be part of the v1 module's available versions
|
|
||||||
and is given an +incompatible suffix when converted to a module
|
|
||||||
version, as in v2.0.0+incompatible. The +incompatible tag is also
|
|
||||||
applied to pseudo-versions derived from such versions, as in
|
|
||||||
v2.0.1-0.yyyymmddhhmmss-abcdefabcdef+incompatible.
|
|
||||||
|
|
||||||
In general, having a dependency in the build list (as reported by 'go list -m all')
|
|
||||||
on a v0 version, pre-release version, pseudo-version, or +incompatible version
|
|
||||||
is an indication that problems are more likely when upgrading that
|
|
||||||
dependency, since there is no expectation of compatibility for those.
|
|
||||||
|
|
||||||
See https://research.swtch.com/vgo-import for more information about
|
|
||||||
semantic import versioning, and see https://semver.org/ for more about
|
|
||||||
semantic versioning.
|
|
||||||
|
|
||||||
Module code layout
|
|
||||||
|
|
||||||
For now, see https://research.swtch.com/vgo-module for information
|
|
||||||
about how source code in version control systems is mapped to
|
|
||||||
module file trees.
|
|
||||||
|
|
||||||
Module downloading and verification
|
|
||||||
|
|
||||||
The go command can fetch modules from a proxy or connect to source control
|
|
||||||
servers directly, according to the setting of the GOPROXY environment
|
|
||||||
variable (see 'go help env'). The default setting for GOPROXY is
|
|
||||||
"https://proxy.golang.org,direct", which means to try the
|
|
||||||
Go module mirror run by Google and fall back to a direct connection
|
|
||||||
if the proxy reports that it does not have the module (HTTP error 404 or 410).
|
|
||||||
See https://proxy.golang.org/privacy for the service's privacy policy.
|
|
||||||
|
|
||||||
If GOPROXY is set to the string "direct", downloads use a direct connection to
|
|
||||||
source control servers. Setting GOPROXY to "off" disallows downloading modules
|
|
||||||
from any source. Otherwise, GOPROXY is expected to be list of module proxy URLs
|
|
||||||
separated by either comma (,) or pipe (|) characters, which control error
|
|
||||||
fallback behavior. For each request, the go command tries each proxy in
|
|
||||||
sequence. If there is an error, the go command will try the next proxy in the
|
|
||||||
list if the error is a 404 or 410 HTTP response or if the current proxy is
|
|
||||||
followed by a pipe character, indicating it is safe to fall back on any error.
|
|
||||||
|
|
||||||
The GOPRIVATE and GONOPROXY environment variables allow bypassing
|
|
||||||
the proxy for selected modules. See 'go help private' for details.
|
|
||||||
|
|
||||||
No matter the source of the modules, the go command checks downloads against
|
|
||||||
known checksums, to detect unexpected changes in the content of any specific
|
|
||||||
module version from one day to the next. This check first consults the current
|
|
||||||
module's go.sum file but falls back to the Go checksum database, controlled by
|
|
||||||
the GOSUMDB and GONOSUMDB environment variables. See 'go help module-auth'
|
|
||||||
for details.
|
|
||||||
|
|
||||||
See 'go help goproxy' for details about the proxy protocol and also
|
|
||||||
the format of the cached downloaded packages.
|
|
||||||
|
|
||||||
Modules and vendoring
|
|
||||||
|
|
||||||
When using modules, the go command typically satisfies dependencies by
|
|
||||||
downloading modules from their sources and using those downloaded copies
|
|
||||||
(after verification, as described in the previous section). Vendoring may
|
|
||||||
be used to allow interoperation with older versions of Go, or to ensure
|
|
||||||
that all files used for a build are stored together in a single file tree.
|
|
||||||
|
|
||||||
The command 'go mod vendor' constructs a directory named vendor in the main
|
|
||||||
module's root directory that contains copies of all packages needed to support
|
|
||||||
builds and tests of packages in the main module. 'go mod vendor' also
|
|
||||||
creates the file vendor/modules.txt that contains metadata about vendored
|
|
||||||
packages and module versions. This file should be kept consistent with go.mod:
|
|
||||||
when vendoring is used, 'go mod vendor' should be run after go.mod is updated.
|
|
||||||
|
|
||||||
If the vendor directory is present in the main module's root directory, it will
|
|
||||||
be used automatically if the "go" version in the main module's go.mod file is
|
|
||||||
1.14 or higher. Build commands like 'go build' and 'go test' will load packages
|
|
||||||
from the vendor directory instead of accessing the network or the local module
|
|
||||||
cache. To explicitly enable vendoring, invoke the go command with the flag
|
|
||||||
-mod=vendor. To disable vendoring, use the flag -mod=mod.
|
|
||||||
|
|
||||||
Unlike vendoring in GOPATH, the go command ignores vendor directories in
|
|
||||||
locations other than the main module's root directory.
|
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -413,87 +34,22 @@ file in its root. When the go command is run, it looks in the current
|
|||||||
directory and then successive parent directories to find the go.mod
|
directory and then successive parent directories to find the go.mod
|
||||||
marking the root of the main (current) module.
|
marking the root of the main (current) module.
|
||||||
|
|
||||||
The go.mod file itself is line-oriented, with // comments but
|
The go.mod file format is described in detail at
|
||||||
no /* */ comments. Each line holds a single directive, made up of a
|
https://golang.org/ref/mod#go-mod-file.
|
||||||
verb followed by arguments. For example:
|
|
||||||
|
|
||||||
module my/thing
|
To create a new go.mod file, use 'go help init'. For details see
|
||||||
go 1.12
|
'go help mod init' or https://golang.org/ref/mod#go-mod-init.
|
||||||
require other/thing v1.0.2
|
|
||||||
require new/thing/v2 v2.3.4
|
|
||||||
exclude old/thing v1.2.3
|
|
||||||
replace bad/thing v1.4.5 => good/thing v1.4.5
|
|
||||||
retract v1.5.6
|
|
||||||
|
|
||||||
The verbs are
|
To add missing module requirements or remove unneeded requirements,
|
||||||
module, to define the module path;
|
use 'go mod tidy'. For details, see 'go help mod tidy' or
|
||||||
go, to set the expected language version;
|
https://golang.org/ref/mod#go-mod-tidy.
|
||||||
require, to require a particular module at a given version or later;
|
|
||||||
exclude, to exclude a particular module version from use;
|
|
||||||
replace, to replace a module version with a different module version; and
|
|
||||||
retract, to indicate a previously released version should not be used.
|
|
||||||
Exclude and replace apply only in the main module's go.mod and are ignored
|
|
||||||
in dependencies. See https://golang.org/ref/mod for details.
|
|
||||||
|
|
||||||
The leading verb can be factored out of adjacent lines to create a block,
|
To add, upgrade, downgrade, or remove a specific module requirement, use
|
||||||
like in Go imports:
|
'go get'. For details, see 'go help module-get' or
|
||||||
|
https://golang.org/ref/mod#go-get.
|
||||||
|
|
||||||
require (
|
To make other changes or to parse go.mod as JSON for use by other tools,
|
||||||
new/thing/v2 v2.3.4
|
use 'go mod edit'. See 'go help mod edit' or
|
||||||
old/thing v1.2.3
|
https://golang.org/ref/mod#go-mod-edit.
|
||||||
)
|
|
||||||
|
|
||||||
The go.mod file is designed both to be edited directly and to be
|
|
||||||
easily updated by tools. The 'go mod edit' command can be used to
|
|
||||||
parse and edit the go.mod file from programs and tools.
|
|
||||||
See 'go help mod edit'.
|
|
||||||
|
|
||||||
The go command automatically updates go.mod each time it uses the
|
|
||||||
module graph, to make sure go.mod always accurately reflects reality
|
|
||||||
and is properly formatted. For example, consider this go.mod file:
|
|
||||||
|
|
||||||
module M
|
|
||||||
|
|
||||||
require (
|
|
||||||
A v1
|
|
||||||
B v1.0.0
|
|
||||||
C v1.0.0
|
|
||||||
D v1.2.3
|
|
||||||
E dev
|
|
||||||
)
|
|
||||||
|
|
||||||
exclude D v1.2.3
|
|
||||||
|
|
||||||
The update rewrites non-canonical version identifiers to semver form,
|
|
||||||
so A's v1 becomes v1.0.0 and E's dev becomes the pseudo-version for the
|
|
||||||
latest commit on the dev branch, perhaps v0.0.0-20180523231146-b3f5c0f6e5f1.
|
|
||||||
|
|
||||||
The update modifies requirements to respect exclusions, so the
|
|
||||||
requirement on the excluded D v1.2.3 is updated to use the next
|
|
||||||
available version of D, perhaps D v1.2.4 or D v1.3.0.
|
|
||||||
|
|
||||||
The update removes redundant or misleading requirements.
|
|
||||||
For example, if A v1.0.0 itself requires B v1.2.0 and C v1.0.0,
|
|
||||||
then go.mod's requirement of B v1.0.0 is misleading (superseded by
|
|
||||||
A's need for v1.2.0), and its requirement of C v1.0.0 is redundant
|
|
||||||
(implied by A's need for the same version), so both will be removed.
|
|
||||||
If module M contains packages that directly import packages from B or
|
|
||||||
C, then the requirements will be kept but updated to the actual
|
|
||||||
versions being used.
|
|
||||||
|
|
||||||
Finally, the update reformats the go.mod in a canonical formatting, so
|
|
||||||
that future mechanical changes will result in minimal diffs.
|
|
||||||
|
|
||||||
Because the module graph defines the meaning of import statements, any
|
|
||||||
commands that load packages also use and therefore update go.mod,
|
|
||||||
including go build, go get, go install, go list, go test, go mod graph,
|
|
||||||
go mod tidy, and go mod why.
|
|
||||||
|
|
||||||
The expected language version, set by the go directive, determines
|
|
||||||
which language features are available when compiling the module.
|
|
||||||
Language features available in that version will be available for use.
|
|
||||||
Language features removed in earlier versions, or added in later versions,
|
|
||||||
will not be available. Note that the language version does not affect
|
|
||||||
build tags, which are determined by the Go release being used.
|
|
||||||
`,
|
`,
|
||||||
}
|
}
|
||||||
|
@ -113,7 +113,10 @@ and test commands:
|
|||||||
created with -buildmode=shared.
|
created with -buildmode=shared.
|
||||||
-mod mode
|
-mod mode
|
||||||
module download mode to use: readonly, vendor, or mod.
|
module download mode to use: readonly, vendor, or mod.
|
||||||
See 'go help modules' for more.
|
By default, if a vendor directory is present and the go version in go.mod
|
||||||
|
is 1.14 or higher, the go command acts as if -mod=vendor were set.
|
||||||
|
Otherwise, the go command acts as if -mod=readonly were set.
|
||||||
|
See https://golang.org/ref/mod#build-commands for details.
|
||||||
-modcacherw
|
-modcacherw
|
||||||
leave newly-created directories in the module cache read-write
|
leave newly-created directories in the module cache read-write
|
||||||
instead of making them read-only.
|
instead of making them read-only.
|
||||||
|
Loading…
Reference in New Issue
Block a user