Go Reference ยท The go Command and Tools
The go work command
Reference for the go work command and go.work files: work on several modules at once, init, use, edit, sync and vendor, the GOWORK variable and common mistakes.
A workspace lets the go command treat several modules on your disk as one build. Normally each module is built on its own and its dependencies come from the versions in its go.mod. When you are changing a library and an application that uses it at the same time, a workspace makes the application see your local copy of the library without editing any go.mod. Workspaces were added in Go 1.18.
A workspace is described by a go.work file. The go work command creates and edits that file. Once the file exists, ordinary commands such as go build, go test and go run pick it up automatically, searching the current directory and its parents the same way they look for go.mod.
go work init ./api ./shared # create go.work listing two modules go work use ./tools/cli # add another module directory go work sync # push the workspace's versions back into each go.mod
Try it
A workspace cannot be created inside the site's single-file sandbox, so these two programs are small stand-ins written with the standard library. They parse the same kind of text a go.work file contains and apply two of the real rules.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
go work init [moddirs] go work use [-r] [moddirs] go work edit [editing flags] [go.work] go work sync go work vendor [-e] [-v] [-o outdir]
| Subcommand | Description |
|---|---|
init [moddirs] |
Creates go.work in the current directory with a use line for each directory given. With no arguments the file starts empty. |
use [-r] [moddirs] |
Adds directories to the use list. A directory that no longer exists is removed from the list. With -r each argument is searched recursively for modules. |
edit |
Changes the file from scripts: -use=dir, -dropuse=dir, -replace=old[@v]=new[@v], -dropreplace, -go=version, -toolchain=name, -godebug, -fmt, -print and -json. |
sync |
Computes the workspace's build list and writes the chosen dependency versions back to each workspace module's go.mod. |
vendor |
Copies all dependencies of the workspace's modules into a vendor directory at the workspace root (Go 1.22). |
The go.work file has these directives: go (language version, at least as high as every module's), toolchain, godebug, use (a module directory, relative to the file), and replace (same syntax as in go.mod; applies to the whole workspace and takes priority over a replace inside a module).
Environment and flags: GOWORK names the file to use. GOWORK=off (or the build flag -workfile=off) turns workspace mode off. go env GOWORK shows which file is active, and is empty when there is none.
Errors and edge cases:
- Two workspace modules with the same module path are an error.
- If the
goline ingo.workis lower than a module's, the go command asks you to raise it. - A
usedirectory without ago.modfile is an error.
Usage notes
- Version selection is merged. All workspace modules are treated as main modules, and each dependency gets the highest version required by any of them (minimal version selection over the union).
- Do not commit
go.workfor a published library. It describes your machine's layout. Teams that share a monorepo often commit it on purpose, so the rule is: commit it only when everyone should build the same set of modules. go.work.sumholds checksums that are not recorded in any module'sgo.sum. It sits next togo.work.- Module commands ignore the workspace.
go mod tidyandgo mod verifywork on one module and do not readgo.work; usego work syncfor the workspace. - Packages from outside modules fail. Imports resolve only through workspace modules or the dependencies they require.
- Debugging "why this version?"
go list -m allinside a workspace lists the merged build list. Run withGOWORK=offto see what CI, which has nogo.work, will build. - Vendoring (
go work vendor) makes-mod=vendorthe default whenvendor/modules.txtexists and thegoline is 1.22 or higher.
Related
- go mod, go get, go list, go env
- Lessons: Modules, Dependencies, Project Layout