SyntaxPilot
Courses/Go Programming/Lesson 28
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 28 of 89

Modules and dependency management

go.mod directives (module, go, toolchain, require, replace, exclude, retract)go.sumsemantic versioningpseudo-versionsmajor version suffixes (/v2)go getgo mod tidygo list -mminimal version selection (MVS)vendoringGOPROXYGOSUMDB checksum databaseGOPRIVATEworkspaces (go.work)

These are the notes for Go episode 28. In episode 27 you split your own code into packages. But most of the code in a real program is written by other people. In this episode Raju's chai shop needs unique order IDs, a home-made solution fails, and you invent the way Go brings in other people's code safely, at the right version, every single time: modules. You will learn what a module and a dependency are, read every line of a go.mod file (the directives module, go, toolchain, require, replace, exclude, retract and tool), see how go.sum keeps a checksum of every download, and use go get, go mod tidy, go list -m and go mod graph. You will learn semantic versioning, pseudo-versions for untagged commits, major version suffixes like /v5, and how minimal version selection picks one version when two libraries disagree. Then you will fix a bad release three ways, find out where downloads come from (GOPROXY, GOSUMDB, GOPRIVATE), keep dependencies in your own repository with vendoring, edit two modules at once with a workspace (go.work), and pin developer programs with the tool directive (new in Go 1.24). Every command below was run for real in a module on a computer, and all outputs and errors are from real runs (Go 1.24, linux/amd64). These examples don't run in the SyntaxPilot compiler: they need a folder, a go.mod file and downloads.

About the demo modules. github.com/google/uuid is the real public library, downloaded from GitHub. The modules example.com/gst, example.com/billing, example.com/delivery and example.com/chaitool are small demo modules (a few lines each) served from a local module proxy, so you can rebuild every example yourself. go help goproxy says: "A Go module proxy is any web server that can respond to GET requests for URLs of a specified form. The requests have no query parameters, so even a site serving from a fixed file system (including a file:/// URL) can be a module proxy." So the demo used a folder as the proxy:

export GOPROXY=file:///tmp/e28/proxy,direct

Inside that folder each version is just three files plus a list (real listing):

$ ls /tmp/e28/proxy/example.com/gst/@v list v1.0.0.info v1.0.0.mod v1.0.0.zip v1.1.0.info v1.1.0.mod v1.1.0.zip v1.2.0.info v1.2.0.mod v1.2.0.zip v1.2.1.info v1.2.1.mod v1.2.1.zip

list holds the version names, .info the version and its time, .mod its go.mod, and .zip its files. ,direct means: anything not in the folder (like github.com/google/uuid) is fetched straight from its source. The sandbox couldn't reach the public checksum database either, so the demo also set GONOSUMDB=example.com,github.com (explained below); go.sum checks still ran, as the SECURITY ERROR section shows. The go command's messages are the same with the real public proxy.

The problem: order IDs

Raju's chai shop now takes online orders, and every order needs a unique ID: a label that no other order has, so the kitchen can tell orders apart. The obvious way: make one yourself from the clock (the hour, minute and second). Three orders arrive:

package main

import (
    "fmt"
    "time"
)

// home-made order ID: the time, to the second
func newID() string {
    return time.Now().Format("150405")
}

func main() {
    for i := 1; i <= 3; i++ {
        fmt.Println("order", newID(), "chai x2")
    }
}
order 234441 chai x2
order 234441 chai x2
order 234441 chai x2
  • time.Now().Format("150405") writes the current time as hour (15), minute (04) and second (05): 234441 is 23:44:41.
  • Three orders, one ID. All three arrived in the same second, so they got the same label. This is called a collision: two things that should be different get the same value.
  • A counter (1, 2, 3...) doesn't help either: it starts again at 1 every time the program restarts. Unique IDs are a hard problem: they need randomness and care.

Someone has already solved it. Think of masala:

In the kitchen In code
Grind your own masala: slow, easy to get wrong write your own ID generator
Copy a friend's recipe onto paper copy-paste someone's code into your project
Your friend fixes the recipe later; your paper never hears about it the original code gets a bug fix; your copy goes stale
Buy a sealed packet from a trusted brand, with a name and a pack version a dependency
  • A dependency is code written by someone else that your program needs, fetched by name and version. When its author fixes a bug, you get the fix by asking for the newer version.
  • For IDs there is a popular one: the package github.com/google/uuid. A UUID (universally unique identifier) is a long random ID, so random that two of them practically never match.

Just import it?

The import path (episode 27) is the address where the code lives: github.com/google/uuid. uuid.New() makes a new ID, and we print its first 8 characters:

package main

import (
    "fmt"

    "github.com/google/uuid"
)

func main() {
    id := uuid.New()
    fmt.Println("order", id.String()[:8], "chai x2")
}

In a folder with only this main.go:

$ go run main.go
main.go:6:5: no required module provides package github.com/google/uuid: go.mod file not found in current directory or any parent directory; see 'go help modules'
  • Go won't download code just because you named it. It needs a written list of what this project depends on, and at which version. That list is a module's go.mod file, and this folder has none.

Modules and go.mod

Think of the shop's shopping list:

