From: Jay Conrod Date: Fri, 12 Jul 2019 15:31:29 +0000 (-0400) Subject: cmd/go: improve module version query documentation X-Git-Tag: go1.13rc1~100 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=21f548400650e4e7047202ee1894ee6ddd44de82;p=gostls13.git cmd/go: improve module version query documentation Add "upgrade" and "patch" to 'go help modules' section 'Module queries'. Also explicitly call out the fact that @v2 will select the latest version starting with v2, not the branch named v2, since this is a common source of confusion. Fixes #33010 Change-Id: I2fe27543b81a160fb6f6b8e8444a7a35f3661433 Reviewed-on: https://go-review.googlesource.com/c/go/+/185979 Run-TryBot: Jay Conrod TryBot-Result: Gobot Gobot Reviewed-by: Bryan C. Mills --- diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 44d07c1197..7999024ce2 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -574,9 +574,16 @@ // // This default version selection can be overridden by adding an @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 // 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'. +// 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 // development module, then get will update the required version. @@ -2499,12 +2506,25 @@ // The string "latest" matches the latest available tagged version, // or else the underlying source repository's latest untagged revision. // -// 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. +// 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, "