cmd/go: 'go work use' documentation is stale and contains typo #81807

Go version

go version go1.28-devel_2ff5743d9f Sat Sep 26 15:27:19 2026 -0700 windows/amd64 (and all supported releases since Go 1.18.1)

Output of go env in your module/workspace:

set AR=ar
set CC=gcc
set CGO_CFLAGS=-O2 -g
set CGO_CPPFLAGS=
set CGO_CXXFLAGS=-O2 -g
set CGO_ENABLED=1
set CGO_FFLAGS=-O2 -g
set CGO_LDFLAGS=-O2 -g
set CXX=g++
set GCCGO=gccgo
set GO111MODULE=
set GOAMD64=v1
set GOARCH=amd64
set GOAUTH=netrc
set GOBIN=C:\Users\aman\go\bin
set GOCACHE=C:\Users\aman\AppData\Local\go-build
set GOCACHEPROG=
set GODEBUG=
set GOENV=C:\Users\aman\AppData\Roaming\go\env
set GOEXE=.exe
set GOEXPERIMENT=
set GOFIPS140=off
set GOFLAGS=
set GOGCCFLAGS=-m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=C:\Users\aman\AppData\Local\Temp\go-build3356099773=/tmp/go-build -gno-record-gcc-switches
set GOHOSTARCH=amd64
set GOHOSTOS=windows
set GOINSECURE=
set GOMOD=NUL
set GOMODCACHE=C:\Users\aman\go\pkg\mod
set GONOPROXY=
set GONOSUMDB=
set GOOS=windows
set GOPACKAGESDRIVER=
set GOPATH=C:\Users\aman\go
set GOPRIVATE=
set GOPROXY=https://proxy.golang.org,direct
set GOROOT=U:\GoogleSource\go
set GOSUMDB=sum.golang.org
set GOTELEMETRY=local
set GOTELEMETRYDIR=C:\Users\aman\AppData\Roaming\go\telemetry
set GOTMPDIR=
set GOTOOLCHAIN=auto
set GOTOOLDIR=U:\GoogleSource\go\pkg\tool\windows_amd64
set GOVCS=
set GOVERSION=go1.28-devel_2ff5743d9f Sat Sep 26 15:27:19 2026 -0700
set GOWORK=
set PKG_CONFIG=pkg-config

What did you do?

• Check the Add modules to workspace file section in the Go command documentation page (generated from src/cmd/go/internal/workcmd/use.go):

  The documentation currently states:

  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,
  or removed from the go.work file if it does not exist.

• Verify the documented behavior with a sample workspace:

  # create workspace with three modules
  mkdir workspace && cd workspace
  mkdir a && cd a && go mod init a && cd ..
  mkdir b && cd b && go mod init b && cd ..
  mkdir c && cd c && go mod init c && cd ..
  go work init a b c
  
  # Case A: Argument directory exists and contains go.mod
  go work use a
  
  # Case B: Argument directory exists but does not contain go.mod
  rm b/go.mod
  go work use b
  
  # Case C: Argument directory does not exist on disk
  rm -r c   # in powershell: rm -Recurse c
  go work use c

What did you see happen?

Case A (go work use a)

The use a directive is retained in go.work (exit code 0).

Case B (go work use b)

Even though the directory exists, the use b directive is removed from go.work (exit code 0) because removal is governed by the absence of go.mod, which is not mentioned in the documentation.

Case C (go work use c)

The documentation states that the directive will be removed from go.work if the argument directory does not exist. But the command fails with an error:

$ go work use c
go: directory c does not exist
go: open U:\workspace\c\go.mod: The system cannot find the path specified.

The command exits with exit code 1 without modifying go.work. The use c directive is not removed:

go 1.22
use (
    a
    c
)

Summary

• Documented behavior: A use directive is added if the argument directory exists and removed if it does not exist.
• Actual behavior: A use directive is only removed when the argument directory exists on disk but does not contain a go.mod file (Case B). When an argument directory does not exist on disk (Case C), the command errors out and leaves go.work completely unmodified.
• Typo: "directory listed on the command line go.work file, if it exists" has an extra "go.work file" after "command line".

What did you expect to see?

Expected either the documentation to accurately reflect the actual implementation (along with fixing the typo), or the implementation to match the documented behavior:

Proposed Solution

1. Fix the typo in src/cmd/go/internal/workcmd/use.go by removing the extra "go.work file" after "command line".

2. For the behavior discrepancy, either:

   • Option A (Update documentation to match implementation):
     Clarify that directives are added if the argument directory contains a go.mod file, or removed if it does not:

       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,
     - or removed from the go.work file if it does not exist.
     + directory listed on the command line, if it contains a go.mod file,
     + or removed from the go.work file if it does not.

     Regenerate alldocs.go via go generate cmd/go.

   • Option B (Update implementation to match documentation):
     Change go work use to drop the directive from go.work when the argument directory does not exist, rather than failing with directory ... does not exist.

     (Note: go work edit -dropuse=<dir> is already available for removing directives without requiring the directory to exist on disk).

3. The following related documentation pages in golang/website will also need to be updated with the revised description:

   • Go Modules Reference: go work use (source: _content/ref/mod.md#L2846-L2848)
   • Workspaces Tutorial: Learn more about workspaces (source: _content/doc/tutorial/workspaces.md#L272-L274, related issue: #81779)

Analysis

Inspecting src/cmd/go/internal/workcmd/use.go (function workUse) and verifying with runtime tests shows how each case is handled:

History