design: update workspace proposal for use directive and sync
Change-Id: I4ee372e5c738c2b4ad9aa1f2b2e4c0ca7c157bec
Reviewed-on: https://go-review.googlesource.com/c/proposal/+/372454
Trust: Michael Matloob <matloob@golang.org>
Run-TryBot: Michael Matloob <matloob@golang.org>
Reviewed-by: Bryan Mills <bcmills@google.com>
diff --git a/design/45713-workspace.md b/design/45713-workspace.md
index 397ef2f..ca2124a 100644
--- a/design/45713-workspace.md
+++ b/design/45713-workspace.md
@@ -163,7 +163,7 @@
```
go 1.17
-directory (
+use (
./baz // foo.org/bar/baz
./tools // golang.org/x/tools
)
@@ -175,7 +175,7 @@
in [`go.mod` lexical elements](https://golang.org/ref/mod#go-mod-file-lexical)
still apply to the `go.work` file
-The `go.work` file has three directives: the `go` directive, the `directory`
+The `go.work` file has three directives: the `go` directive, the `use`
directive, and the `replace` directive.
#### The `go` Directive
@@ -191,24 +191,24 @@
go 1.17
```
-#### The `directory` directive
+#### The `use` directive
-The `directory` directive takes an absolute or relative path to a directory
+The `use` directive takes an absolute or relative path to a use
containing a `go.mod` file as an argument. The syntax of the path is the same as
directory replacements in `replace` directives. The path must be to a module
directory containing a `go.mod` file. The `go.work` file must contain at least
-one `directory` directive. The `go` command may optionally edit the comments on
-the `directory` directive when doing any operation in workspace mode to add the
+one `use` directive. The `go` command may optionally edit the comments on
+the `use` directive when doing any operation in workspace mode to add the
module path from the directory's `go.mod` file.
-Note that the `directory` directive has no restriction on where the directory
+Note that the `use` directive has no restriction on where the directory
is located: module directories listed in `go.work` file can be located outside
the directory the `go.work` file itself is in.
Example:
```
-directory (
+use (
./tools // golang.org/x/tools
./mod // golang.org/x/mod
)
@@ -219,7 +219,7 @@
not refer to any other modules specified by `go.mod` files in subdirectories of
that directory.
-The modules specified by `directory` directives in the `go.work` file are the
+The modules specified by `use` directives in the `go.work` file are the
_workspace modules_. The workspace modules will collectively be the main modules
when doing a build in workspace mode. These modules are always selected by MVS
with the version `""`, and their `replace` and `exclude` directives are applied.
@@ -259,7 +259,7 @@
When doing a build operation under workspace mode the `go` command will try to
find a `go.mod` file. If a `go.mod` file is found, its containing directory must
-be declared with a `directory` directive in the `go.work` file. Because the
+be declared with a `use` directive in the `go.work` file. Because the
build list is determined by the workspace rather than a `go.mod` file, outside
of a module, the `go` command will proceed as normal to build any non-relative
package paths or patterns. Outside of a module, a package composed of `.go`
@@ -283,27 +283,42 @@
Module vendor directories are ignored in workspace mode because of the
requirement of `-mod=readonly`.
-### Creating and editing go.work files
+### Creating and editing `go.work` files
-Two new subcommands will be added to go mod: `go mod initwork` and `go mod
-editwork`.
+A new `go work` command will be added with the following subcommands
+`go work init`, `go work use`, and `go work edit`.
-`go mod initwork` will take as arguments a (potentially empty) list of
+`go work init` will take as arguments a (potentially empty) list of
directories it will use to write out a `go.work` file in the working directory
-with a `go` statement and a `directory` statement listing each of the
-directories. `go mod initwork` will take an optional `-o` flag to specify a
+with a `go` statement and a `use` directive listing each of the
+directories. `go work init` will take an optional `-o` flag to specify a
different output file path, which can be used to create workspace files for
other configurations.
-`go mod editwork` will work similarly to `go mod edit` and take the following
+`go work use` will take as arguments a set of arguments to use in the go.work
+file. If the `-r` flag is added, recursive subdirectories of the listed directories
+will be also listed in use directives. Use directives with directories that don't
+exist, but that match the arguments to `go work use` will be removed from
+the `go.work` file.
+
+`go work edit` will work similarly to `go mod edit` and take the following
flags:
* `-fmt` will reformat the `go.work` file
* `-go=version` will set the file's `go` directive to `version`
-* `-directory=path` and `-dropdirectory=path` will add and drop a directory
+* `-use=path` and `-dropuse=path` will add and drop a use
directive for the given path
* `-replace` and `-dropreplace` will work exactly as they do for `go mod edit`
+### Syncing the workspace's buildlist back ot workspace modules
+
+`go work sync` pushes the module versions of dependency
+modules back into the go.mod files of the dependency modules. It does this
+by calculating the build list in the workspace, and then upgrading the dependencies
+of the workspace's modules to the versions in the workspace buildlist. Because
+of MVS the versions in the workspace must be at least the same as the versions
+in each component module.
+
## Rationale
This proposal addresses these workflows among others:
@@ -349,7 +364,7 @@
```
go 1.17
-directory (
+use (
./mod // golang.org/x/mod
./tools // golang.org/x/tools
)
@@ -420,7 +435,7 @@
// golang.org/x/tools/go.work
go 1.17
-directory (
+use (
./tools
./tools/gopls
)
@@ -443,7 +458,7 @@
between the three configurations.
Users who want to test using a subset of the workspace modules can also easily
-comment out some of the directory directives in their workspace file instead of
+comment out some of the use directives in their workspace file instead of
making separate workspace files with the appropriate subset of workspace
modules, if that works better for their workflows.
@@ -531,7 +546,7 @@
all modules under a directory because those entries would require slow directory
walks each time the `go` command would need to load a workspace. Because
a module's path is not always clear from its directory name, we will allow the
-go command add comments on the `directory` directive with the module path.
+go command add comments on the `use` directive with the module path.
Requiring the directories listed in the `go.work` file to have `go.mod` files
means that projects without `go.mod` files can't be added to a workspace even
@@ -541,12 +556,13 @@
rare and the missing `go.mod` can be worked around by adding a temporary
`go.mod` file to the project's directory.
-The naming of the `go` and `replace` directives is straightforward: they are the
-same as in `go.mod`. The `directory` directive is called `directory` because
-that is its argument. Using `module` to list the module directories could be
-confusing because there is already a module directive in `go.mod` that has a
-different meaning. On the other hand, names like `modvers` and `moddir` are
-awkward.
+The naming of the `go` and `replace` directives is straightforward:
+they are the same as in `go.mod`. The `use` directive is called `use`
+because it causes the go.work file to use a directory as a main
+module. Using `module` to list the module directories could be
+confusing because there is already a module directive in `go.mod` that
+has a different meaning. On the other hand, names like `modvers` and
+`moddir` are awkward.
`go.work` files should not be checked into version control repos containing
modules so that the `go.work` file in a module does not end up overriding
@@ -619,12 +635,18 @@
### Creating and editing `go.work` files
-The `go mod initwork` and `go mod editwork` subcommands are being added for the
+The `go work init` and `go work edit` subcommands are being added for the
same reasons that the go `go mod init` and `go mod edit` commands exist: they
make it more convenient to create and edit `go.work` files. The names are
awkward, but it's not clear that it would be worth making the commands named `go
work init` and `go work edit` if `go work` would only have two subcommands.
+### Syncing requirements in workspace back to `go.mod` files
+
+`go work sync` allows users to eliminate divergence between the build list used
+when developing and the build lists users will see when working within
+the individual modules separately.
+
## Compatibility
Tools based on the go command, either directly through `go list` or via
@@ -715,12 +737,6 @@
## Open issues
-### The name of the `directory` directive
-
-The name `directory` could lead people to believe that all modules under the
-directory are included rather than just one. It might be better to use another
-name. One alternative that has been suggested is `include`.
-
### Clearing `replace`s
We might want to add a mechanism to ignore all replaces of a module or module
@@ -772,16 +788,6 @@
use the current workspace as well as the set of dependencies in the module graph
to automate this work.
-### Pushing down dependencies from the build list back to the workspace modules
-
-Even though it's out of scope to update the dependencies between workspace
-modules because that requires a release, it might be useful to make dependency
-versions consistent. One idea could be to push the module versions of dependency
-modules back into the go.mod files of the dependency modules. But this could
-lead to confusion because while the dependency versions will be consistent, the
-dependencies between the workspace modules will still need to be updated
-separately.
-
### Listing the module versions in the workspace
While modules have a single file listing all their root dependencies, the set of
