From 21f548400650e4e7047202ee1894ee6ddd44de82 Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Fri, 12 Jul 2019 11:31:29 -0400 Subject: [PATCH] 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 --- src/cmd/go/alldocs.go | 34 +++++++++++++++++++++++------ src/cmd/go/internal/modget/get.go | 9 +++++++- src/cmd/go/internal/modload/help.go | 25 ++++++++++++++++----- 3 files changed, 54 insertions(+), 14 deletions(-) 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, "