At the shop In Go What it is
The shop, with everything it sells module packages released together, with one name and one version
The shopping list: brand + pack size go.mod the module path and the minimum version of every requirement
The seal numbers on the packets: spot tampering go.sum a checksum of each download
  • A module is "a collection of packages that are released, versioned, and distributed together" (go help modules). Raju's shop is a module. The uuid library is another module. Every package you import lives in some module (standard library packages like fmt come with Go itself).
  • Every module has a go.mod file at its root (its top folder). It says the module's own name, the module path, and every other module it needs, with the lowest version it accepts.
  • The module path is the module's name, usually the address where its code will live online (github.com/google/uuid), so it is unique worldwide. It is also the start of the import path of every package inside it (episode 27).
  • The main module is the module whose folder you run the go command in. Here that is the shop. Some rules (you'll meet them with replace and exclude) only read the main module's go.mod.
  • go help modules begins: "Modules are how Go manages dependencies."

go mod init and go get

Make the module (you did this in episode 2), and run:

$ go mod init example.com/shop
go: creating new go.mod: module example.com/shop
go: to add module requirements and sums:
    go mod tidy
$ go run .
main.go:6:5: no required module provides package github.com/google/uuid; to add it:
    go get github.com/google/uuid
  • go mod init creates go.mod. Because main.go already imports something, it also suggests go mod tidy (coming up).
  • Now the error even tells us the fix. go get adds a dependency, or changes its version:
$ go get github.com/google/uuid
go: downloading github.com/google/uuid v1.6.0
go: added github.com/google/uuid v1.6.0
$ go run .
order 56ecd5e8 chai x2
$ go run .
order 896377e2 chai x2
  • go get found the newest version, v1.6.0, downloaded it, and wrote it into go.mod. Two runs, two different IDs: real randomness, in one line of our code.
  • go help get says it "resolves its command-line arguments to packages at specific module versions, updates go.mod to require those versions, and downloads source code into the module cache". The module cache is the folder on your computer where downloaded modules are kept (by default GOPATH/pkg/mod; go help gopath: GOPATH "is still used to store downloaded source code (in GOPATH/pkg/mod)"), so each version is downloaded only once.

What go get wrote: go.mod and go.sum

go.mod:

module example.com/shop

go 1.24.7

require github.com/google/uuid v1.6.0 // indirect

go.sum:

github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
  • The module line names our module. The go line is the minimum Go version this module needs. The require line says: we need github.com/google/uuid, at least version v1.6.0. Notice the comment // indirect; we fix it in the next section.
  • A directive is one kind of line in go.mod: module, go and require are directives. You'll meet all eight below.
  • go.sum has two lines per module version: one for the module's code, one for just its go.mod.
  • The h1:... text is a checksum, also called a hash: a short fingerprint computed from every byte of the files. Change one byte, and the fingerprint changes completely. h1: names the hashing method; the rest is the fingerprint written in base64 (episode 27). go help module-auth: "When the go command downloads a module zip file or go.mod file into the module cache, it computes a cryptographic hash and compares it with a known value to verify the file hasn't changed since it was first downloaded. Known hashes are stored in a file in the module root directory named go.sum."
  • Commit both files to Git. (Git is the version control program most projects use to save the history of their code; a commit is one saved change in Git, with an ID like 2d3c2a9.)

go mod tidy: direct and indirect dependencies

$ go mod tidy && cat go.mod
module example.com/shop

go 1.24.7

require github.com/google/uuid v1.6.0
  • // indirect means: no package in this module imports it directly. go get wrote it because it added the module before checking our imports.
  • A direct dependency is a module whose packages your code imports. An indirect dependency is one your build needs only because another dependency uses it (you'll see example.com/gst marked this way later).
  • go mod tidy fixes the list. go help mod tidy: "Tidy makes sure go.mod matches the source code in the module. It adds any missing modules necessary to build the current module's packages and dependencies, and it removes unused modules that don't provide any relevant packages. It also adds any missing entries to go.sum and removes any unnecessary ones." Now uuid is a direct dependency and the comment is gone.

Watch the other half. Add a web router library, chi, but never import it:

$ go get github.com/go-chi/chi/v5@v5.0.0
go: downloading github.com/go-chi/chi/v5 v5.0.0
go: added github.com/go-chi/chi/v5 v5.0.0
$ cat go.mod
module example.com/shop

go 1.24.7

require github.com/google/uuid v1.6.0

require github.com/go-chi/chi/v5 v5.0.0 // indirect
$ go mod tidy && go list -m all
example.com/shop
github.com/google/uuid v1.6.0
  • go list -m all lists every module in the build: the main module first (with no version, because it's the one you're editing), then each dependency with the version the build uses. -m means "list modules, not packages".
  • chi is gone. Tidy removed it, because no code uses it. Run go mod tidy before every commit, and your list is always exact.

Semantic versions

Go versions follow semantic versioning, semver for short: v, then three numbers, MAJOR.MINOR.PATCH. Think of a recipe book:

Recipe book Semver Means
New edition, recipes changed: the old way no longer works MAJOR: v1 → v2 a breaking change: code that used the old version may stop compiling
New recipes added, old ones the same MINOR: v1.5 → v1.6 new features, nothing breaks
Typos fixed, nothing new PATCH: v1.6.0 → v1.6.1 bug fixes only
  • v0 (like v0.3.0) means: still experimental, anything may change, even between minor versions.
  • A version is just a Git tag on the library's code: a name like v1.6.0 attached to one commit, so everyone can find exactly that code.
$ go list -m -versions github.com/google/uuid
github.com/google/uuid v1.0.0 v1.1.0 v1.1.1 v1.1.2 v1.1.3 v1.1.4 v1.1.5 v1.2.0 v1.3.0 v1.3.1 v1.4.0 v1.5.0 v1.6.0
  • go list -m -versions shows every released version of a module.
  • go get module@version asks for one: @v1.5.0, @latest (the newest release), or a commit. go help get: "To upgrade or downgrade a package to a specific version: go get example.com/pkg@v1.2.3".

Pseudo-versions: a commit with no tag

You can ask for a commit that has no tag, by its ID:

$ go get github.com/google/uuid@2d3c2a9
go: downloading github.com/google/uuid v1.6.1-0.20241114170450-2d3c2a9cc518
go: upgraded github.com/google/uuid v1.6.0 => v1.6.1-0.20241114170450-2d3c2a9cc518

Go invents a pseudo-version for it, a fake version number that still sorts in the right order:

Part Here Meaning
next patch version v1.6.1-0 built on top of the last tag, v1.6.0
date and time of the commit 20241114170450 2024-11-14, 17:04:50
commit ID (12 characters) 2d3c2a9cc518 exactly which commit
$ go get github.com/google/uuid@v1.6.0
go: downgraded github.com/google/uuid v1.6.1-0.20241114170450-2d3c2a9cc518 => v1.6.0
  • go get says added, upgraded or downgraded every time a version changes. Read those lines: they are the history of your go.mod.

Which of my dependencies are out of date? go list -m -u

-u adds the newest available version in square brackets (real run, after go get github.com/google/uuid@v1.5.0):

$ go get github.com/google/uuid@v1.5.0
go: downloading github.com/google/uuid v1.5.0
go: downgraded github.com/google/uuid v1.6.0 => v1.5.0
$ go list -m -u all
example.com/shop
github.com/google/uuid v1.5.0 [v1.6.0]
$ go get github.com/google/uuid@latest
go: upgraded github.com/google/uuid v1.5.0 => v1.6.0

Major versions: /v2 and beyond

Now try version 5 of the chi library, the obvious way:

$ go get github.com/go-chi/chi@v5.0.0
go: github.com/go-chi/chi@v5.0.0: invalid version: go.mod has post-v5 module path "github.com/go-chi/chi/v5" at revision v5.0.0
$ go get github.com/go-chi/chi/v5@v5.0.0
go: added github.com/go-chi/chi/v5 v5.0.0

and in your code:

import "github.com/go-chi/chi/v5"
  • This is Go's major version suffix rule. From v2 on, the major version is part of the module path: /v2, /v5. A breaking change makes it a different module, with a different import path.
  • So old code importing github.com/go-chi/chi keeps working, and new code imports github.com/go-chi/chi/v5. Both can even live in one program, because to Go they are two different modules.
  • v0 and v1 have no suffix. The package name stays the normal one: you still write chi.NewRouter(), not v5.NewRouter() (episode 27: the package name comes from the package clause, not the last path element).

Minimal version selection

Next problem. The shop now uses two libraries, example.com/billing and example.com/delivery. Both use a third library, example.com/gst, that adds tax. Their go.mod files (real, from the proxy) say:

module example.com/billing

go 1.21

require example.com/gst v1.0.0

and delivery requires example.com/gst v1.1.0. One program can have only one copy of gst version 1. Which one?

Two cooks, one sugar order Go
Cook A: at least 1 kg billing requires gst v1.0.0
Cook B: at least 2 kg delivery requires gst v1.1.0
Buy 2 kg, not the biggest bag in the market selected: gst v1.1.0
  • Go's rule is called minimal version selection (MVS): for each module, take the highest of the minimum versions anyone asked for. Never newer than that, even if newer exists.
  • The Go wiki's example: A needs B and C; B needs D v1.0.0; C needs D v1.1.0. The build uses D v1.1.0, even if D v1.2.0 exists.

The shop's main.go:

package main

import (
    "fmt"

    "example.com/billing"
    "example.com/delivery"
    "github.com/google/uuid"
)

func main() {
    id := uuid.New().String()[:8]
    fmt.Println("order", id, "bill", billing.Total(100))
    fmt.Println("delivery", delivery.Total(40))
}

After go mod tidy, its go.mod:

module example.com/shop

go 1.24.7

require (
    example.com/billing v1.0.0
    example.com/delivery v1.0.0
    github.com/google/uuid v1.6.0
)

require example.com/gst v1.1.0 // indirect
$ go run .
go: downloading example.com/delivery v1.0.0
go: downloading example.com/billing v1.0.0
go: downloading example.com/gst v1.1.0
order 3e5c1d60 bill 105
delivery 42

gst v1.1.0 adds 5 percent: 100 → 105, 40 → 42. Now look at the requirements. go mod graph prints every requirement as an arrow, "who needs what", one per line:

$ go mod graph
example.com/shop example.com/billing@v1.0.0
example.com/shop example.com/delivery@v1.0.0
example.com/shop example.com/gst@v1.1.0
example.com/shop github.com/google/uuid@v1.6.0
example.com/shop go@1.24.7
example.com/billing@v1.0.0 example.com/gst@v1.0.0
example.com/billing@v1.0.0 go@1.21
example.com/delivery@v1.0.0 example.com/gst@v1.1.0
example.com/delivery@v1.0.0 go@1.21
example.com/gst@v1.1.0 go@1.21
go@1.24.7 toolchain@go1.24.7

(The video filtered it with | grep gst.) The go@... lines are each module's go line, shown as a requirement too.

$ go list -m all
example.com/shop
example.com/billing v1.0.0
example.com/delivery v1.0.0
example.com/gst v1.1.0
github.com/google/uuid v1.6.0
$ go list -m -versions example.com/gst
example.com/gst v1.0.0 v1.1.0 v1.2.1
  • The build uses gst v1.1.0, the highest minimum, even though v1.2.1 exists, because nobody asked for it.
  • This makes builds repeatable: the same go.mod files always give the same versions, today and in five years, with no surprise upgrades. You upgrade only when you run go get.
  • go mod why -m shows one chain of imports that explains why a module is needed:
$ go mod why -m example.com/gst
# example.com/gst
example.com/shop
example.com/billing
example.com/gst

A bad release: retract

Where is v1.2.0 in that list? The gst author released it with a bug: 50 percent tax instead of 5. A published version should never change, because other people already depend on it and their go.sum would catch the change. So the author published v1.2.1 (fixed) with a retract line in its go.mod (real file from the proxy):

module example.com/gst

go 1.21

retract v1.2.0 // wrong rate: 50% instead of 5%
  • retract is the module author's way of saying "don't use this version of mine". The comment after it is the reason Go shows to users. Go reads retractions from the go.mod of the module's latest version, and retracted versions stay downloadable (so builds that already use them don't break). retract was added in Go 1.16 (February 2021).

Ask for it anyway:

$ go get example.com/gst@v1.2.0
go: downloading example.com/gst v1.2.0
go: warning: example.com/gst@v1.2.0: retracted by module author: wrong rate: 50% instead of 5%
go: to switch to the latest unretracted version, run:
    go get example.com/gst@latest
go: upgraded example.com/gst v1.1.0 => v1.2.0
$ go run .
order b77a65c6 bill 150
delivery 60

The bill really is 150 for a 100 rupee order. go list -m -u all marks it too:

$ go list -m -u all
example.com/shop
example.com/billing v1.0.0
example.com/delivery v1.0.0
example.com/gst v1.2.0 (retracted) [v1.2.1]
github.com/google/uuid v1.6.0

@latest skips retracted versions:

$ go get example.com/gst@latest && go run .
go: downloading example.com/gst v1.2.1
go: upgraded example.com/gst v1.2.0 => v1.2.1
order e90ce2a8 bill 105
delivery 42

-versions hides retracted versions; add -retracted to see them:

$ go list -m -retracted -versions example.com/gst
example.com/gst v1.0.0 v1.1.0 v1.2.0 v1.2.1

replace and exclude: rules for your own module

Retract is for authors. For users, Go has two more directives.

replace. Suppose the author hasn't fixed v1.2.0 yet, and the shop is charging 50 percent tax. We fix it ourselves in a folder ../gst-local (it needs its own go.mod, module example.com/gst). The replace directive says: whenever you need this module, use that folder (or that other module) instead. Starting at gst v1.2.0 (bill 150):

$ go mod edit -replace example.com/gst=../gst-local
$ tail -3 go.mod
require example.com/gst v1.2.0 // indirect

replace example.com/gst => ../gst-local
$ go run .
order f7473210 bill 105
delivery 42
$ go list -m example.com/gst
example.com/gst v1.2.0 => ../gst-local
  • go mod edit changes go.mod from the command line (you can also edit the file by hand). The bill went from 150 back to 105, and go list shows the arrow to our copy.
  • Typical uses: a fork (your own copy of someone's repository with your fix), or testing a local change.

exclude. exclude says: never use this exact version; Go then ignores any requirement on it. Starting from the normal shop (gst v1.1.0):

$ go mod edit -exclude example.com/gst@v1.1.0
$ go mod tidy
go: dropping requirement on excluded version example.com/gst v1.1.0
go: downloading example.com/gst v1.0.0
$ go list -m all
example.com/shop
example.com/billing v1.0.0
example.com/delivery v1.0.0
example.com/gst v1.0.0
github.com/google/uuid v1.6.0
$ go run .
order 5cb7f8ea bill 118
delivery 47.199999999999996
  • It fell back to the version billing asked for, v1.0.0, whose rate is 18 percent (100 → 118). The odd 47.199999999999996 is just floating-point rounding of 40 × 1.18 (floats can't store most decimals exactly). Lesson: excluding a version can quietly give you an older one, so check go list -m all afterwards.
  • Both replace and exclude only work in the main module. If a library you depend on has replace or exclude lines, Go ignores them. Your build, your rules.

Every go.mod directive

Here is every directive a go.mod can have, together (a teaching example: a real module rarely has all of them, and retract names versions of this module):

module example.com/shop          // this module's name

go 1.24.7                         // minimum Go version
toolchain go1.24.7                // preferred Go toolchain

require (                         // what we need, at least
    example.com/billing v1.0.0
    github.com/google/uuid v1.6.0
)

replace example.com/gst => ../gst-local    // use my copy
exclude example.com/gst v1.1.0             // never this one
retract v1.0.5   // for authors: "don't use my v1.0.5"
tool example.com/chaitool                  // a dev tool
Directive Who it's for Meaning
module everyone this module's path
go everyone the minimum Go version needed to use this module
toolchain the main module the Go release this module prefers to be built with
require everyone the minimum version of each dependency
replace main module only use another folder or module instead
exclude main module only never use this version
retract the module's author "don't use these versions of mine"
tool the main module a developer program, run with go tool (Go 1.24)

The go and toolchain lines

A toolchain is a whole Go release: the compiler, the go command and the other tools. Since Go 1.21, the go line is the minimum required Go version, and the go command can manage toolchains by itself: with the default GOTOOLCHAIN=auto, if your installed Go is older than a module needs, it can download and use the newer toolchain. The demo set GOTOOLCHAIN=local ("only use the Go that is installed"), so you can see the check:

$ go mod edit -go=1.25.0
$ go run .
go: go.mod requires go >= 1.25.0 (running go 1.24.7; GOTOOLCHAIN=local)
$ go env GOTOOLCHAIN          (with no setting of your own)
auto

A toolchain line only means something when it is newer than the go line. Real runs:

$ go mod edit -go=1.24.7 -toolchain=go1.24.7
$ go run .
go: updates to go.mod needed; to update it:
    go mod tidy
$ go mod tidy && cat go.mod
module example.com/shop

go 1.24.7

require github.com/google/uuid v1.6.0
$ go mod edit -go=1.24.0 -toolchain=go1.24.7
$ go mod tidy && cat go.mod
module example.com/shop

go 1.24.0

toolchain go1.24.7

require github.com/google/uuid v1.6.0
$ go run .
order 600b81b6 chai x2

Tidy dropped toolchain go1.24.7 when it equalled the go line, and kept it when it was newer.

Where downloads come from: GOPROXY, GOSUMDB, GOPRIVATE

Think of buying stock for the shop:

Buying stock Downloading modules Default
The wholesale market keeps copies of every brand GOPROXY: a module proxy https://proxy.golang.org,direct
A public seal register: check any seal number GOSUMDB: the checksum database sum.golang.org
Your own secret supplier, not in any market GOPRIVATE: modules that skip both empty

On a fresh install (real run, no settings of my own):

$ go env GOPROXY GOSUMDB GOPRIVATE
https://proxy.golang.org,direct
sum.golang.org

(The third line is empty: GOPRIVATE is not set.)

  • An environment variable is a named setting the operating system passes to programs; go env NAME prints the go command's value of it, and go env -w NAME=value saves one.
  • A module proxy is a server that keeps copies of public modules, like a wholesale market keeping stock of every brand. go help private calls proxy.golang.org "the public Go module mirror". direct means: if the proxy doesn't have it, fetch it from the source, such as GitHub.
  • The checksum database is a public register of the fingerprint of every public module version. go help private: the go command "defaults to validating downloaded modules, regardless of source, against the public Go checksum database at sum.golang.org." The first time anyone downloads a version, Go checks it against this register, so everyone in the world gets the same bytes.
  • But company code must not go to public servers. From go help private: "The GOPRIVATE environment variable controls which modules the go command considers to be private (not available publicly) and should therefore not use the proxy or checksum database. The variable is a comma-separated list of glob patterns (in the syntax of Go's path.Match) of module path prefixes. For example, GOPRIVATE=*.corp.example.com,rsc.io/private". A glob pattern is a pattern where * means "anything here", like *.corp.example.com.
  • GONOPROXY and GONOSUMDB "accept the same kind of glob list and override GOPRIVATE for the specific decision of whether to use the proxy and checksum database, respectively." If you set only GOPRIVATE, both copy it (real run):
$ GOPRIVATE='*.corp.example.com,github.com/my-company/*' go env GOPRIVATE GONOPROXY GONOSUMDB
*.corp.example.com,github.com/my-company/*
*.corp.example.com,github.com/my-company/*
*.corp.example.com,github.com/my-company/*

(This is also why the demo's GONOSUMDB=example.com,github.com turned off only the checksum database lookup, not the proxy and not go.sum.)

The seal is broken

Let's see the seal work. One character of the gst fingerprint in go.sum was changed (h1:q... to h1:X...), the downloaded copies were deleted with go clean -modcache, and then:

$ go run .
go: downloading example.com/delivery v1.0.0
go: downloading example.com/billing v1.0.0
go: downloading github.com/google/uuid v1.6.0
go: downloading example.com/gst v1.1.0
verifying example.com/gst@v1.1.0: checksum mismatch
    downloaded: h1:qgkKftsOGNIajBxot3TdSCBy5JcgDe1NFcyK+DKyQlA=
    go.sum:     h1:XgkKftsOGNIajBxot3TdSCBy5JcgDe1NFcyK+DKyQlA=

SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.
The bits may have been replaced on the origin server, or an attacker may
have intercepted the download attempt.

For more information, see 'go help module-auth'.
  • Go refuses to build with code that changed under the same version number. go.sum plus the checksum database make downloads tamper-proof.
  • Never "fix" this by deleting go.sum lines without finding out why the bytes changed.

go mod verify checks the copies already in your module cache against go.sum:

$ go mod verify
all modules verified

Vendoring: keep a copy in the store room

Some companies build on machines with no internet. Vendoring means copying every dependency's code into a folder called vendor inside your module, like keeping stock in your own store room. go mod vendor does it, and writes vendor/modules.txt, the list of what's inside:

$ go mod vendor && cat vendor/modules.txt
# example.com/billing v1.0.0
## explicit; go 1.21
example.com/billing
# example.com/delivery v1.0.0
## explicit; go 1.21
example.com/delivery
# example.com/gst v1.1.0
## explicit; go 1.21
example.com/gst
# github.com/google/uuid v1.6.0
## explicit
github.com/google/uuid
$ ls vendor/github.com/google/uuid | head -3
CHANGELOG.md
CONTRIBUTING.md
CONTRIBUTORS
  • Each # line is a module and version; ## explicit means it is listed in go.mod; the plain lines are the packages copied.
  • When a vendor folder exists and the go line is 1.14 or newer, go build uses it automatically, with no downloads.
  • The cost: your repository gets bigger. Most projects don't vendor; the proxy and go.sum are enough.
  • Change go.mod and forget to re-vendor, and the build stops (real run after go get example.com/gst@v1.2.1):
$ go build .
go: inconsistent vendoring in /tmp/notes28/shop:
    example.com/gst@v1.2.1: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
    example.com/gst@v1.1.0: is marked as explicit in vendor/modules.txt, but not explicitly required in go.mod

    To ignore the vendor directory, use -mod=readonly or -mod=mod.
    To sync the vendor directory, run:
        go mod vendor

Workspaces: go.work

Now Raju wants to improve gst himself: round the bill to whole rupees. The folder ~/work has two modules side by side: shop (it requires example.com/gst v1.1.0) and gst, his copy, whose Add is now:

func Add(price float64) float64 {
    return float64(int(price*1.05 + 0.5))
}

The shop's main.go prints gst.Add(99). It still uses the downloaded gst:

$ cd shop && go run .
bill 103.95

We could add a replace line, but it's easy to forget it in go.mod and commit it. A workspace is better: a go.work file that says "use these module folders, as they are on my disk". go work init makes one:

$ go work init ./shop ./gst && cat go.work
go 1.24.7

use (
    ./gst
    ./shop
)
$ cd shop && go run .
bill 104
$ cd shop && GOWORK=off go run .
bill 103.95
  • Every module named in a use line is used from its folder. Our local gst gives 104, and no go.mod changed.
  • GOWORK=off turns the workspace off for one command: back to 103.95. (go env GOWORK prints which go.work is in use; here /tmp/notes28/work/go.work.)
  • go work use adds another folder (real run, after making a third module tools):
$ go work use ./tools && cat go.work
go 1.24.7

use (
    ./gst
    ./shop
    ./tools
)
  • Keep go.work out of Git. It describes your laptop's folders, not the project.

Tools: the tool directive (Go 1.24)

Projects use programs while developing, like code generators and checkers, and everyone on the team should run the same version. Before Go 1.24, people used a trick: a file called tools.go with blank imports (episode 27) of those programs, just to get them into go.mod. Go 1.24 (February 2025) added the tool directive:

$ go get -tool example.com/chaitool@v0.3.0
go: downloading example.com/chaitool v0.3.0
go: added example.com/chaitool v0.3.0
$ tail -1 go.mod
tool example.com/chaitool
$ go tool chaitool
chaitool v0.3.0: menu checked, 0 problems
  • go get -tool adds the program as a requirement and writes a tool line. go tool chaitool runs it, at exactly the version in go.mod. go help get: "If -tool is used with @none, the line will be removed."
  • tool is also a meta-pattern (a word that stands for a group of packages): go get tool upgrades every tool at once, and go install tool installs them all. go list tool lists them:
$ go list tool
example.com/chaitool
  • The full go.mod after go get -tool (the tool is recorded as an indirect requirement):
module example.com/shop

go 1.24.7

require (
    example.com/billing v1.0.0
    example.com/delivery v1.0.0
    github.com/google/uuid v1.6.0
)

require (
    example.com/chaitool v0.3.0 // indirect
    example.com/gst v1.1.0 // indirect
)

tool example.com/chaitool

Mini project: the shop's dependencies

Build the shop module with real order IDs, keep its list exact, move a version down and up, and commit the right files. main.go makes three IDs and checks they are all different:

package main

import (
    "fmt"

    "github.com/google/uuid"
)

func main() {
    seen := map[string]bool{}
    for i := 1; i <= 3; i++ {
        id := uuid.New().String()
        seen[id] = true
        fmt.Println("order", id[:8], "chai x2")
    }
    fmt.Println("unique IDs:", len(seen))
}

Steps:

  1. go mod init example.com/shop
  2. go get github.com/google/uuid (order IDs)
  3. go mod tidy (direct, no extras)
  4. go list -m all (see every version)
  5. go get ...@v1.5.0, then @latest (downgrade, upgrade)
  6. commit go.mod and go.sum, never go.work

The real run:

$ go mod init example.com/shop
go: creating new go.mod: module example.com/shop
go: to add module requirements and sums:
    go mod tidy
$ go get github.com/google/uuid
go: added github.com/google/uuid v1.6.0
$ go mod tidy
$ cat go.mod
module example.com/shop

go 1.24.7

require github.com/google/uuid v1.6.0
$ go run .
order 4a022cd4 chai x2
order 0381d369 chai x2
order ed82cf41 chai x2
unique IDs: 3
$ go list -m all
example.com/shop
github.com/google/uuid v1.6.0
$ go get github.com/google/uuid@v1.5.0
go: downloading github.com/google/uuid v1.5.0
go: downgraded github.com/google/uuid v1.6.0 => v1.5.0
$ go list -m -u all
example.com/shop
github.com/google/uuid v1.5.0 [v1.6.0]
$ go get github.com/google/uuid@latest
go: upgraded github.com/google/uuid v1.5.0 => v1.6.0
$ go list -m all
example.com/shop
github.com/google/uuid v1.6.0
$ go mod verify
all modules verified
$ ls
go.mod
go.sum
main.go
  • go get printed no "downloading" line this time because v1.6.0 was already in the module cache. A map (episode 15) keeps each ID once, so unique IDs: 3 proves the three IDs differ (the clock version would have given 1).
  • Commit go.mod, go.sum and main.go. If you made a go.work while experimenting, leave it out.

Expert corner

Why go.mod lists modules you never import

The shop's go.mod has a second require block with example.com/gst v1.1.0 // indirect, although no shop code imports gst. go mod tidy records every module that provides a package to the build, and marks the ones you don't import yourself as // indirect. A useful side effect: your own go.mod now holds a minimum for gst too. Real run: remove delivery from main.go and tidy:

$ go mod tidy && cat go.mod
module example.com/shop

go 1.24.7

require (
    example.com/billing v1.0.0
    github.com/google/uuid v1.6.0
)

require example.com/gst v1.1.0 // indirect

gst stayed at v1.1.0, not v1.0.0: our own requirement is one of the minimums, and tidy never downgrades. Only an explicit go get changes it:

$ go get example.com/gst@v1.0.0
go: downloading example.com/gst v1.0.0
go: downgraded example.com/gst v1.1.0 => v1.0.0
$ go run .
order 73273e9b bill 118

Add delivery back, and MVS moves gst up again, by itself:

$ go get example.com/delivery@v1.0.0
go: added example.com/delivery v1.0.0
go: upgraded example.com/gst v1.0.0 => v1.1.0

Removing and upgrading: @none and -u

$ go get example.com/delivery@none
go: removed example.com/delivery v1.0.0

go help get: "To remove a dependency on a module and downgrade modules that require it: go get example.com/mod@none". And -u "instructs get to update modules providing dependencies of packages named on the command line to use newer minor or patch releases when available" (real run in the shop without delivery):

$ go get -u ./...
go: upgraded example.com/gst v1.1.0 => v1.2.1

-u gave v1.2.1, not the retracted v1.2.0. -u never crosses a major version: v2 is a different module path.

Seeing exactly what was downloaded

$ go mod download -json example.com/gst@v1.2.1
{
    "Path": "example.com/gst",
    "Version": "v1.2.1",
    "Info": "/tmp/notes28/modcache/cache/download/example.com/gst/@v/v1.2.1.info",
    "GoMod": "/tmp/notes28/modcache/cache/download/example.com/gst/@v/v1.2.1.mod",
    "Zip": "/tmp/notes28/modcache/cache/download/example.com/gst/@v/v1.2.1.zip",
    "Dir": "/tmp/notes28/modcache/example.com/gst@v1.2.1",
    "Sum": "h1:15bGLzEUvvhGKY1WmMc3nEgMEc61oWepR/I9Rh9+/NA=",
    "GoModSum": "h1:4otS+pjsF8mrFy/rNFuCrNpVXlSh3Bi1/bM5dKX83n0="
}

The module cache keeps the same .info, .mod and .zip files a proxy serves, plus the unpacked folder (Dir). Sum and GoModSum are exactly the two lines go.sum would get. That is why go.sum has a /go.mod line: Go often needs only a module's go.mod (to run MVS over the graph) without downloading its code.

go get is not go install

go help get: "In earlier versions of Go, 'go get' was used to build and install packages. Now, 'go get' is dedicated to adjusting dependencies in go.mod. 'go install' may be used to build and install commands instead." go install example.com/pkg@v1.2.3 installs a program at that version, ignoring the current go.mod. Use go get -tool when the whole team should share the version.

A short history

Go 1.11 (2018) added preliminary module support. Go 1.16 (February 2021) made module mode the default and added retract. Go 1.21 made the go line the minimum required version and added toolchain management (GOTOOLCHAIN=auto by default). Go 1.24 (February 2025) added tool directives, go get -tool and the tool meta-pattern, replacing the tools.go trick. Before modules, Go code lived in GOPATH; go help gopath now says: "When using modules, GOPATH is no longer used for resolving imports."

The go mod commands at a glance

From go help mod: download (download modules to local cache), edit (edit go.mod from tools or scripts), graph (print module requirement graph), init, tidy (add missing and remove unused modules), vendor (make vendored copy of dependencies), verify (verify dependencies have expected content), why (explain why packages or modules are needed). And: "day-to-day adding, removing, upgrading, and downgrading of dependencies should be done using 'go get'."

Common mistakes (and the real messages)

Mistake Real message Why Fix
go run main.go with an import but no go.mod no required module provides package github.com/google/uuid: go.mod file not found in current directory or any parent directory no module, no shopping list go mod init example.com/shop
importing a module that isn't in go.mod no required module provides package github.com/google/uuid; to add it: go get github.com/google/uuid not required yet go get, or go mod tidy
go.sum deleted or not committed missing go.sum entry for module providing package example.com/billing (imported by example.com/shop) no fingerprints to check go mod tidy; commit go.sum
go get github.com/go-chi/chi@v5.0.0 invalid version: go.mod has post-v5 module path "github.com/go-chi/chi/v5" v2+ needs the suffix github.com/go-chi/chi/v5
a version that doesn't exist github.com/google/uuid@v9.9.9: invalid version: unknown revision v9.9.9 no such tag go list -m -versions first
go.sum edited / bytes changed verifying example.com/gst@v1.1.0: checksum mismatch ... SECURITY ERROR fingerprint differs find out why; never just delete go.sum lines
go get example.com/gst@v1.2.0 warning: example.com/gst@v1.2.0: retracted by module author: wrong rate: 50% instead of 5% a known-bad release go get example.com/gst@latest
excluding a version and not checking dropping requirement on excluded version example.com/gst v1.1.0 Go falls back to another minimum check go list -m all
changing go.mod but not vendor/ inconsistent vendoring in ... vendor/modules.txt is stale go mod vendor
needing a newer Go with GOTOOLCHAIN=local go.mod requires go >= 1.25.0 (running go 1.24.7; GOTOOLCHAIN=local) the go line is a minimum install it, or allow GOTOOLCHAIN=auto
a toolchain line equal to the go line updates to go.mod needed; to update it: go mod tidy the line is redundant go mod tidy
go tool with a name that isn't a tool no such tool "chaitoolx" not in a tool line go get -tool ...

Practice

  1. (Homework) Build the shop module with github.com/google/uuid (the mini project) and run it.
  2. (Homework) Run go mod graph and go list -m all on a module with two dependencies, and find each arrow in the graph.
  3. (Homework) Change one character of a go.sum line, run go clean -modcache and go run ., read the SECURITY ERROR, then undo the change.
  4. (Homework) Make a go.work with a local copy of a library, change the copy, and see the change with and without GOWORK=off.
  5. Read this pseudo-version: v1.6.1-0.20241114170450-2d3c2a9cc518. Which tag is it built on? When was the commit made? Which commit?
  6. A library example.com/menu releases a breaking v3.0.0. What import path do you use, and what go get command?
  7. The shop requires billing (needs gst v1.0.0) and delivery (needs gst v1.1.0); gst v1.2.1 exists. You run go get example.com/gst@v1.0.0. What happens? (Hint: think about what delivery requires.)
  8. Raju's company keeps private modules at git.chai.example.com/... and at github.com/raju-chai/.... What GOPRIVATE value keeps them away from the public proxy and checksum database?
  9. Which of these files belong in Git: go.mod, go.sum, go.work, vendor/?
  10. After go get example.com/gst@v1.2.0, what does go list -m -u all show for gst, and why?
Solution
  1. The files and the real output are in the mini project section (unique IDs: 3).

  2. Every line of go mod graph is "module needs module@version". In the shop: example.com/billing@v1.0.0 example.com/gst@v1.0.0 and example.com/delivery@v1.0.0 example.com/gst@v1.1.0, while go list -m all shows the chosen example.com/gst v1.1.0.

  3. The real message is in the "The seal is broken" section: checksum mismatch, the downloaded and go.sum fingerprints one under the other, and SECURITY ERROR.

  4. Real outputs: bill 103.95 without the workspace, bill 104 with it, bill 103.95 with GOWORK=off.

  5. Built on v1.6.0 (the next patch would be v1.6.1, and the -0. part marks it as coming before any real v1.6.1); the commit's date and time are 2024-11-14, 17:04:50; the commit ID starts 2d3c2a9cc518.

  6. import "example.com/menu/v3" and go get example.com/menu/v3@v3.0.0. From v2 on, the major version is part of the module path. Old code importing example.com/menu keeps getting v1.

  7. You can't go below what delivery needs while delivery is in the build. A real run, done on the shop without delivery, shows the two halves: with only billing, go get example.com/gst@v1.0.0 printed go: downgraded example.com/gst v1.1.0 => v1.0.0 and the bill became 118 (18 percent). Adding delivery back printed go: added example.com/delivery v1.0.0 and go: upgraded example.com/gst v1.0.0 => v1.1.0: MVS takes the highest minimum again.

  8. GOPRIVATE=git.chai.example.com,github.com/raju-chai (a comma-separated list of module path prefixes; prefixes also match everything below them, and * works as in *.chai.example.com). Save it with go env -w GOPRIVATE=.... GONOPROXY and GONOSUMDB copy it unless you set them.

  9. go.mod and go.sum: always. go.work: no, it describes your own folders. vendor/: only if your project has decided to vendor (then commit it and keep it in sync with go mod vendor).

  10. example.com/gst v1.2.0 (retracted) [v1.2.1] (real output above). The author's retract v1.2.0 line in the latest version's go.mod marks it, and [v1.2.1] is the newest unretracted version.

Quick quiz

1. Which version of log does Go use? (From the video.)

shop        → api v1.0.0, cache v1.0.0
api v1.0.0  → log v1.2.0
cache v1.0.0 → log v1.4.0

log versions: v1.2.0 v1.4.0 v1.5.0 v1.9.0

A. log v1.2.0 · B. log v1.4.0 · C. log v1.9.0 · D. both v1.2.0 and v1.4.0

Answer

B. Minimal version selection: the highest of the minimum versions required, v1.4.0. Not v1.9.0, because nobody asked for it, and not both, because one program gets one copy of each major version.

2. What does // indirect after a require line mean?

Answer

No package in this module imports that module directly. It is needed by another dependency (like example.com/gst in the shop), or go get added it before your code imported it. go mod tidy adds or removes the comment as needed.

3. Who writes a retract directive, and does it stop people downloading the version?

Answer

The module's author, in the go.mod of a newer version. It doesn't stop downloads: retracted versions stay downloadable, but go get prints retracted by module author with the reason, and @latest skips them.

4. A library you use has replace example.com/gst => ../my-gst in its go.mod. Does it affect your build?

Answer

No. replace and exclude apply only in the main module, the one you're building. Only your own go.mod's replace lines count.

5. Which command shows v1.5.0 [v1.6.0]?

A. go list -m -versions · B. go list -m -u all · C. go mod graph · D. go mod why

Answer

B. -u adds the newest available version in brackets. A lists all released versions, C prints requirement arrows, D explains why a module is needed.

6. What does GOWORK=off go run . do?

Answer

Runs the module as if there were no go.work: dependencies come from go.mod (downloaded versions), not the workspace's folders. In the video, bill 104 went back to bill 103.95.

Interview questions

  1. What is a Go module, and what do go.mod and go.sum contain? A module is a collection of packages released, versioned and distributed together, identified by its module path. go.mod holds the module path, the go (minimum Go version) and optional toolchain lines, the minimum required version of each dependency, and optional replace, exclude, retract and tool lines. go.sum holds cryptographic hashes of each dependency version's files and of its go.mod, so later downloads can be verified.
  2. How does Go choose a dependency's version? Minimal version selection: from all go.mod files in the requirement graph, it takes, for each module, the highest of the required minimum versions. It never picks a newer version on its own, so builds are repeatable without a separate lock file; you upgrade explicitly with go get.
  3. What's the difference between go get and go mod tidy? go get changes requirements on purpose: add, upgrade, downgrade (@version) or remove (@none) a dependency. go mod tidy makes go.mod and go.sum match the imports in your code: it adds missing modules and removes unused ones, and fixes // indirect comments.
  4. Why does a v2 module need /v2 in its path? A major version may contain breaking changes, so Go treats it as a different module with a different import path. Old code keeps importing v1, new code imports /v2, and both can exist in one build. Without the suffix, go get fails, as in go.mod has post-v5 module path "github.com/go-chi/chi/v5".
  5. What is a pseudo-version? A version Go generates for an untagged commit: the next version after the last tag with a -0. marker, the commit's date and time, and a 12-character commit ID, e.g. v1.6.1-0.20241114170450-2d3c2a9cc518. It sorts after the base tag, so MVS still works.
  6. replace vs exclude vs retract? replace substitutes a module (or one version) with another module or a local folder; exclude forbids a specific version. Both apply only in the main module. retract is published by a module's author to mark their own versions as not to be used; it is read from the latest version's go.mod, and retracted versions remain downloadable.
  7. How do GOPROXY, GOSUMDB and GOPRIVATE work together? GOPROXY lists where to download modules (by default proxy.golang.org, then direct from the source). GOSUMDB names the checksum database (sum.golang.org) used to check a version's hashes the first time it is added. GOPRIVATE lists module path patterns that skip both; GONOPROXY and GONOSUMDB override it for each decision separately.
  8. When would you vendor, and when use a workspace? Vendor (go mod vendor) when builds must work without network access or you must keep dependency code in your repository; keep vendor/ in sync or you get inconsistent vendoring. Use a workspace (go.work) to develop several modules together locally without editing their go.mod files; don't commit it.
  9. How do you pin developer tools since Go 1.24? go get -tool example.com/tool@version adds a tool line and a requirement; go tool name runs it at that version; go get tool upgrades all tools and go install tool installs them. Before Go 1.24, a tools.go file with blank imports did the same job.

Glossary

Term Meaning Example
Dependency code written by someone else that your program needs, fetched by name and version github.com/google/uuid
Direct dependency a module whose packages your code imports uuid in the shop
Indirect dependency a module your build needs only because another dependency uses it example.com/gst
// indirect the go.mod comment that marks an indirect requirement require example.com/gst v1.1.0 // indirect
Module a collection of packages released, versioned and distributed together the shop; the uuid library
Module path a module's name, from its module line; the prefix of its import paths example.com/shop
Main module the module whose folder you run the go command in the shop
Import path the address of a package: module path + folder "github.com/google/uuid"
Module root the top folder of a module, where go.mod is shop/
go.mod the file at the module root listing the module path and requirements require github.com/google/uuid v1.6.0
Directive one kind of line in go.mod require, replace
module directive names this module module example.com/shop
go directive the minimum Go version needed (since Go 1.21) go 1.24.7
toolchain directive the Go release the main module prefers; kept only if newer than go toolchain go1.24.7
require directive the minimum version of a dependency require example.com/billing v1.0.0
replace directive use another folder or module instead (main module only) replace example.com/gst => ../gst-local
exclude directive never use this version (main module only) exclude example.com/gst v1.1.0
retract directive an author marks their own versions as not to be used (Go 1.16) retract v1.2.0 // wrong rate
tool directive a developer program pinned in go.mod (Go 1.24) tool example.com/chaitool
go.sum the file of checksums for every downloaded module version and its go.mod ... v1.6.0 h1:NIva...=
Checksum / hash a short fingerprint computed from every byte of some files; any change changes it h1:NIvaJDMOsjHA8n1j...=
h1: the prefix naming the hashing method used in go.sum h1:TIyPZe4M...=
Collision two things that should differ get the same value three orders with ID 234441
UUID a long random ID; two practically never match 56ecd5e8-...
Git the version control program that saves the history of code git commit
Commit one saved change in Git, with an ID 2d3c2a9cc518
Git tag a name attached to one commit; Go versions are tags v1.6.0
Semantic versioning (semver) versions as vMAJOR.MINOR.PATCH with agreed meanings v1.6.0
Major version changes when there are breaking changes v1 → v2
Minor version changes when features are added without breaking v1.5.0 → v1.6.0
Patch version changes for bug fixes only v1.6.0 → v1.6.1
v0 major version zero: experimental, anything may change v0.3.0
Breaking change a change after which code using the old version may stop compiling or working a renamed function
Pseudo-version a generated version for an untagged commit: base, time, commit ID v1.6.1-0.20241114170450-2d3c2a9cc518
Major version suffix /vN at the end of the module path for v2 and above github.com/go-chi/chi/v5
go mod init creates go.mod for a new module go mod init example.com/shop
go get adds, upgrades, downgrades or removes a dependency go get github.com/google/uuid@v1.5.0
@latest / @none newest (unretracted) release / remove the dependency go get example.com/delivery@none
go get -u upgrade dependencies to newer minor or patch releases go get -u ./...
go mod tidy make go.mod/go.sum match the imports: add missing, drop unused removed unused chi
go mod edit change go.mod from the command line go mod edit -replace ...
go list -m all list every module in the build with its selected version example.com/gst v1.1.0
go list -m -versions list a module's released versions v1.0.0 v1.1.0 v1.2.1
go list -m -u also show the newest available version in brackets v1.5.0 [v1.6.0]
go list -m -retracted include retracted versions ... v1.2.0 v1.2.1
go mod graph print every requirement as "module needs module@version" example.com/billing@v1.0.0 example.com/gst@v1.0.0
go mod why -m show an import chain that explains why a module is needed shop → billing → gst
go mod verify check cached modules against go.sum all modules verified
go mod download download modules into the module cache go mod download -json ...
Requirement graph all modules and the versions each requires the go mod graph output
Minimal version selection (MVS) for each module, use the highest of the minimum versions required gst v1.0.0 + v1.1.0 → v1.1.0
Repeatable build the same go.mod files always give the same versions no surprise upgrades
Module cache the local folder of downloaded modules, by default GOPATH/pkg/mod go clean -modcache empties it
GOPATH Go's older workspace folder; with modules it stores the module cache and installed commands /root/go
Fork your own copy of someone's repository, often with a fix replace to a fork
Vendoring copying all dependency code into vendor/ inside your module go mod vendor
go mod vendor creates the vendor/ folder and vendor/modules.txt stock in the store room
vendor/modules.txt the list of modules and packages in vendor/ # example.com/gst v1.1.0
Inconsistent vendoring vendor/ no longer matches go.mod re-run go mod vendor
Environment variable a named setting passed to programs; go env shows the go command's GOPROXY
go env prints (or with -w saves) go settings go env GOPROXY
Module proxy a server keeping copies of modules, answering fixed URLs; can even be a file:// folder proxy.golang.org
GOPROXY where to download modules from, in order https://proxy.golang.org,direct
direct in GOPROXY: fetch from the source repository GitHub via git
Checksum database a public register of every public module version's hashes sum.golang.org
GOSUMDB which checksum database to use sum.golang.org
GOPRIVATE comma-separated glob patterns of private module path prefixes; skip proxy and checksum database GOPRIVATE=*.corp.example.com,rsc.io/private
GONOPROXY / GONOSUMDB override GOPRIVATE for just the proxy / just the checksum database decision GONOSUMDB=example.com
Glob pattern a pattern where * means "anything here" *.corp.example.com
SECURITY ERROR Go's message when a download doesn't match go.sum checksum mismatch
Workspace several local modules used together from their folders, described by go.work ~/work
go.work the workspace file with use lines; not committed use ./gst
go work init create go.work with the given folders go work init ./shop ./gst
go work use add a folder to go.work go work use ./tools
use a go.work line: use this module from this folder use ./shop
GOWORK=off ignore go.work for this command GOWORK=off go run .
Toolchain a whole Go release: compiler, go command and tools go1.24.7
GOTOOLCHAIN which toolchain may be used; default auto (may download a newer one), local (installed only) GOTOOLCHAIN=local
go get -tool add a program as a requirement and a tool line (Go 1.24) go get -tool example.com/chaitool@v0.3.0
go tool run a tool at the version in go.mod go tool chaitool
tool meta-pattern the word tool standing for all of a module's tools go get tool, go install tool
tools.go trick the pre-1.24 way: a file of blank imports of tools import _ "example.com/chaitool"
go install pkg@version build and install a program at a version, ignoring the current go.mod go install example.com/pkg@latest
Floating-point rounding floats can't store most decimals exactly 47.199999999999996

Summary

  • A module is a set of packages released together with one module path and one version. Its go.mod lists the path, the minimum Go version (go), an optional toolchain, and the minimum version of every dependency (require); go.sum holds a checksum of every download. Commit both.
  • go get adds, upgrades, downgrades (@v1.5.0, @latest, a commit) or removes (@none) dependencies; go mod tidy makes the list exactly match your imports and fixes // indirect. go list -m all / -versions / -u and go mod graph show what you have.
  • Versions are semver Git tags (MAJOR.MINOR.PATCH, v0 = experimental); untagged commits get pseudo-versions; v2 and above get a new path (/v5).
  • Minimal version selection picks the highest minimum anyone required, never something newer on its own: repeatable builds.
  • retract is the author's "don't use this version"; replace and exclude are your own module's rules and only work in the main module.
  • Downloads come from GOPROXY and are checked against go.sum and the GOSUMDB checksum database (a mismatch is a SECURITY ERROR); GOPRIVATE keeps company modules away from both.
  • go mod vendor keeps dependencies in vendor/; go.work (go work init, use, GOWORK=off) edits modules side by side without touching go.mod, and stays out of Git; tool lines (Go 1.24, go get -tool, go tool) pin developer programs.

Next episode: Project layout, documentation and linting: cmd/ and internal/, doc comments, go doc, pkg.go.dev, examples, staticcheck and golangci-lint.