Go Linting

Core Principle

More important than any "blessed" set of linters: lint consistently across a codebase.

Consistent linting helps catch common issues and establishes a high bar for code quality without being unnecessarily prescriptive.

Resource Routing

scripts/setup-lint.sh - Run when generating a .golangci.yml, validating the first lint pass, or producing JSON metadata.
assets/golangci.yml - Use as the v2 golangci-lint baseline for established projects.

Setup Procedure

Create .golangci.yml with scripts/setup-lint.sh or copy assets/golangci.yml
Run golangci-lint run ./...
If errors appear, fix them category by category (formatting first, then vet, then style)
Re-run until clean

After generating .golangci.yml, run golangci-lint config verify --config .golangci.yml to verify the configuration schema before relying on lint results.

Minimum Recommended Linters

These linters catch the most common issues while maintaining a high quality bar:

| Linter | Purpose | |--------|---------| | errcheck | Ensure errors are handled | | goimports | Format code and manage imports | | revive | Common style mistakes (modern replacement for golint) | | govet | Analyze code for common mistakes | | staticcheck | Various static analysis checks |

Note: revive is the modern, faster successor to the now-deprecated golint.

Lint Runner: golangci-lint

Use golangci-lint as your lint runner. See the example .golangci.yml from uber-go/guide.

Example Configuration

Use assets/golangci.yml as the maintained example. It targets golangci-lint v2 (verified with 2.10.1 on 2026-06-19), keeps goimports under formatters, and enables the core linters plus common production additions.

Running

# Install the version this skill's config is verified against
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1

# Run all linters
golangci-lint run

# Run on specific paths
golangci-lint run ./pkg/...

Additional Recommended Linters

Beyond the minimum set, consider these for production projects:

| Linter | Purpose | When to enable | |--------|---------|----------------| | gosec | Security vulnerability detection | Always for services handling user input | | ineffassign | Detect ineffectual assignments | Always — catches dead code | | misspell | Correct common misspellings in comments/strings | Always | | gocyclo | Cyclomatic complexity threshold | When functions exceed ~15 complexity | | exhaustive | Ensure switch covers all enum values | When using iota enums | | bodyclose | Detect unclosed HTTP response bodies | Always for HTTP client code |

Nolint Directives

When suppressing a lint finding, always explain why:

//nolint:errcheck // fire-and-forget logging; error is not actionable
_ = logger.Sync()

Rules:

Use //nolint:lintername — never bare //nolint
Place the comment on the same line as the finding
Include a justification after //

CI/CD Integration

Run golangci-lint run ./... in CI after tests. Pin the golangci-lint version used by CI so local and release behavior do not drift.

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
golangci-lint run --new-from-rev=HEAD~1

Use --new-from-rev to lint only changed code, keeping the feedback loop fast.

Quick Reference

| Task | Command/Action | |------|----------------| | Install golangci-lint | go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1 | | Run linters | golangci-lint run | | Run on path | golangci-lint run ./pkg/... | | Config file | .golangci.yml in project root | | CI integration | Run golangci-lint run in pipeline | | Nolint directives | //nolint:name // reason — never bare //nolint | | CI integration | Use golangci/golangci-lint-action for GitHub Actions | | Pre-commit | golangci-lint run --new-from-rev=HEAD~1 |

Linter Selection Guidelines

| When you need... | Use | |------------------|-----| | Error handling coverage | errcheck | | Import formatting | goimports | | Style consistency | revive | | Bug detection | govet, staticcheck | | All of the above | golangci-lint with config |

Related Skills

Style foundations: See go-style-core when resolving style questions that linters enforce (formatting, nesting, naming)
Code review: See go-code-review when combining linter output with a manual review checklist
Error handling: See go-error-handling when errcheck flags unhandled errors and you need to decide how to handle them
Testing: See go-testing when running linters alongside tests in CI pipelines