Using Go 1.18 Multi‑Module Workspaces: Tutorial and Practical Examples

Go 1.18, released on March 15, 2022, not only brings performance improvements and the long‑awaited generics feature, but also introduces multi‑module workspaces (Workspaces). Workspaces make it easier to develop and debug several Go modules simultaneously.

This article provides a step‑by‑step guide on how to use Go workspaces, including prerequisites, essential commands, and a complete example that demonstrates creating a simple "hello" module, adding a shared "example" library, and extending the functionality while keeping both modules under active development.

Prerequisites

Go 1.18 or later installed ( go version should show go1.18 or newer).

Set up the GOWORK environment variable if you want to place the go.work file in a custom location (e.g., export GOWORK="~/go/src/test/go.18/workspace/go.work" ).

Key Workspace Commands

go work init [module1] [module2] ... – Initialize a go.work file and list the modules that belong to the workspace.

go work use [module] – Add a new module to the workspace (can be a single path or a list inside parentheses).

go work edit – Manually edit the go.work file; you can also use sub‑commands such as go work edit -replace , -use , -dropuse , etc.

go work sync – Synchronize the workspace’s build list with the modules.

go env GOWORK – Show the current workspace file path.

Example: Building a Multi‑Module Project

1. Create the hello module and add a dependency on the shared example library.

# Create hello module
mkdir hello
cd hello
# Initialize go.mod
go mod init github.com/link1st/link1st/workspaces/hello
# Add example library
go get github.com/link1st/example
# Create main.go (see code block below)
vim main.go

2. main.go source (the core of the tutorial):

// Package main demonstrates a Go multi‑module workspace example.
package main

import (
    "flag"
    "fmt"
    "github.com/link1st/example/stringutil"
)

var str string

func init() {
    flag.StringVar(&str, "str", str, "input string")
    flag.Parse()
}

func main() {
    if str == "" {
        fmt.Println("Example: go run main.go -str hello")
        fmt.Println("str parameter is required")
        flag.Usage()
        return
    }
    // Reverse the string using the shared library.
    str = stringutil.Reversal(str)
    // Output the result.
    fmt.Println(str)
}

Running the program:

go run main.go -str "hello world"
# Output: dlrow olleh

3. Extend the shared library with a new ToUpper function (still local, not yet committed).

// Package stringutil provides string utilities.
package stringutil

import "unicode"

// ToUpper converts a string to uppercase.
func ToUpper(s string) string {
    r := []rune(s)
    for i := range r {
        r[i] = unicode.ToUpper(r[i])
    }
    return string(r)
}

4. Add the new function to main.go :

// After reversal, also convert to uppercase.
    str = stringutil.ToUpper(str)
    fmt.Println(str)

5. Initialize the workspace to include both hello and example modules:

# From the workspace root
go work init ./hello ./example
cat go.work
# Expected content (simplified):
go 1.18
use (
    ./example
    ./hello
)

6. Build and run the updated program:

go run main.go -str "hello world"
# Output: DLROW OLLEH

This demonstrates that the workspace allows simultaneous development of both modules without committing changes to the remote repository. The go.work file takes precedence over go.mod replace directives, making local testing straightforward.

Summary

Using Go 1.18 multi‑module workspaces simplifies development across multiple repositories, improves debugging of inter‑module dependencies, and fits well with modern micro‑service architectures.