Go Reference

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This section is written against Go 1.27 (the current stable release is go1.27.2), checked on 2026-10-18. Go ships a major release about every six months and supports the two newest ones, here Go 1.27 and Go 1.26; Go 1.28 is not released yet (it is expected around February 2027), so nothing here depends on it. Features newer than the oldest supported release are marked with the version that introduced them, for example WaitGroup.Go (1.25), b.Loop (1.24), range over functions (1.23), per-iteration loop variables and the enhanced ServeMux (1.22), generics (1.18), and in 1.27 generic methods and encoding/json/v2. Every go.mod shown declares go 1.27, and every example was compiled, vetted and run with go1.27.2.

What Go is

Go is a compiled, statically typed, garbage-collected language designed at Google by Robert Griesemer, Rob Pike and Ken Thompson and released as open source in 2009. It aims at software that is easy to read, fast to build and simple to deploy: a small language specification, a fast compiler that produces a single static binary, implicit interfaces and composition instead of inheritance, errors as ordinary values, and first-class concurrency with goroutines, channels and select. Around the language sits one official toolchain — the go command with its module system, gofmt, go vet, go test with benchmarks and fuzzing, go doc and the profilers — and a large standard library that covers HTTP, JSON, cryptography, templates and databases without third-party code. Go powers cloud infrastructure (Docker, Kubernetes, Prometheus and Terraform are written in it), network services, command-line tools and, with WebAssembly, code that runs in browsers and WASI hosts.

The shelf scenario

The examples across the section share one small, original domain: shelf, a Go module (example.com/shelf, go 1.27) for a library catalogue. It is deliberately the same domain as the Rust Reference, so you can compare the two languages on the same types.

  • The catalog package holds Book, Author, ISBN (a validated defined type with a String method), Loan and LoanState (an iota enumeration) types, a Store interface and an in-memory implementation guarded by a mutex.

  • An internal/ package holds helpers that are not part of the public API.

  • cmd/shelf is a command-line program that searches, lends and returns books and imports and exports JSON.

  • cmd/shelfd is an HTTP service that exposes the catalogue as JSON with net/http, log/slog and database/sql.

  • Tests, benchmarks, a fuzz test for ISBN parsing and a testable example grow alongside the code.

The pages build on each other, and the cheat sheet summarises them.

New here? Read in this order

  1. Getting Started — install Go, the go command, a first program

  2. Variables, Constants and iota and Types and Values

  3. Control Flow and Functions, Closures and Defer

  4. Arrays and Slices, Maps and Structs and Embedding

  5. Methods and Receivers and Interfaces — how Go does abstraction

  6. Error Handling

  7. Goroutines and the Scheduler, Channels and Select and Context — the concurrency model

  8. Modules and Dependency Management and Testing

  9. Generics and Iterators and Range-over-Func

Then pick topics as you need them, and keep the cheat sheet at hand. If you know an older tutorial, start with What’s New and Migrating Older Code.

mindmap root((Go Reference)) Getting started Toolchain and versions Program structure Core language Types and constants Control flow Functions and defer Pointers Composite types Slices and maps Strings and runes Structs Abstraction Methods and interfaces Generics Iterators Errors Concurrency Goroutines and channels Context and sync Memory model Tooling Modules and workspaces go command and builds Testing and fuzzing vet and analysis Standard library fmt, io, time json and slog net/http and sql Crypto Runtime and interop Reflection and unsafe GC and profiling PGO cgo and WebAssembly Practice Idioms Gotchas Migration

What’s covered

Getting started

Page What it covers

Getting Started

what Go is for, installing it, the go command, editors, Hello world, the Playground and the shelf module

Go IDEs & Tools

GoLand, VS Code, Neovim and gopls

Toolchain Versions and Compatibility

release cycle, support policy, the Go 1 promise, go and toolchain lines, GOTOOLCHAIN, GODEBUG

Program Structure and Lexical Elements

source files, tokens, semicolon insertion, comments, program execution

Design Philosophy and Coming from Other Languages

the design goals, what Go leaves out, and a map from other languages

