1// Copyright 2021 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package workcmd implements the “go work” command.
6package workcmd
7
8import (
9	"cmd/go/internal/base"
10)
11
12var CmdWork = &base.Command{
13	UsageLine: "go work",
14	Short:     "workspace maintenance",
15	Long: `Work provides access to operations on workspaces.
16
17Note that support for workspaces is built into many other commands, not
18just 'go work'.
19
20See 'go help modules' for information about Go's module system of which
21workspaces are a part.
22
23See https://go.dev/ref/mod#workspaces for an in-depth reference on
24workspaces.
25
26See https://go.dev/doc/tutorial/workspaces for an introductory
27tutorial on workspaces.
28
29A workspace is specified by a go.work file that specifies a set of
30module directories with the "use" directive. These modules are used as
31root modules by the go command for builds and related operations.  A
32workspace that does not specify modules to be used cannot be used to do
33builds from local modules.
34
35go.work files are line-oriented. Each line holds a single directive,
36made up of a keyword followed by arguments. For example:
37
38	go 1.18
39
40	use ../foo/bar
41	use ./baz
42
43	replace example.com/foo v1.2.3 => example.com/bar v1.4.5
44
45The leading keyword can be factored out of adjacent lines to create a block,
46like in Go imports.
47
48	use (
49	  ../foo/bar
50	  ./baz
51	)
52
53The use directive specifies a module to be included in the workspace's
54set of main modules. The argument to the use directive is the directory
55containing the module's go.mod file.
56
57The go directive specifies the version of Go the file was written at. It
58is possible there may be future changes in the semantics of workspaces
59that could be controlled by this version, but for now the version
60specified has no effect.
61
62The replace directive has the same syntax as the replace directive in a
63go.mod file and takes precedence over replaces in go.mod files.  It is
64primarily intended to override conflicting replaces in different workspace
65modules.
66
67To determine whether the go command is operating in workspace mode, use
68the "go env GOWORK" command. This will specify the workspace file being
69used.
70`,
71
72	Commands: []*base.Command{
73		cmdEdit,
74		cmdInit,
75		cmdSync,
76		cmdUse,
77		cmdVendor,
78	},
79}
80