golangci-lint

Configuration

The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line and in the config file, the option from command-line will be used. Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file.

To see a list of linters enabled by your configuration use:

golangci-lint linters

Config File

GolangCI-Lint looks for config files in the following paths from the current working directory:

  • .golangci.yml
  • .golangci.yaml
  • .golangci.toml
  • .golangci.json

GolangCI-Lint also searches for config files in all directories from the directory of the first analyzed path up to the root. If no configuration file has been found, GolangCI-Lint will try to find one in your home directory. To see which config file is being used and where it was sourced from run golangci-lint with -v option.

Config options inside the file are identical to command-line options. You can configure specific linters' options only within the config file (not the command-line).

There is a .golangci.reference.yml file with all supported options, their description, and default values. This file is neither a working example nor a recommended configuration, it's just a reference to display all the configuration options.

The configuration file can be validated with the JSON Schema: https://golangci-lint.run/jsonschema/golangci.jsonschema.json

# Options for analysis running.
run:
# See the dedicated "run" documentation section.
option: value
# output configuration options
output:
# See the dedicated "output" documentation section.
option: value
# All available settings of specific linters.
linters-settings:
# See the dedicated "linters-settings" documentation section.
option: value
linters:
# See the dedicated "linters" documentation section.
option: value
issues:
# See the dedicated "issues" documentation section.
option: value
severity:
# See the dedicated "severity" documentation section.
option: value

run configuration

# Options for analysis running.
run:
# Number of CPUs to use when running golangci-lint.
# Default: the number of logical CPUs in the machine
concurrency: 4
# Timeout for analysis, e.g. 30s, 5m.
# Default: 1m
timeout: 5m
# Exit code when at least one issue was found.
# Default: 1
issues-exit-code: 2
# Include test files or not.
# Default: true
tests: false
# List of build tags, all linters use it.
# Default: []
build-tags:
- mytag
# Which dirs to skip: issues from them won't be reported.
# Can use regexp here: `generated.*`, regexp is applied on full path,
# including the path prefix if one is set.
# Default dirs are skipped independently of this option's value (see skip-dirs-use-default).
# "/" will be replaced by current OS file path separator to properly work on Windows.
# Default: []
skip-dirs:
- src/external_libs
- autogenerated_by_my_lib
# Enables skipping of directories:
# - vendor$, third_party$, testdata$, examples$, Godeps$, builtin$
# Default: true
skip-dirs-use-default: false
# Which files to skip: they will be analyzed, but issues from them won't be reported.
# There is no need to include all autogenerated files,
# we confidently recognize autogenerated files.
# If it's not, please let us know.
# "/" will be replaced by current OS file path separator to properly work on Windows.
# Default: []
skip-files:
- ".*\\.my\\.go$"
- lib/bad.go
# If set, we pass it to "go list -mod={option}". From "go help modules":
# If invoked with -mod=readonly, the go command is disallowed from the implicit
# automatic updating of go.mod described above. Instead, it fails when any changes
# to go.mod are needed. This setting is most useful to check that go.mod does
# not need updates, such as in a continuous integration and testing system.
# If invoked with -mod=vendor, the go command assumes that the vendor
# directory holds the correct copies of dependencies and ignores
# the dependency descriptions in go.mod.
#
# Allowed values: readonly|vendor|mod
# Default: ""
modules-download-mode: readonly
# Allow multiple parallel golangci-lint instances running.
# If false, golangci-lint acquires file lock on start.
# Default: false
allow-parallel-runners: true
# Allow multiple golangci-lint instances running, but serialize them around a lock.
# If false, golangci-lint exits with an error if it fails to acquire file lock on start.
# Default: false
allow-serial-runners: true
# Define the Go version limit.
# Mainly related to generics support since go1.18.
# Default: use Go version from the go.mod file, fallback on the env var `GOVERSION`, fallback on 1.17
go: '1.19'
# Show statistics per linter.
# Default: false
show-stats: true

output configuration

# output configuration options
output:
# Format: colored-line-number|line-number|json|colored-tab|tab|checkstyle|code-climate|junit-xml|github-actions|teamcity
#
# Multiple can be specified by separating them by comma, output can be provided
# for each of them by separating format name and path by colon symbol.
# Output path can be either `stdout`, `stderr` or path to the file to write to.
# Example: "checkstyle:report.xml,json:stdout,colored-line-number"
#
# Default: colored-line-number
format: json
# Print lines of code with issue.
# Default: true
print-issued-lines: false
# Print linter name in the end of issue text.
# Default: true
print-linter-name: false
# Make issues output unique by line.
# Default: true
uniq-by-line: false
# Add a prefix to the output file references.
# Default: ""
path-prefix: ""
# Sort results by: filepath, line and column.
# Default: false
sort-results: true

