cmd/go/internal/modget: add help text for module-aware get design
This CL is only the description of the design.
A followup CL will implement it and then delete the old
module-aware get implementation (in cmd/go/internal/vgo/get.go).
Change-Id: I06a17b80488ca0052a75fad175178d9f4e8152d8
Reviewed-on: https://go-review.googlesource.com/121918
Reviewed-by: Bryan C. Mills <bcmills@google.com>
diff --git a/vendor/cmd/go/internal/get/get.go b/vendor/cmd/go/internal/get/get.go
index 2348693..8ab96fb 100644
--- a/vendor/cmd/go/internal/get/get.go
+++ b/vendor/cmd/go/internal/get/get.go
@@ -23,7 +23,7 @@
)
var CmdGet = &base.Command{
- UsageLine: "get [-d] [-f] [-fix] [-insecure] [-t] [-u] [-v] [build flags] [packages]",
+ UsageLine: "get [-d] [-f] [-t] [-u] [-v] [-fix] [-insecure] [build flags] [packages]",
Short: "download and install packages and dependencies",
Long: `
Get downloads the packages named by the import paths, along with their
@@ -74,20 +74,43 @@
For more about how 'go get' finds source code to
download, see 'go help importpath'.
+This text describes the behavior of get when using GOPATH
+to manage source code and dependencies.
+If instead the go command is running in module-aware mode,
+the details of get's flags and effects change, as does 'go help get'.
+See 'go help modules' and 'go help module-get'.
+
See also: go build, go install, go clean.
`,
}
-var getD = CmdGet.Flag.Bool("d", false, "")
-var getF = CmdGet.Flag.Bool("f", false, "")
-var getT = CmdGet.Flag.Bool("t", false, "")
-var getU = CmdGet.Flag.Bool("u", false, "")
-var getFix = CmdGet.Flag.Bool("fix", false, "")
-var getInsecure = CmdGet.Flag.Bool("insecure", false, "")
+var HelpGopathGet = &base.Command{
+ UsageLine: "gopath-get",
+ Short: "legacy GOPATH go get",
+ Long: `
+The 'go get' command changes behavior depending on whether the
+go command is running in module-aware mode or legacy GOPATH mode.
+This help text, accessible as 'go help gopath-get' even in module-aware mode,
+describes 'go get' as it operates in legacy GOPATH mode.
+
+Usage: ` + CmdGet.UsageLine + `
+` + CmdGet.Long,
+}
+
+var (
+ getD = CmdGet.Flag.Bool("d", false, "")
+ getF = CmdGet.Flag.Bool("f", false, "")
+ getT = CmdGet.Flag.Bool("t", false, "")
+ getU = CmdGet.Flag.Bool("u", false, "")
+ getFix = CmdGet.Flag.Bool("fix", false, "")
+
+ Insecure bool
+)
func init() {
work.AddBuildFlags(CmdGet)
CmdGet.Run = runGet // break init loop
+ CmdGet.Flag.BoolVar(&Insecure, "insecure", Insecure, "")
}
func runGet(cmd *base.Command, args []string) {
@@ -379,7 +402,7 @@
)
security := web.Secure
- if *getInsecure {
+ if Insecure {
security = web.Insecure
}
@@ -425,7 +448,7 @@
}
vcs, repo, rootPath = rr.vcs, rr.Repo, rr.Root
}
- if !blindRepo && !vcs.isSecure(repo) && !*getInsecure {
+ if !blindRepo && !vcs.isSecure(repo) && !Insecure {
return fmt.Errorf("cannot download, %v uses insecure protocol", repo)
}
diff --git a/vendor/cmd/go/internal/help/help.go b/vendor/cmd/go/internal/help/help.go
index 488ef7b..48b4625 100644
--- a/vendor/cmd/go/internal/help/help.go
+++ b/vendor/cmd/go/internal/help/help.go
@@ -45,7 +45,15 @@
buf := new(bytes.Buffer)
PrintUsage(buf)
usage := &base.Command{Long: buf.String()}
- tmpl(&commentWriter{W: os.Stdout}, documentationTemplate, append([]*base.Command{usage}, base.Commands...))
+ cmds := []*base.Command{usage}
+ for _, cmd := range base.Commands {
+ if cmd.UsageLine == "gopath-get" {
+ // Avoid duplication of the "get" documentation.
+ continue
+ }
+ cmds = append(cmds, cmd)
+ }
+ tmpl(&commentWriter{W: os.Stdout}, documentationTemplate, cmds)
fmt.Println("package main")
return
}
diff --git a/vendor/cmd/go/internal/help/helpdoc.go b/vendor/cmd/go/internal/help/helpdoc.go
index a90d19e..d675b38 100644
--- a/vendor/cmd/go/internal/help/helpdoc.go
+++ b/vendor/cmd/go/internal/help/helpdoc.go
@@ -30,7 +30,7 @@
var HelpPackages = &base.Command{
UsageLine: "packages",
- Short: "package lists",
+ Short: "package lists and patterns",
Long: `
Many commands apply to a set of packages:
diff --git a/vendor/cmd/go/internal/list/list.go b/vendor/cmd/go/internal/list/list.go
index 15ac82c..855d0d6 100644
--- a/vendor/cmd/go/internal/list/list.go
+++ b/vendor/cmd/go/internal/list/list.go
@@ -259,7 +259,7 @@
module paths match the pattern.
A query of the form path@version specifies the result of that query,
which is not limited to active modules.
-See 'go help modules' for more about patterns and queries.
+See 'go help module' for more about module queries.
The template function "module" takes a single string argument
that must be a module path or query and returns the specified
diff --git a/vendor/cmd/go/internal/modget/get.go b/vendor/cmd/go/internal/modget/get.go
new file mode 100644
index 0000000..17ffdcf
--- /dev/null
+++ b/vendor/cmd/go/internal/modget/get.go
@@ -0,0 +1,157 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package modget implements the module-aware ``go get'' command.
+package modget
+
+import (
+ "cmd/go/internal/base"
+ "cmd/go/internal/get"
+ "cmd/go/internal/work"
+)
+
+var CmdGet = &base.Command{
+ // Note: -d -m -u are listed explicitly because they are the most common get flags.
+ // Do not send CLs removing them because they're covered by [get flags].
+ UsageLine: "get [-d] [-m] [-p] [-u] [-v] [-insecure] [build flags] [packages]",
+ Short: "add dependencies to current module and install them",
+ Long: `
+Get resolves and adds dependencies to the current development module
+and then optionally downloads, builds, and installs them.
+
+The first step is to resolve which dependencies to add.
+
+For each named package or package pattern, get must decide which version of
+the corresponding module to use. By default, get chooses the latest tagged
+release version, such as v0.4.5 or v1.2.3. If there are no tagged release
+versions, get chooses the latest tagged prerelease version, such as
+v0.0.1-pre1. If there are no tagged versions at all, get chooses the latest
+known commit.
+
+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'.
+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'.
+The version suffix @latest explicitly requests the default behavior
+described above.
+
+If a module under consideration is already a dependency of the current
+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.
+
+Although get defaults to using the latest version of the module containing
+a named package, it does not use the latest version of that module's
+dependencies. Instead it prefers to use the specific dependency versions
+requested by that module. For example, if the latest A requires module
+B v1.2.3, while B v1.2.4 and v1.3.1 are also available, then 'go get A'
+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
+those requirements by taking the maximum requested version.)
+
+The -u flag instructs get to update dependencies to use newer minor or
+point releases when available. Continuing the previous example,
+'go get -u A' will use the latest A with B v1.3.1 (not B v1.2.3).
+
+The -u=point flag instructs get to update dependencies to use newer
+point releases when available. Continuing the previous example,
+'go get -u=point A' will use the latest A with B v1.2.4 (not B v1.2.3).
+
+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 dependenceis, and 'go get' does
+this automatically as well.
+
+The second step is to download source code for dependencies.
+This step is usually skipped, deferring the download until the code
+is first needed by a build (at which point it is cached for future use),
+so that building one package in a module does not incur the cost of
+downloading dependencies for other packages in the module.
+
+The -d flag instructs get to download the source code for all added
+modules, including their dependencies, recursively, so that the first
+build that needs the code won't have to download it.
+
+The -insecure flag permits fetching from repositories and resolving
+custom domains using insecure schemes such as HTTP. Use with caution.
+
+The -m flag instructs get to stop here, after resolving, adding, and
+possibly downloading the modules, without building and installing
+any named packages.
+
+The third and final step is to build and install the named packages.
+
+If an argument names a module but not a package (because there is no
+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.
+
+If 'go get' has no package arguments, then it applies to the current
+development module: the -d flag downloads all dependencies of the
+current module, and the -u and -u=point flags update all dependencies
+of the current module. If there is a Go package in the current directory,
+the build and install step applies to that package.
+
+For more about modules, see 'go help modules'.
+
+For more about specifying packages, see 'go help packages'.
+
+This text describes the behavior of get using modules to manage
+source code and dependencies.
+If instead the go command is running in legacy GOPATH 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 also: go build, go install, go clean, go mod.
+ `,
+}
+
+// Note that this help text is a stopgap to make the module-aware get help text
+// available even in non-module settings. It should be deleted when the old get
+// is deleted. It should NOT be considered to set a precedent of having hierarchical
+// help names with dashes.
+var HelpModuleGet = &base.Command{
+ UsageLine: "module-get",
+ Short: "module-aware go get",
+ Long: `
+The 'go get' command changes behavior depending on whether the
+go command is running in module-aware mode or legacy GOPATH mode.
+This help text, accessible as 'go help module-get' even in legacy GOPATH mode,
+describes 'go get' as it operates in module-aware mode.
+
+Usage: ` + CmdGet.UsageLine + `
+` + CmdGet.Long,
+}
+
+var (
+ getD = CmdGet.Flag.Bool("d", false, "")
+ getF = CmdGet.Flag.Bool("f", false, "")
+ getFix = CmdGet.Flag.Bool("fix", false, "")
+ getM = CmdGet.Flag.Bool("m", false, "")
+ getT = CmdGet.Flag.Bool("t", false, "")
+ getU = CmdGet.Flag.Bool("u", false, "")
+ // -insecure is get.Insecure
+ // -v is cfg.BuildV
+)
+
+func init() {
+ work.AddBuildFlags(CmdGet)
+ CmdGet.Run = runGet // break init loop
+ CmdGet.Flag.BoolVar(&get.Insecure, "insecure", get.Insecure, "")
+}
+
+func runGet(cmd *base.Command, args []string) {
+ // OK because the command is also unregistered.
+ // For now we're still running vgo.CmdGet.
+ panic("unimplemented")
+}
diff --git a/vendor/cmd/go/internal/vgo/help.go b/vendor/cmd/go/internal/vgo/help.go
index 4a373e9..9f2e30f 100644
--- a/vendor/cmd/go/internal/vgo/help.go
+++ b/vendor/cmd/go/internal/vgo/help.go
@@ -7,7 +7,7 @@
import "cmd/go/internal/base"
var HelpModule = &base.Command{
- UsageLine: "module",
+ UsageLine: "modules",
Short: "using versioned modules",
Long: `
TODO: write whole thing
diff --git a/vendor/cmd/go/internal/work/build.go b/vendor/cmd/go/internal/work/build.go
index cc4572b..9973e27 100644
--- a/vendor/cmd/go/internal/work/build.go
+++ b/vendor/cmd/go/internal/work/build.go
@@ -89,7 +89,7 @@
-gcflags '[pattern=]arg list'
arguments to pass on each go tool compile invocation.
-getmode mode
- module download mode to use. See 'go help module' for more.
+ module download mode to use. See 'go help modules' for more.
-installsuffix suffix
a suffix to use in the name of the package installation directory,
in order to keep output separate from default builds.
diff --git a/vendor/cmd/go/main.go b/vendor/cmd/go/main.go
index 1190808..2e8595c 100644
--- a/vendor/cmd/go/main.go
+++ b/vendor/cmd/go/main.go
@@ -28,6 +28,7 @@
"cmd/go/internal/help"
"cmd/go/internal/list"
"cmd/go/internal/modcmd"
+ "cmd/go/internal/modget"
"cmd/go/internal/run"
"cmd/go/internal/test"
"cmd/go/internal/tool"
@@ -63,8 +64,10 @@
help.HelpEnvironment,
help.HelpFileType,
help.HelpGopath,
+ get.HelpGopathGet,
help.HelpImportPath,
- vgo.HelpModule,
+ vgo.HelpModules,
+ modget.HelpModuleGet,
help.HelpPackages,
test.HelpTestflag,
test.HelpTestfunc,
