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

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

Comment From: gabyhelp

Related Issues

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

Comment From: 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.

Comment From: 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.

Comment From: 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."

Comment From: 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!

Comment From: gopherbot

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