linters-settings configuration

See the dedicated linters-settings documentation section.

linters configuration

linters:
# Disable all linters.
# Default: false
disable-all: true
# Enable specific linter
# https://golangci-lint.run/usage/linters/#enabled-by-default
enable:
- asasalint
- asciicheck
- bidichk
- bodyclose
- containedctx
- contextcheck
- cyclop
- deadcode
- decorder
- depguard
- dogsled
- dupl
- dupword
- durationcheck
- errcheck
- errchkjson
- errname
- errorlint
- execinquery
- exhaustive
- exhaustivestruct
- exhaustruct
- exportloopref
- forbidigo
- forcetypeassert
- funlen
- gci
- ginkgolinter
- gocheckcompilerdirectives
- gochecknoglobals
- gochecknoinits
- gochecksumtype
- gocognit
- goconst
- gocritic
- gocyclo
- godot
- godox
- goerr113
- gofmt
- gofumpt
- goheader
- goimports
- golint
- gomnd
- gomoddirectives
- gomodguard
- goprintffuncname
- gosec
- gosimple
- gosmopolitan
- govet
- grouper
- ifshort
- importas
- inamedparam
- ineffassign
- interfacebloat
- interfacer
- ireturn
- lll
- loggercheck
- maintidx
- makezero
- maligned
- mirror
- misspell
- musttag
- nakedret
- nestif
- nilerr
- nilnil
- nlreturn
- noctx
- nolintlint
- nonamedreturns
- nosnakecase
- nosprintfhostport
- paralleltest
- perfsprint
- prealloc
- predeclared
- promlinter
- protogetter
- reassign
- revive
- rowserrcheck
- scopelint
- sloglint
- spancheck
- sqlclosecheck
- staticcheck
- structcheck
- stylecheck
- tagalign
- tagliatelle
- tenv
- testableexamples
- testifylint
- testpackage
- thelper
- tparallel
- typecheck
- unconvert
- unparam
- unused
- usestdlibvars
- varcheck
- varnamelen
- wastedassign
- whitespace
- wrapcheck
- wsl
- zerologlint
# Enable all available linters.
# Default: false
enable-all: true
# Disable specific linter
# https://golangci-lint.run/usage/linters/#disabled-by-default
disable:
- asasalint
- asciicheck
- bidichk
- bodyclose
- containedctx
- contextcheck
- cyclop
- deadcode
- decorder
- depguard
- dogsled
- dupl
- dupword
- durationcheck
- errcheck
- errchkjson
- errname
- errorlint
- execinquery
- exhaustive
- exhaustivestruct
- exhaustruct
- exportloopref
- forbidigo
- forcetypeassert
- funlen
- gci
- ginkgolinter
- gocheckcompilerdirectives
- gochecknoglobals
- gochecknoinits
- gochecksumtype
- gocognit
- goconst
- gocritic
- gocyclo
- godot
- godox
- goerr113
- gofmt
- gofumpt
- goheader
- goimports
- golint
- gomnd
- gomoddirectives
- gomodguard
- goprintffuncname
- gosec
- gosimple
- gosmopolitan
- govet
- grouper
- ifshort
- importas
- inamedparam
- ineffassign
- interfacebloat
- interfacer
- ireturn
- lll
- loggercheck
- maintidx
- makezero
- maligned
- mirror
- misspell
- musttag
- nakedret
- nestif
- nilerr
- nilnil
- nlreturn
- noctx
- nolintlint
- nonamedreturns
- nosnakecase
- nosprintfhostport
- paralleltest
- perfsprint
- prealloc
- predeclared
- promlinter
- protogetter
- reassign
- revive
- rowserrcheck
- scopelint
- sloglint
- spancheck
- sqlclosecheck
- staticcheck
- structcheck
- stylecheck
- tagalign
- tagliatelle
- tenv
- testableexamples
- testifylint
- testpackage
- thelper
- tparallel
- typecheck
- unconvert
- unparam
- unused
- usestdlibvars
- varcheck
- varnamelen
- wastedassign
- whitespace
- wrapcheck
- wsl
- zerologlint
# Enable presets.
# https://golangci-lint.run/usage/linters
# Default: []
presets:
- bugs
- comment
- complexity
- error
- format
- import
- metalinter
- module
- performance
- sql
- style
- test
- unused
# Enable only fast linters from enabled linters set (first run won't be fast)
# Default: false
fast: true

issues configuration