Core language

Page What it covers

Variables, Constants and iota

var, short declarations, zero values, typed and untyped constants, iota

Types and Values

every predeclared type with size, range and zero value, conversions, literals

Operators and Expressions

arithmetic, comparison, logical and bit operators, precedence, order of evaluation

Control Flow

if, the four for forms, range, switch, type switch, labels, goto

Functions, Closures and Defer

parameters, results, variadics, closures, defer, panic and recover

Pointers and Value Semantics

pointers, nil, new, copying, escape and value versus pointer design

Composite types

Page What it covers

Arrays and Slices

arrays, the slice header, append and capacity, aliasing, the slices package

Maps

map types, comma-ok, delete and clear, iteration order, sets, the maps package

Strings, Runes and UTF-8

strings as bytes, runes, UTF-8, conversions, strings.Builder

Structs and Embedding

fields, literals, tags, comparison, embedding and promotion

Abstraction

Page What it covers

Methods and Receivers

value and pointer receivers, method sets, method values and expressions

Interfaces

implicit satisfaction, embedding, nil interfaces, assertions, type switches, any

Composition and Object-Oriented Design

encapsulation, constructors, functional options and polymorphism without classes

Generics

type parameters, constraints, inference, generic types and (Go 1.27) generic methods

Iterators and Range-over-Func

iter.Seq and Seq2, range over functions, iter.Pull, slices and maps helpers

Error Handling

errors as values, wrapping, Is, As, AsType, Join, custom and sentinel errors

Concurrency

Page What it covers

Goroutines and the Scheduler

the go statement, lifetimes, WaitGroup.Go, the GMP scheduler, GOMAXPROCS

Channels and Select

unbuffered and buffered channels, close, the axioms table, select

Concurrency Patterns

pipelines, fan-out and fan-in, worker pools, semaphores, errgroup

Context

cancellation, deadlines, values, AfterFunc and propagation through a call tree

Sync and Atomics

Mutex, RWMutex, Once, Pool, Map, Cond and typed atomics

Memory Model and Data Races

happens-before, synchronization points, the race detector

Packages, modules and tooling

Page What it covers

Packages, Imports and Initialization

packages, import forms, visibility, init order, internal

Modules and Dependency Management

go.mod directives, versions, MVS, go.sum, proxies, vendoring, tool directives

Workspaces, Versioning and Publishing

go.work, version numbers, publishing, retraction, major versions

The go Command, Builds and Cross-Compilation

go build and friends, flags, ldflags, build constraints, GOOS and GOARCH

Directives, Code Generation and Embedding

go:generate, go:embed, go:build, go:debug, go:fix inline and other directives

Testing

go test, table tests, subtests, helpers, examples, coverage, t.Context

Benchmarks, Fuzzing and synctest

b.Loop benchmarks, benchstat, native fuzzing, testing/synctest

Formatting, vet, fix and Static Analysis

gofmt, goimports, go vet, go fix modernizers, staticcheck, golangci-lint

Documentation and Doc Comments

doc comment syntax, go doc, pkgsite, examples, deprecation notices

Standard library

Page What it covers

fmt, Strings and Text Processing

fmt verbs, strings, strconv, bytes, regexp, text/scanner

Text and HTML Templates

text/template and html/template actions, pipelines and escaping

I/O, Files and the Filesystem

io interfaces, bufio, os, io/fs, os.Root, embed and filepath

Time and Timers

Duration, Time, zones, layouts, Timer and Ticker semantics

encoding/json

encoding/json v1, struct tags, streaming, and encoding/json/v2 with jsontext

Structured Logging with slog

Logger, Handler, levels, attributes, groups and custom handlers

net/http Clients and Servers

Client, Transport, ServeMux patterns, middleware, timeouts, CrossOriginProtection

database/sql

the connection pool, queries, transactions, null handling and context

Command-Line Programs

os.Args, flag, exit codes, signals, os/exec and process boundaries

Collections and Utility Packages

slices, maps, cmp, sort, container, math, big, unique and friends

Crypto and Security

