Go Packages & Modules

# Create go.mod in current directory
go mod init github.com/you/myproject

# Tidy: add missing, remove unused dependencies
go mod tidy

# Download all dependencies to module cache
go mod download

# Vendor all dependencies into ./vendor/
go mod vendor

# Print module graph
go mod graph

# go.sum records SHA-256 hashes for every
# dependency version used, plus its go.mod.
# It is machine-generated — do not edit by hand.
# Commit it to source control.

# Verify all modules against go.sum
go mod verify

# If go.sum is out of date after editing go.mod:
go mod tidy

# Install a tool to $GOPATH/bin
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Install a specific version
go install golang.org/x/tools/cmd/goimports@v0.20.0

# go install vs go get:
# go install — for tools you run from the CLI
# go get     — for library dependencies in a module

# List all direct and indirect dependencies
go list -m all

# List with JSON output
go list -m -json all

# Show why a package is needed
go mod why github.com/pkg/errors

# List outdated dependencies
go list -m -u all

// go.mod
require github.com/foo/bar/v2 v2.3.0

// source code — import path includes /v2
import "github.com/foo/bar/v2"

// v1 and v2 can coexist in the same build
import (
    barv1 "github.com/foo/bar"
    barv2 "github.com/foo/bar/v2"
)

# Pre-release tag
go get github.com/foo/bar@v1.0.0-beta.1

# Pseudo-version: commit hash before first tag
# v0.0.0-20240115123456-abcdefabcdef
# Generated automatically when pointing to a commit:
go get github.com/foo/bar@main

# Point to a specific commit
go get github.com/foo/bar@abc1234

// go.mod — retract a version you released by mistake
retract v1.3.0  // critical bug introduced

// Retract a range
retract [v1.3.0, v1.3.2]

// go get will warn about retracted versions
// Existing users are not auto-upgraded

// go.mod — prevent a known-bad version from being selected
exclude github.com/foo/bar v1.2.3

// MVS will skip to the next available version
// Useful if a dependency published a broken release
// and you can't wait for them to retract it

# Create go.work and add current module
go work init ./service ./shared

# Add another module to an existing workspace
go work use ./newmodule

# Sync workspace — update go.work.sum
go work sync

# Disable workspace for a single command
GOWORK=off go test ./...

go 1.22

use (
    ./service
    ./shared
)

// Optional: replace directives here override
// all modules in the workspace
replace github.com/external/dep => ../local-dep

// Package name is the last element of its import path
// import "github.com/you/proj/config"  →  package config

// All files in a directory share one package name
// Exception: _test.go files may use package foo_test

// Package names: short, lowercase, no underscores
// Good: config, httputil, timeutil
// Bad:  myConfig, http_util, util (too generic)

// Exported identifiers start with a capital letter
func DoWork() {}      // exported
func doWork() {}      // unexported

// Packages under internal/ can only be imported by
// code rooted at the parent of the internal/ directory

myproject/
├── internal/
│   └── auth/      // importable by myproject/...
│       └── auth.go
└── api/
    └── api.go     // can import internal/auth

// External packages cannot import internal/auth
// The compiler enforces this — no runtime check

# Tell Go not to use the checksum database for private modules
GONOSUMDB=github.com/yourorg/*

# Or set permanently in go env
go env -w GONOSUMDB=github.com/yourorg/*

# Skip sum verification entirely for a pattern
go env -w GONOSUMCHECK=github.com/yourorg/*

# Multiple patterns (comma-separated)
go env -w GONOSUMDB=github.com/yourorg/*,gitlab.yourcompany.com/*

# GOPRIVATE sets both GONOSUMDB and GONOPROXY
go env -w GOPRIVATE=github.com/yourorg/*

# Use a private proxy, fall back to direct
go env -w GOPROXY=https://proxy.company.com,direct

# Bypass proxy for private modules
go env -w GONOPROXY=github.com/yourorg/*

# Direct fetch only (no proxy)
GOPROXY=direct go get github.com/yourorg/secret