Workspaces

Workspaces

The Workspace File (go.work)

Concept: A configuration file that allows the Go toolchain to recognize multiple local modules as part of a single shared environment. It sits at the root of a folder containing several independent projects.

• Setup:

my-workspace/
├── go.work          # The "Glue" file
├── app-service/     # Module A
│   ├── go.mod
│   └── main.go
└── shared-utils/    # Module B
    ├── go.mod
    └── logger.go

• Behavior: When you run go run or go build inside a workspace, Go treats all modules listed in go.work as if they are part of the same project. You no longer need to push code to GitHub just to test a change in a dependency.
• Why: Before Workspaces, if app-service depended on shared-utils, you had to use the replace directive in go.mod to point to a local path. This was messy because you often accidentally committed those local paths to Git, breaking the build for everyone else.

The use Directive

Concept: The command within the go.work file that tells Go which local directories contain the modules you are working on.

• Behavior:

go 1.23.0

use (
    ./app-service
    ./shared-utils
)

• Why: It provides a clean "opt-in" mechanism. You can have 10 modules in a folder but only "use" 2 of them in your current workspace to keep your environment focused and fast.

Automatic Dependency Resolution

Concept: The workspace overrides remote versions with local code automatically.

• Behavior: If app-service requires github.com/username/shared-utils v1.0.0, but that module is present in your workspace via the use directive, Go will ignore the version on GitHub and use your unsaved, local code instead.
• Why: It allows for seamless Cross-Module Refactoring. You can change a function signature in your library (shared-utils) and immediately see the compiler errors in your main application (app-service) without doing any go get or tagging new versions.

The replace Override

Concept: Just like in go.mod, you can use replace in a go.work file, but it applies to all modules in the workspace.

• Behavior:

replace golang.org/x/net => ../local-net-fork

• Why: This is the "Nuclear Option" for debugging. It forces every module in your workspace to use a specific fork of a third-party dependency, making it easy to test bug fixes in external libraries across your entire ecosystem.

Reference Guides

Crucial Commands

Summary Table