diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index 6703792054d..d90321414a7 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -1372,21 +1372,53 @@ // // Go workspace provides access to operations on workspaces. // -// Note that support for workspaces is built into many other commands, -// not just 'go work'. +// Note that support for workspaces is built into many other commands, not +// just 'go work'. // -// See 'go help modules' for information about Go's module system of -// which workspaces are a part. +// See 'go help modules' for information about Go's module system of which +// workspaces are a part. // // A workspace is specified by a go.work file that specifies a set of -// module directories with the "use" directive. These modules are used -// as root modules by the go command for builds and related operations. -// A workspace that does not specify modules to be used cannot be used -// to do builds from local modules. +// module directories with the "use" directive. These modules are used as +// root modules by the go command for builds and related operations. A +// workspace that does not specify modules to be used cannot be used to do +// builds from local modules. // -// To determine whether the go command is operating in workspace mode, -// use the "go env GOWORK" command. This will specify the workspace -// file being used. +// go.work files are line-oriented. Each line holds a single directive, +// made up of a keyword followed by aruments. For example: +// +// go 1.18 +// +// use ../foo/bar +// use ./baz +// +// replace example.com/foo v1.2.3 => example.com/bar v1.4.5 +// +// The leading keyword can be factored out of adjacent lines to create a block, +// like in Go imports. +// +// use ( +// ../foo/bar +// ./baz +// ) +// +// The use directive specifies a module to be included in the workspace's +// set of main modules. The argument to the use directive is the directory +// containing the module's go.mod file. +// +// The go directive specifies the version of Go the file was written at. It +// is possible there may be future changes in the semantics of workspaces +// that could be controlled by this version, but for now the version +// specified has no effect. +// +// The replace directive has the same syntax as the replace directive in a +// go.mod file and takes precedence over replaces in go.mod files. It is +// primarily intended to override conflicting replaces in different workspace +// modules. +// +// To determine whether the go command is operating in workspace mode, use +// the "go env GOWORK" command. This will specify the workspace file being +// used. // // Usage: // @@ -1478,24 +1510,39 @@ // // go work init [moddirs] // -// Init initializes and writes a new go.work file in the current -// directory, in effect creating a new workspace at the current directory. +// Init initializes and writes a new go.work file in the +// current directory, in effect creating a new workspace at the current +// directory. // -// go work init optionally accepts paths to the workspace modules as arguments. -// If the argument is omitted, an empty workspace with no modules will be created. +// go work init optionally accepts paths to the workspace modules as +// arguments. If the argument is omitted, an empty workspace with no +// modules will be created. // -// See the workspaces design proposal at -// https://go.googlesource.com/proposal/+/master/design/45713-workspace.md for -// more information. +// Each argument path is added to a use directive in the go.work file. The +// current go version will also be listed in the go.work file. // // // Sync workspace build list to modules // // Usage: // -// go work sync [moddirs] +// go work sync // -// go work sync +// Sync syncs the workspace's build list back to the +// workspace's modules +// +// The workspace's build list is the set of versions of all the +// (transitive) dependency modules used to do builds in the workspace. go +// work sync generates that build list using the Minimal Version Selection +// algorithm, and then syncs those versions back to each of modules +// specified in the workspace (with use directives). +// +// The syncing is done by sequentially upgrading each of the dependency +// modules specified in a workspace module to the version in the build list +// if the dependency module's version is not already the same as the build +// list's version. Note that Minimal Version Selection guarantees that the +// build list's version of each module is always the same or higher than +// that in each workspace module. // // // Add modules to workspace file @@ -1504,10 +1551,17 @@ // // go work use [-r] [moddirs] // -// Use provides a command-line interface for adding directories, -// optionally recursively, to a go.work file. +// Use provides a command-line interface for adding +// directories, optionally recursively, to a go.work file. // -// The -r flag searches recursively for modules in the argument directories. +// A use directive will be added to the go.work file for each argument +// directory listed on the command line go.work file, if it exists on disk, +// or removed from the go.work file if it does not exist on disk. +// +// The -r flag searches recursively for modules in the argument +// directories, and the use command operates as if each of the directories +// were specified as arguments: namely, use directives will be added for +// directories that exist, and removed for directories that do not exist. // // // Compile and run Go program diff --git a/src/cmd/go/internal/workcmd/init.go b/src/cmd/go/internal/workcmd/init.go index 2297ac20d0a..cefecee8329 100644 --- a/src/cmd/go/internal/workcmd/init.go +++ b/src/cmd/go/internal/workcmd/init.go @@ -13,22 +13,20 @@ import ( "path/filepath" ) -// TODO(#49232) Add more documentation below. Though this is -// enough for those trying workspaces out, there should be more through -// documentation before Go 1.18 is released. - var cmdInit = &base.Command{ UsageLine: "go work init [moddirs]", Short: "initialize workspace file", - Long: `Init initializes and writes a new go.work file in the current -directory, in effect creating a new workspace at the current directory. + Long: `Init initializes and writes a new go.work file in the +current directory, in effect creating a new workspace at the current +directory. -go work init optionally accepts paths to the workspace modules as arguments. -If the argument is omitted, an empty workspace with no modules will be created. +go work init optionally accepts paths to the workspace modules as +arguments. If the argument is omitted, an empty workspace with no +modules will be created. + +Each argument path is added to a use directive in the go.work file. The +current go version will also be listed in the go.work file. -See the workspaces design proposal at -https://go.googlesource.com/proposal/+/master/design/45713-workspace.md for -more information. `, Run: runInit, } diff --git a/src/cmd/go/internal/workcmd/sync.go b/src/cmd/go/internal/workcmd/sync.go index 5f33e057f6d..a10d15a3b75 100644 --- a/src/cmd/go/internal/workcmd/sync.go +++ b/src/cmd/go/internal/workcmd/sync.go @@ -15,15 +15,26 @@ import ( "golang.org/x/mod/module" ) -// TODO(#49232) Add more documentation below. Though this is -// enough for those trying workspaces out, there should be more thorough -// documentation before Go 1.18 is released. - var cmdSync = &base.Command{ - UsageLine: "go work sync [moddirs]", + UsageLine: "go work sync", Short: "sync workspace build list to modules", - Long: `go work sync`, - Run: runSync, + Long: `Sync syncs the workspace's build list back to the +workspace's modules + +The workspace's build list is the set of versions of all the +(transitive) dependency modules used to do builds in the workspace. go +work sync generates that build list using the Minimal Version Selection +algorithm, and then syncs those versions back to each of modules +specified in the workspace (with use directives). + +The syncing is done by sequentially upgrading each of the dependency +modules specified in a workspace module to the version in the build list +if the dependency module's version is not already the same as the build +list's version. Note that Minimal Version Selection guarantees that the +build list's version of each module is always the same or higher than +that in each workspace module. +`, + Run: runSync, } func init() { diff --git a/src/cmd/go/internal/workcmd/use.go b/src/cmd/go/internal/workcmd/use.go index 97c493685ad..852e5b910c2 100644 --- a/src/cmd/go/internal/workcmd/use.go +++ b/src/cmd/go/internal/workcmd/use.go @@ -16,17 +16,21 @@ import ( "path/filepath" ) -// TODO(#49232) Add more documentation below. Though this is -// enough for those trying workspaces out, there should be more thorough -// documentation before Go 1.18 is released. - var cmdUse = &base.Command{ UsageLine: "go work use [-r] [moddirs]", Short: "add modules to workspace file", - Long: `Use provides a command-line interface for adding directories, -optionally recursively, to a go.work file. + Long: `Use provides a command-line interface for adding +directories, optionally recursively, to a go.work file. -The -r flag searches recursively for modules in the argument directories.`, +A use directive will be added to the go.work file for each argument +directory listed on the command line go.work file, if it exists on disk, +or removed from the go.work file if it does not exist on disk. + +The -r flag searches recursively for modules in the argument +directories, and the use command operates as if each of the directories +were specified as arguments: namely, use directives will be added for +directories that exist, and removed for directories that do not exist. +`, } var useR = cmdUse.Flag.Bool("r", false, "") diff --git a/src/cmd/go/internal/workcmd/work.go b/src/cmd/go/internal/workcmd/work.go index 3ddbfbe7726..5bb0a2e8bad 100644 --- a/src/cmd/go/internal/workcmd/work.go +++ b/src/cmd/go/internal/workcmd/work.go @@ -14,21 +14,53 @@ var CmdWork = &base.Command{ Short: "workspace maintenance", Long: `Go workspace provides access to operations on workspaces. -Note that support for workspaces is built into many other commands, -not just 'go work'. +Note that support for workspaces is built into many other commands, not +just 'go work'. -See 'go help modules' for information about Go's module system of -which workspaces are a part. +See 'go help modules' for information about Go's module system of which +workspaces are a part. A workspace is specified by a go.work file that specifies a set of -module directories with the "use" directive. These modules are used -as root modules by the go command for builds and related operations. -A workspace that does not specify modules to be used cannot be used -to do builds from local modules. +module directories with the "use" directive. These modules are used as +root modules by the go command for builds and related operations. A +workspace that does not specify modules to be used cannot be used to do +builds from local modules. -To determine whether the go command is operating in workspace mode, -use the "go env GOWORK" command. This will specify the workspace -file being used. +go.work files are line-oriented. Each line holds a single directive, +made up of a keyword followed by aruments. For example: + + go 1.18 + + use ../foo/bar + use ./baz + + replace example.com/foo v1.2.3 => example.com/bar v1.4.5 + +The leading keyword can be factored out of adjacent lines to create a block, +like in Go imports. + + use ( + ../foo/bar + ./baz + ) + +The use directive specifies a module to be included in the workspace's +set of main modules. The argument to the use directive is the directory +containing the module's go.mod file. + +The go directive specifies the version of Go the file was written at. It +is possible there may be future changes in the semantics of workspaces +that could be controlled by this version, but for now the version +specified has no effect. + +The replace directive has the same syntax as the replace directive in a +go.mod file and takes precedence over replaces in go.mod files. It is +primarily intended to override conflicting replaces in different workspace +modules. + +To determine whether the go command is operating in workspace mode, use +the "go env GOWORK" command. This will specify the workspace file being +used. `, Commands: []*base.Command{