cmd/go: explain versions better

Summarize the desiderata for selecting versions of remote packages to get.
Fixes #3394.

R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/5902058

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index 775f305d2b6e997b22c8ab1727727d0e60eda2ff..162eecfcc928f2b7f4303315f6e9b4f3e56a1a91 100644 (file)
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -225,7 +225,15 @@ The -u flag instructs get to use the network to update the named packages
 and their dependencies.  By default, get uses the network to check out
 missing packages but does not use it to look for updates to existing packages.
 
-TODO: Explain versions better.
+When checking out or updating a package, get looks for a branch or
+tag that matches the locally installed version of Go. If the local
+version "is release.rNN", it searches for "go.rNN". (For an
+installation using Go version "weekly.YYYY-MM-DD", it searches for a
+package version labeled "go.YYYY-MM-DD".)  If the desired version
+cannot be found but others exist with labels in the correct format,
+get retrieves the most recent version before the desired label.
+Finally, if all else fails it retrieves the most recent version of
+the package.
 
 For more about specifying packages, see 'go help packages'.
 

diff --git a/src/cmd/go/get.go b/src/cmd/go/get.go
index 5db1ff873ba6299a92deeb7011de19b904353a94..c0788d30c6d6ee7d6824c197d0b634c29c283346 100644 (file)
--- a/src/cmd/go/get.go
+++ b/src/cmd/go/get.go
@@ -36,7 +36,15 @@ The -u flag instructs get to use the network to update the named packages
 and their dependencies.  By default, get uses the network to check out
 missing packages but does not use it to look for updates to existing packages.
 
-TODO: Explain versions better.
+When checking out or updating a package, get looks for a branch or
+tag that matches the locally installed version of Go. If the local
+version "is release.rNN", it searches for "go.rNN". (For an
+installation using Go version "weekly.YYYY-MM-DD", it searches for a
+package version labeled "go.YYYY-MM-DD".)  If the desired version
+cannot be found but others exist with labels in the correct format,
+get retrieves the most recent version before the desired label.
+Finally, if all else fails it retrieves the most recent version of
+the package.
 
 For more about specifying packages, see 'go help packages'.