golangci-lint — Specification¶

Focus: Precise reference for the golangci-lint driver — synopsis, subcommands, flags, config schema, environment, exit codes, and behavioral guarantees.

Sources: - golangci-lint --help, golangci-lint <cmd> --help - Project docs: https://golangci-lint.run - Source: https://github.com/golangci/golangci-lint

This document tracks v1.59+ behavior with notes where v2 differs.

1. Synopsis¶

golangci-lint <command> [flags] [path...]
golangci-lint run    [flags] [path...]

The default subject is the current Go module. path... accepts Go package patterns (./..., ./internal/api/...) or directories.

2. Top-level commands¶

3. Key run flags¶

4. .golangci.yml structure¶

Top-level keys (v1 schema; v2 reorganizes — see §9):

run:                 # execution
  timeout: 5m
  concurrency: 4
  tests: true
  build-tags: [integration]
  go: "1.22"

linters:             # which linters fire
  disable-all: true
  enable: [govet, staticcheck, errcheck]
  presets: [bugs]

linters-settings:    # per-linter configuration
  gocyclo: { min-complexity: 15 }
  revive:
    rules:
      - name: exported

issues:              # filter the findings stream
  exclude-dirs: [vendor, gen]
  exclude-files: [".*\\.pb\\.go$"]
  exclude-rules:
    - path: _test\.go
      linters: [errcheck, gosec]
  exclude-use-default: true
  max-issues-per-linter: 50
  max-same-issues: 3
  new-from-rev: ""    # equivalent to --new-from-rev

severity:            # map findings to severities
  default-severity: error
  rules:
    - severity: warning
      linters: [revive, gocritic]

output:              # presentation
  formats:
    - format: colored-line-number
  print-issued-lines: true
  print-linter-name: true
  sort-results: true

Top-level service: is used by the hosted golangci.com integration and is irrelevant for self-hosted CI.

5. Linter selection precedence¶

From lowest to highest priority:

1. Default enabled set.
2. linters.disable-all / linters.enable-all.
3. linters.presets.
4. linters.enable / linters.disable.
5. Command-line --disable-all, --enable, --disable.
6. --enable-only (replaces everything above).

--enable-only is the kill switch: use it when you need to ignore all configuration and run exactly one linter.

6. Output formats¶

Multiple formats at once, each optionally to a path:

golangci-lint run --out-format=colored-line-number,json:report.json,checkstyle:report.xml

7. Exit codes¶

Always check the exit code; do not parse stderr to determine success.

8. Environment variables¶

9. v1 → v2 schema notes¶

Migrate with golangci-lint migrate (in-place) or --dry-run.

10. Behavioral guarantees¶

• Single load. Packages are loaded once per run; go/analysis analyzers share the result.
• Deterministic with a pinned version. Same version + same Go + same config + same source → same findings.
• Cache safety. Cache entries are keyed on tool/Go versions, enabled linter set, settings, and source hashes; stale entries are not returned.
• Faithful exit code. Returns non-zero when issues are found unless --issues-exit-code=0.
• Suggested fixes are atomic per file. --fix writes to a temp file and renames; partial writes do not occur.

11. Non-goals / limitations¶

• Not a security scanner on its own (use gosec as one of its linters).
• Not a code formatter (it can apply formatter linters' fixes, but pick one of gofmt/gofumpt).
• Not an IDE protocol; for editor integration use the upstream linters' LSPs or golangci-lint's editor plugins.
• Not a go vet replacement at the language level — go vet ships with the Go toolchain and runs as go test always.
• Not reproducible across versions; pin the version.

12. Related references¶

• Project site: https://golangci-lint.run
• Configuration reference: https://golangci-lint.run/usage/configuration/
• Linters list: https://golangci-lint.run/usage/linters/
• v2 migration guide: https://golangci-lint.run/product/migration-guide/
• go/analysis: https://pkg.go.dev/golang.org/x/tools/go/analysis