x/website/_content/ref: clarify documentation of go work use -r

[eliben]

Go version

any

Output of go env in your module/workspace:

n/a

What did you do?

The documentation at https://go.dev/ref/mod#go-work-use currently says:

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.

Which can be taken as "the command will remove directories from the go.work file that weren't found in the recursive tree under the arguments passed to -r"

What did you see happen?

n/a

What did you expect to see?

n/a

[gabyhelp]

Related Issues

• Go Modules Reference > Module-aware commands > go work use
• Command go > Add modules to workspace file
• Command go > Add modules to workspace file
• cmd/go: 'go work use -r' fails to remove entries for deleted subdirectories #50959 (closed)
• cmd/go: work use . does nothing in non module root #53090
• Tutorial: Getting started with multi-module workspaces > Learn more about workspaces

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[matloob]

Okay, so reading "use directives will be added for directories that exist, and removed for directories that do not exist", the subject for both "added" and "removed" seems to me to clearly be "use directives" rather than "directories".

Would "use directives will be added for directories that exist, and they will be removed for directories that do not exist" be more clear?

Or maybe "use directives will be added for directories that exist, and use directives will be removed for directories that do not exist"? It's clunky but it's harder to misinterpret.

[eliben]

I think the mix-up may be on my end; I did not interpret it as "the go tool will remove the actual directories". I was thinking of this scenario:

Suppose I already have a go.work file with a bunch of existing directories in it. Now I want to add some new directories - not related to the existing ones - so I call go work use -r <some-tree>. IIUC, this means that for any directory not in <some-tree>, go work will remove its mention from the go.work file; this is the documented behavior. If the documentation is accurate here, perhaps one just has to be more careful with using the -r mode.

[matloob]

Oh I see. The behavior is that only directories that would be under the tree specified with -r and which do not exist would be removed.

I'm not sure how to rephrase it without making it more awkward. Maybe we can remove the last part of the sentence entirely? "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."

Or maybe "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 paths that are under the argument directories but do not exist."

[eliben]

The shorter "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" seems better to me - thanks!

[gopherbot]

Change https://go.dev/cl/595536 mentions this issue: cmd/go/internal/workcmd: remove a potentially confusing statement

[gopherbot]

Change https://go.dev/cl/595997 mentions this issue: _content/ref: remove potentially confusing statement in go work use doc