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/uuidis the real public library, downloaded from GitHub. The modulesexample.com/gst,example.com/billing,example.com/deliveryandexample.com/chaitoolare small demo modules (a few lines each) served from a local module proxy, so you can rebuild every example yourself.go help goproxysays: "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,directInside 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
listholds the version names,.infothe version and its time,.moditsgo.mod, and.zipits files.,directmeans: anything not in the folder (likegithub.com/google/uuid) is fetched straight from its source. The sandbox couldn't reach the public checksum database either, so the demo also setGONOSUMDB=example.com,github.com(explained below);go.sumchecks 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):234441is 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.modfile, 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 likefmtcome with Go itself). - Every module has a
go.modfile 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
replaceandexclude) only read the main module'sgo.mod. go help modulesbegins: "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 initcreatesgo.mod. Becausemain.goalready imports something, it also suggestsgo 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 getfound the newest version,v1.6.0, downloaded it, and wrote it intogo.mod. Two runs, two different IDs: real randomness, in one line of our code.go help getsays 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 defaultGOPATH/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
moduleline names our module. Thegoline is the minimum Go version this module needs. Therequireline says: we needgithub.com/google/uuid, at least versionv1.6.0. Notice the comment// indirect; we fix it in the next section. - A directive is one kind of line in
go.mod:module,goandrequireare directives. You'll meet all eight below. go.sumhas two lines per module version: one for the module's code, one for just itsgo.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
// indirectmeans: no package in this module imports it directly.go getwrote 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/gstmarked 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.
-mmeans "list modules, not packages". - chi is gone. Tidy removed it, because no code uses it. Run
go mod tidybefore 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.0attached 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@versionasks 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 getsays added, upgraded or downgraded every time a version changes. Read those lines: they are the history of yourgo.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/chikeeps working, and new code importsgithub.com/go-chi/chi/v5. Both can even live in one program, because to Go they are two different modules. v0andv1have no suffix. The package name stays the normal one: you still writechi.NewRouter(), notv5.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.modfiles always give the same versions, today and in five years, with no surprise upgrades. You upgrade only when you rungo get. go mod why -mshows 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%
retractis 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 thego.modof the module's latest version, and retracted versions stay downloadable (so builds that already use them don't break).retractwas 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 editchangesgo.modfrom the command line (you can also edit the file by hand). The bill went from 150 back to 105, andgo listshows 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
billingasked for,v1.0.0, whose rate is 18 percent (100 → 118). The odd47.199999999999996is 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 checkgo list -m allafterwards. - Both
replaceandexcludeonly work in the main module. If a library you depend on hasreplaceorexcludelines, 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 NAMEprints the go command's value of it, andgo env -w NAME=valuesaves one. - A module proxy is a server that keeps copies of public modules, like a wholesale market keeping stock of every brand.
go help privatecallsproxy.golang.org"the public Go module mirror".directmeans: 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.sumplus the checksum database make downloads tamper-proof. - Never "fix" this by deleting
go.sumlines 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;## explicitmeans it is listed ingo.mod; the plain lines are the packages copied. - When a
vendorfolder exists and thegoline is 1.14 or newer,go builduses it automatically, with no downloads. - The cost: your repository gets bigger. Most projects don't vendor; the proxy and
go.sumare enough. - Change
go.modand forget to re-vendor, and the build stops (real run aftergo 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
useline is used from its folder. Our local gst gives 104, and nogo.modchanged. - GOWORK=off turns the workspace off for one command: back to 103.95. (
go env GOWORKprints whichgo.workis 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.workout 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
toolline. go tool chaitool runs it, at exactly the version ingo.mod.go help get: "If -tool is used with @none, the line will be removed." toolis also a meta-pattern (a word that stands for a group of packages):go get toolupgrades every tool at once, andgo install toolinstalls them all.go list toollists them:
$ go list tool
example.com/chaitool
- The full
go.modaftergo 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:
go mod init example.com/shopgo get github.com/google/uuid(order IDs)go mod tidy(direct, no extras)go list -m all(see every version)go get ...@v1.5.0, then@latest(downgrade, upgrade)- commit
go.modandgo.sum, nevergo.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 getprinted no "downloading" line this time becausev1.6.0was already in the module cache. A map (episode 15) keeps each ID once, sounique IDs: 3proves the three IDs differ (the clock version would have given 1).- Commit
go.mod,go.sumandmain.go. If you made ago.workwhile 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
- (Homework) Build the shop module with
github.com/google/uuid(the mini project) and run it. - (Homework) Run
go mod graphandgo list -m allon a module with two dependencies, and find each arrow in the graph. - (Homework) Change one character of a
go.sumline, rungo clean -modcacheandgo run ., read the SECURITY ERROR, then undo the change. - (Homework) Make a
go.workwith a local copy of a library, change the copy, and see the change with and withoutGOWORK=off. - Read this pseudo-version:
v1.6.1-0.20241114170450-2d3c2a9cc518. Which tag is it built on? When was the commit made? Which commit? - A library
example.com/menureleases a breakingv3.0.0. What import path do you use, and whatgo getcommand? - The shop requires
billing(needsgst v1.0.0) anddelivery(needsgst v1.1.0);gst v1.2.1exists. You rungo get example.com/gst@v1.0.0. What happens? (Hint: think about whatdeliveryrequires.) - Raju's company keeps private modules at
git.chai.example.com/...and atgithub.com/raju-chai/.... WhatGOPRIVATEvalue keeps them away from the public proxy and checksum database? - Which of these files belong in Git:
go.mod,go.sum,go.work,vendor/? - After
go get example.com/gst@v1.2.0, what doesgo list -m -u allshow for gst, and why?
Solution
-
The files and the real output are in the mini project section (
unique IDs: 3). -
Every line of
go mod graphis "module needs module@version". In the shop:example.com/billing@v1.0.0 example.com/gst@v1.0.0andexample.com/delivery@v1.0.0 example.com/gst@v1.1.0, whilego list -m allshows the chosenexample.com/gst v1.1.0. -
The real message is in the "The seal is broken" section:
checksum mismatch, the downloaded andgo.sumfingerprints one under the other, andSECURITY ERROR. -
Real outputs:
bill 103.95without the workspace,bill 104with it,bill 103.95withGOWORK=off. -
Built on
v1.6.0(the next patch would bev1.6.1, and the-0.part marks it as coming before any realv1.6.1); the commit's date and time are 2024-11-14, 17:04:50; the commit ID starts2d3c2a9cc518. -
import "example.com/menu/v3"andgo get example.com/menu/v3@v3.0.0. From v2 on, the major version is part of the module path. Old code importingexample.com/menukeeps getting v1. -
You can't go below what
deliveryneeds whiledeliveryis in the build. A real run, done on the shop withoutdelivery, shows the two halves: with onlybilling,go get example.com/gst@v1.0.0printedgo: downgraded example.com/gst v1.1.0 => v1.0.0and the bill became 118 (18 percent). Addingdeliveryback printedgo: added example.com/delivery v1.0.0andgo: upgraded example.com/gst v1.0.0 => v1.1.0: MVS takes the highest minimum again. -
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 withgo env -w GOPRIVATE=....GONOPROXYandGONOSUMDBcopy it unless you set them. -
go.modandgo.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 withgo mod vendor). -
example.com/gst v1.2.0 (retracted) [v1.2.1](real output above). The author'sretract v1.2.0line in the latest version'sgo.modmarks 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
- 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.modholds the module path, thego(minimum Go version) and optionaltoolchainlines, the minimum required version of each dependency, and optionalreplace,exclude,retractandtoollines.go.sumholds cryptographic hashes of each dependency version's files and of itsgo.mod, so later downloads can be verified. - How does Go choose a dependency's version? Minimal version selection: from all
go.modfiles 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 withgo get. - What's the difference between go get and go mod tidy?
go getchanges requirements on purpose: add, upgrade, downgrade (@version) or remove (@none) a dependency.go mod tidymakesgo.modandgo.summatch the imports in your code: it adds missing modules and removes unused ones, and fixes// indirectcomments. - 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 getfails, as ingo.mod has post-v5 module path "github.com/go-chi/chi/v5". - 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. - replace vs exclude vs retract?
replacesubstitutes a module (or one version) with another module or a local folder;excludeforbids a specific version. Both apply only in the main module.retractis published by a module's author to mark their own versions as not to be used; it is read from the latest version'sgo.mod, and retracted versions remain downloadable. - How do GOPROXY, GOSUMDB and GOPRIVATE work together?
GOPROXYlists where to download modules (by defaultproxy.golang.org, thendirectfrom the source).GOSUMDBnames the checksum database (sum.golang.org) used to check a version's hashes the first time it is added.GOPRIVATElists module path patterns that skip both;GONOPROXYandGONOSUMDBoverride it for each decision separately. - 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; keepvendor/in sync or you getinconsistent vendoring. Use a workspace (go.work) to develop several modules together locally without editing theirgo.modfiles; don't commit it. - How do you pin developer tools since Go 1.24?
go get -tool example.com/tool@versionadds atoolline and a requirement;go tool nameruns it at that version;go get toolupgrades all tools andgo install toolinstalls them. Before Go 1.24, atools.gofile 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 optionaltoolchain, 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 touchinggo.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.