issues:
# List of regexps of issue texts to exclude.
#
# But independently of this option we use default exclude patterns,
# it can be disabled by `exclude-use-default: false`.
# To list all excluded by default patterns execute `golangci-lint run --help`
#
# Default: https://golangci-lint.run/usage/false-positives/#default-exclusions
exclude:
- abcdef
# Excluding configuration per-path, per-linter, per-text and per-source
exclude-rules:
# Exclude some linters from running on tests files.
- path: _test\.go
linters:
- gocyclo
- errcheck
- dupl
- gosec
# Run some linter only for test files by excluding its issues for everything else.
- path-except: _test\.go
linters:
- forbidigo
# Exclude known linters from partially hard-vendored code,
# which is impossible to exclude via `nolint` comments.
# `/` will be replaced by current OS file path separator to properly work on Windows.
- path: internal/hmac/
text: "weak cryptographic primitive"
linters:
- gosec
# Exclude some `staticcheck` messages.
- linters:
- staticcheck
text: "SA9003:"
# Exclude `lll` issues for long lines with `go:generate`.
- linters:
- lll
source: "^//go:generate "
# Independently of option `exclude` we use default exclude patterns,
# it can be disabled by this option.
# To list all excluded by default patterns execute `golangci-lint run --help`.
# Default: true
exclude-use-default: false
# If set to true exclude and exclude-rules regular expressions become case-sensitive.
# Default: false
exclude-case-sensitive: false
# The list of ids of default excludes to include or disable.
# https://golangci-lint.run/usage/false-positives/#default-exclusions
# Default: []
include:
- EXC0001
- EXC0002
- EXC0003
- EXC0004
- EXC0005
- EXC0006
- EXC0007
- EXC0008
- EXC0009
- EXC0010
- EXC0011
- EXC0012
- EXC0013
- EXC0014
- EXC0015
# Maximum issues count per one linter.
# Set to 0 to disable.
# Default: 50
max-issues-per-linter: 0
# Maximum count of issues with the same text.
# Set to 0 to disable.
# Default: 3
max-same-issues: 0
# Show only new issues: if there are unstaged changes or untracked files,
# only those changes are analyzed, else only changes in HEAD~ are analyzed.
# It's a super-useful option for integration of golangci-lint into existing large codebase.
# It's not practical to fix all existing issues at the moment of integration:
# much better don't allow issues in new code.
#
# Default: false
new: true
# Show only new issues created after git revision `REV`.
# Default: ""
new-from-rev: HEAD
# Show only new issues created in git patch with set file path.
# Default: ""
new-from-patch: path/to/patch/file
# Fix found issues (if it's supported by the linter).
# Default: false
fix: true
# Show issues in any part of update files (requires new-from-rev or new-from-patch).
# Default: false
whole-files: true

severity configuration

severity:
# Set the default severity for issues.
#
# If severity rules are defined and the issues do not match or no severity is provided to the rule
# this will be the default severity applied.
# Severities should match the supported severity names of the selected out format.
# - Code climate: https://docs.codeclimate.com/docs/issues#issue-severity
# - Checkstyle: https://checkstyle.sourceforge.io/property_types.html#SeverityLevel
# - GitHub: https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-error-message
# - TeamCity: https://www.jetbrains.com/help/teamcity/service-messages.html#Inspection+Instance
#
# Default: ""
default-severity: error
# If set to true `severity-rules` regular expressions become case-sensitive.
# Default: false
case-sensitive: true
# When a list of severity rules are provided, severity information will be added to lint issues.
# Severity rules have the same filtering capability as exclude rules
# except you are allowed to specify one matcher per severity rule.
# Only affects out formats that support setting severity information.
#
# Default: []
rules:
- linters:
- dupl
severity: info

Command-Line Options

