By the end of this page you will have a Go module on your disk with a passing test in it. Everything after this course builds on that folder, so do it now rather than reading ahead.
You need a terminal and a text editor. That is the whole setup.
Install Go
Grab it from go.dev/dl, or use a package manager:
brew install go
Check it took:
go version
go version go1.26.6 darwin/arm64
Go 1.26 or newer is needed for this course — course 08 uses an iterator that
landed in 1.26. If the command is not found, your shell cannot see Go’s bin
directory; the install page has the fix for your platform.
That version number is easy to get wrong, and Go now checks it for you. If your
go.mod claims an older version than the standard library you actually call,
go build says nothing but vet does:
reflect.(Type).Fields requires go1.26 or later (file is go1.23)
sync.(*WaitGroup).Go requires go1.25 or later (file is go1.23)
That is the stdversion check, and since Go 1.27 go test runs it for you.
Start a module
Every Go project is a module, and a module is a folder with a go.mod in it:
mkdir greet && cd greet
go mod init example.com/greet
Before you look — what do you think is in go.mod? Most build tools would
have written a manifest with a version, a name, a licence, a scripts block.
cat go.mod
module example.com/greet
go 1.26
Two lines. example.com/greet is the module path — the prefix other code would
use to import yours. Nothing on the internet is contacted and nothing is
downloaded. If you plan to publish, use the real location
(github.com/yourname/greet); otherwise example.com/anything is fine.
Keep this folder. Courses 02 through 09 all add files to it.
Write something, run it
Create main.go:
package main
import "fmt"
func Greet(name string) string {
return fmt.Sprintf("Hello, %s!", name)
}
func main() {
fmt.Println(Greet("Ada"))
}
go run .
Hello, Ada!
go run . compiles the package in the current directory and runs it, leaving no
binary behind. The . matters — it means “this directory”, and you will use it
constantly.
package main plus a func main() is what makes a package executable. Any other
package name produces a library instead, which is what course 02 onward will be
writing.
Your turn: break it on purpose
Go’s compiler is stricter than you expect, and its error messages are good. Find
out how strict. Add this function to main.go and run go run .:
func broken() {
var n int = "hello"
unused := 5
}
Predict how many errors you get. There are two obvious problems — is the unused variable one of them?
./main.go:4:6: declared and not used: n
./main.go:4:14: cannot use "hello" (untyped string constant) as int value
./main.go:5:2: declared and not used: unused
Three. An unused local variable is a compile error in Go, not a warning. So is an unused import. Coming from almost any other language this feels aggressive for about a week, and then you notice you have stopped accumulating dead code.
Delete broken before moving on.
Test it
Go has a test runner built in — no framework to install. Create greet_test.go:
package main
import "testing"
func TestGreet(t *testing.T) {
got := Greet("Ada")
want := "Hi, Ada!"
if got != want {
t.Errorf("Greet(%q) = %q, want %q", "Ada", got, want)
}
}
That want is deliberately wrong. Run it and read the failure before you fix
it — you will be reading these for the rest of the course:
go test ./...
--- FAIL: TestGreet (0.00s)
greet_test.go:9: Greet("Ada") = "Hello, Ada!", want "Hi, Ada!"
FAIL
The message is whatever you wrote in t.Errorf. Go ships no assertion library,
so the convention is to print got and want in that order, with %q so empty
strings and stray whitespace are visible.
Now change want to "Hello, Ada!" and run again:
ok example.com/greet 0.471s
Red, then green. That loop is the one you will repeat in every remaining course.
Format it
Go does not have a style debate. Mangle the spacing in main.go — put spaces
inside the parens, drop the indentation, remove the space after a comma:
func Greet( name string ) string {
return fmt.Sprintf("Hello, %s!",name)
}
Ask which files are badly formatted, then fix them:
gofmt -l . # lists files that need changing
gofmt -w . # rewrites them in place
func Greet(name string) string {
return fmt.Sprintf("Hello, %s!", name)
}
Tabs, not spaces. Nobody chose that and nobody can change it, which is the
feature — every Go codebase you ever open is formatted identically. Set your
editor to run gofmt on save and forget it exists.
Vet it
Add a deliberate mistake to main:
fmt.Printf("%d\n", "not a number")
Predict: does go run . fail? A %d verb with a string argument.
Hello, Ada!
%!d(string=not a number)
It compiles and runs, printing garbage. Printf takes ...any, so the compiler
has nothing to object to. This is what go vet is for:
go vet ./...
main.go:11:13: fmt.Printf format %d has arg "not a number" of wrong type string
Vet catches what compiles but is probably wrong. Format strings, unreachable
code, mutexes copied by value, lost context cancellations. It is fast, it has
almost no false positives, and go test runs a subset of it automatically. Run
the full thing before you commit.
Remove the bad Printf line.
Build it
To ship a real binary:
go build -o greet .
./greet
Hello, Ada!
One self-contained executable with the runtime baked in — around 2 MB, no
interpreter, no node_modules. Copy it to another machine of the same
OS and architecture and it runs.
The six commands
That is the whole toolchain for this course:
| Command | What it does |
|---|---|
go mod init <path> |
Start a module |
go run . |
Compile and run the current package |
go build -o <name> . |
Produce a standalone binary |
go test ./... |
Run every test in the tree |
gofmt -w . |
Format code in place |
go vet ./... |
Report likely mistakes |
Two more for later: go get adds a dependency (course 13, when we add pgx), and
go doc prints documentation in your terminal — try go doc fmt.Printf now.
Build something
Make Greet("") return "Hello, stranger!" instead of "Hello, !".
Write the test first, watch it fail, then fix the function:
go test ./... # red
go test ./... # green
Then run gofmt -l . and go vet ./... over your work. Getting into that habit
now costs nothing; discovering it in course 09 costs you a rewrite.
Check yourself once it passes
func Greet(name string) string {
if name == "" {
return "Hello, stranger!"
}
return fmt.Sprintf("Hello, %s!", name)
}
func TestGreetEmpty(t *testing.T) {
got := Greet("")
want := "Hello, stranger!"
if got != want {
t.Errorf("Greet(%q) = %q, want %q", "", got, want)
}
}
You now have two tests that are the same five lines with different values. That duplication is the setup for course 09, where one table-driven test replaces both — the idiom you will see throughout real Go code.
Next
You have a module, a binary, a passing test, and a formatter that will never ask
your opinion. Next: Go’s type system — starting with the fact that there is no
null, and what happens instead when you declare a variable and walk away.