crypto/rand, hashing, HMAC, AEAD, TLS, post-quantum and FIPS 140-3

Runtime, advanced topics and interop

Page What it covers

Reflection

the three laws, Type, Kind, Value, struct tags and their costs

unsafe and Low-Level Programming

unsafe.Pointer rules, Sizeof, alignment, struct padding, syscall

Memory Management and Garbage Collection

escape analysis, the allocator, the GC cycle, GOGC and GOMEMLIMIT

Cleanups, Weak Pointers and Interning

finalizers, AddCleanup, weak pointers and unique

Profiling, Tracing and Diagnostics

pprof, trace, flight recorder, goroutine leak profiles, runtime/metrics

Performance and PGO

the measure-change loop, inlining, escape analysis and profile-guided optimization

cgo and C Interoperability

import "C", type conversion, pointer-passing rules, calling Go from C

WebAssembly and WASI

GOOS=js and GOOS=wasip1, wasmexport, hosts and limits

Practice and evolution

Page What it covers

Idioms, Style and Code Review

Effective Go in 2026, Code Review Comments, Google and Uber style guides

Common Mistakes and Gotchas

the classic pitfalls with causes, symptoms and fixes

What’s New and Migrating Older Code

Go 1.18 to 1.27 release by release, and migrating older code

Quick reference

Cheat Sheet — one A4 page, downloadable as a PDF.

Related material on this site

The section draws on the official documentation first, and on two books for concept coverage.

Bibliography

Books

  • Jon Bodner, Learning Go: An Idiomatic Approach to Real-World Go Programming, 1st edition. O’Reilly Media, 2021 (March). ISBN 978-1-492-07721-3 (print), 978-1-492-07720-6 (eBook). Publisher page; companion code. A 2nd edition (O’Reilly, January 2024, ISBN 978-1-098-13929-2, publisher page) exists; it is a newer edition that was not consulted.

  • Vladimir Vivien, Learning Go Programming, 1st edition (technical reviewers Quintessence Anx, Parth Desai, Abhishek Kumar and Chris Schaefer). Packt Publishing, 2016 (October). ISBN 978-1-78439-543-8. Publisher page; companion code and Packt repository. Its fundamentals are still useful; its GOPATH-era tooling chapters are obsolete.

The books are consulted references, not the primary source: no text, listing or figure was taken from them, and every example was written against the current official documentation. On any discrepancy, and wherever a book is silent on a later feature, the official documentation wins; where a book shows an outdated form, the pages say so in prose (collected on What’s New and Migrating Older Code).

Official Go documentation and resources

Go blog posts

The Go blog posts used by the pages, each cited on the page that derives from it: alias names, allocation optimizations, archsimd, cgo, chacha8rand, cleanups and weak, codelab share, comparable, compat, concurrency timeouts, constants, container aware gomaxprocs, context, context and structs, coretypes, cover, deadcode, defer panic and recover, error handling and go, error syntax, errors are values, examples, execution traces 2024, fips140, flight recorder, generate, generic interfaces, generic methods, generic slice functions, get familiar with workspaces, go1.13 errors, go1.21, go15gc, gob, gofix, gofmt, goroutine leak profiles, greenteagc, inliner, integration test coverage, intro generics, io2013 talk concurrency, ismmkeynote, json, jsonv2 exp, laws of reflection, loopvar preview, maps, module compatibility, module mirror launch, normalization, organizing go code, osroot, package names, path security, pgo, pgo preview, pipelines, playground, pprof, profiling go programs, publishing go modules, race detector, randv2, range functions, rebuild, routing enhancements, simd experiment, size specialized allocations, slices, slices intro, slog, strings, subtests, supply chain, swisstable, synctest, testing b loop, testing time, toolchain, type inference, unique, using go modules, v2 go modules, wasi, wasmexport, waza talk, when generics, why generics.

golang.org/x repositories

The golang.org/x repositories are maintained by the Go team but sit outside the standard library and have looser compatibility guarantees; they are labelled as such where used.

Community references

These are not official; the pages label them as community material.

Specifications and standards