golangci-lint run -h
Usage:
golangci-lint run [flags]
Flags:
-c, --config PATH Read config from file path PATH
--no-config Don't read config file
--out-format string Format of output: colored-line-number|line-number|json|tab|checkstyle|code-climate|html|junit-xml|github-actions|teamcity (default "colored-line-number")
--print-issued-lines Print lines of code with issue (default true)
--print-linter-name Print linter name in issue line (default true)
--uniq-by-line Make issues output unique by line (default true)
--sort-results Sort linter results
--path-prefix string Path prefix to add to output
--modules-download-mode string Modules download mode. If not empty, passed as -mod=<mode> to go tools
--issues-exit-code int Exit code when issues were found (default 1)
--go string Targeted Go version
--build-tags strings Build tags
--timeout duration Timeout for total work (default 1m0s)
--tests Analyze tests (*_test.go) (default true)
--print-resources-usage Print avg and max memory usage of golangci-lint and total time
--skip-dirs strings Regexps of directories to skip
--skip-dirs-use-default Use or not use default excluded directories:
- (^|/)vendor($|/)
- (^|/)third_party($|/)
- (^|/)testdata($|/)
- (^|/)examples($|/)
- (^|/)Godeps($|/)
- (^|/)builtin($|/)
(default true)
--skip-files strings Regexps of files to skip
--allow-parallel-runners Allow multiple parallel golangci-lint instances running. If false (default) - golangci-lint acquires file lock on start.
--allow-serial-runners Allow multiple golangci-lint instances running, but serialize them around a lock. If false (default) - golangci-lint exits with an error if it fails to acquire file lock on start.
--show-stats Show statistics per linter
-D, --disable strings Disable specific linter
--disable-all Disable all linters
-E, --enable strings Enable specific linter
--enable-all Enable all linters
--fast Enable only fast linters from enabled linters set (first run won't be fast)
-p, --presets strings Enable presets (bugs|comment|complexity|error|format|import|metalinter|module|performance|sql|style|test|unused) of linters. Run 'golangci-lint help linters' to see them. This option implies option --disable-all
-e, --exclude strings Exclude issue by regexp
--exclude-use-default Use or not use default excludes:
# EXC0001 errcheck: Almost all programs ignore errors on these functions and in most cases it's ok
- Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*print(f|ln)?|os\.(Un)?Setenv). is not checked
# EXC0002 golint: Annoying issue about not having a comment. The rare codebase has such comments
- (comment on exported (method|function|type|const)|should have( a package)? comment|comment should be of the form)
# EXC0003 golint: False positive when tests are defined in package 'test'
- func name will be used as test\.Test.* by other packages, and that stutters; consider calling this
# EXC0004 govet: Common false positives
- (possible misuse of unsafe.Pointer|should have signature)
# EXC0005 staticcheck: Developers tend to write in C-style with an explicit 'break' in a 'switch', so it's ok to ignore
- ineffective break statement. Did you mean to break out of the outer loop
# EXC0006 gosec: Too many false-positives on 'unsafe' usage
- Use of unsafe calls should be audited
# EXC0007 gosec: Too many false-positives for parametrized shell calls
- Subprocess launch(ed with variable|ing should be audited)
# EXC0008 gosec: Duplicated errcheck checks
- (G104)
# EXC0009 gosec: Too many issues in popular repos
- (Expect directory permissions to be 0750 or less|Expect file permissions to be 0600 or less)
# EXC0010 gosec: False positive is triggered by 'src, err := ioutil.ReadFile(filename)'
- Potential file inclusion via variable
# EXC0011 stylecheck: Annoying issue about not having a comment. The rare codebase has such comments
- (comment on exported (method|function|type|const)|should have( a package)? comment|comment should be of the form)
# EXC0012 revive: Annoying issue about not having a comment. The rare codebase has such comments
- exported (.+) should have comment( \(or a comment on this block\))? or be unexported
# EXC0013 revive: Annoying issue about not having a comment. The rare codebase has such comments
- package comment should be of the form "(.+)...
# EXC0014 revive: Annoying issue about not having a comment. The rare codebase has such comments
- comment on exported (.+) should be of the form "(.+)..."
# EXC0015 revive: Annoying issue about not having a comment. The rare codebase has such comments
- should have a package comment
(default true)
--exclude-case-sensitive If set to true exclude and exclude rules regular expressions are case sensitive
--max-issues-per-linter int Maximum issues count per one linter. Set to 0 to disable (default 50)
--max-same-issues int Maximum count of issues with the same text. Set to 0 to disable (default 3)
-n, --new Show only new issues: if there are unstaged changes or untracked files, only those changes are analyzed, else only changes in HEAD~ are analyzed.
It's a super-useful option for integration of golangci-lint into existing large codebase.
It's not practical to fix all existing issues at the moment of integration: much better to not allow issues in new code.
For CI setups, prefer --new-from-rev=HEAD~, as --new can skip linting the current patch if any scripts generate unstaged files before golangci-lint runs.
--new-from-rev REV Show only new issues created after git revision REV
--new-from-patch PATH Show only new issues created in git patch with file path PATH
--whole-files Show issues in any part of update files (requires new-from-rev or new-from-patch)
--fix Fix found issues (if it's supported by the linter)
-h, --help help for run
Global Flags:
--color string Use color when printing; can be 'always', 'auto', or 'never' (default "auto")
-j, --concurrency int Number of CPUs to use (Default: number of logical CPUs) (default 8)
--cpu-profile-path string Path to CPU profile output file
--mem-profile-path string Path to memory profile output file
--trace-path string Path to trace output file
-v, --verbose Verbose output
--version Print version

When the --cpu-profile-path or --mem-profile-path arguments are specified, golangci-lint writes runtime profiling data in the format expected by the pprof visualization tool.

When the --trace-path argument is specified, golangci-lint writes runtime tracing data in the format expected by the go tool trace command and visualization tool.

Cache

GolangCI-Lint stores its cache in the subdirectory golangci-lint inside the default user cache directory.

You can override the default cache directory with the environment variable GOLANGCI_LINT_CACHE; the path must be absolute.

Edit this page on GitHub