golangci-lint

Configuration

Table of Contents

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 a neither a working example nor recommended configuration, it's just a reference to display all the configuration options.

# 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:
  # The default concurrency value is the number of available CPU.
  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 value is empty list,
  # but 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.
  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.
  # Default value is empty list,
  # but 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.
  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
  # By default, it isn't set.
  modules-download-mode: readonly
  # Allow multiple parallel golangci-lint instances running.
  # If false (default) - golangci-lint acquires file lock on start.
  allow-parallel-runners: false
  # 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.18
  go: '1.19'

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 is no prefix.
  path-prefix: ""
  # Sort results by: filepath, line and column.
  sort-results: false

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
    - gocognit
    - goconst
    - gocritic
    - gocyclo
    - godot
    - godox
    - goerr113
    - gofmt
    - gofumpt
    - goheader
    - goimports
    - golint
    - gomnd
    - gomoddirectives
    - gomodguard
    - goprintffuncname
    - gosec
    - gosimple
    - gosmopolitan
    - govet
    - grouper
    - ifshort
    - importas
    - ineffassign
    - interfacebloat
    - interfacer
    - ireturn
    - lll
    - loggercheck
    - maintidx
    - makezero
    - maligned
    - misspell
    - musttag
    - nakedret
    - nestif
    - nilerr
    - nilnil
    - nlreturn
    - noctx
    - nolintlint
    - nonamedreturns
    - nosnakecase
    - nosprintfhostport
    - paralleltest
    - prealloc
    - predeclared
    - promlinter
    - reassign
    - revive
    - rowserrcheck
    - scopelint
    - sqlclosecheck
    - staticcheck
    - structcheck
    - stylecheck
    - tagalign
    - tagliatelle
    - tenv
    - testableexamples
    - 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
    - gocognit
    - goconst
    - gocritic
    - gocyclo
    - godot
    - godox
    - goerr113
    - gofmt
    - gofumpt
    - goheader
    - goimports
    - golint
    - gomnd
    - gomoddirectives
    - gomodguard
    - goprintffuncname
    - gosec
    - gosimple
    - gosmopolitan
    - govet
    - grouper
    - ifshort
    - importas
    - ineffassign
    - interfacebloat
    - interfacer
    - ireturn
    - lll
    - loggercheck
    - maintidx
    - makezero
    - maligned
    - misspell
    - musttag
    - nakedret
    - nestif
    - nilerr
    - nilnil
    - nlreturn
    - noctx
    - nolintlint
    - nonamedreturns
    - nosnakecase
    - nosprintfhostport
    - paralleltest
    - prealloc
    - predeclared
    - promlinter
    - reassign
    - revive
    - rowserrcheck
    - scopelint
    - sqlclosecheck
    - staticcheck
    - structcheck
    - stylecheck
    - tagalign
    - tagliatelle
    - tenv
    - testableexamples
    - testpackage
    - thelper
    - tparallel
    - typecheck
    - unconvert
    - unparam
    - unused
    - usestdlibvars
    - varcheck
    - varnamelen
    - wastedassign
    - whitespace
    - wrapcheck
    - wsl
    - zerologlint
  # Enable presets.
  # https://golangci-lint.run/usage/linters
  presets:
    - bugs
    - comment
    - complexity
    - error
    - format
    - import
    - metalinter
    - module
    - performance
    - sql
    - style
    - test
    - unused
  # Run 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`.
  new-from-rev: HEAD
  # Show only new issues created in git patch with set file path.
  new-from-patch: path/to/patch/file
  # Fix found issues (if it's supported by the linter).
  fix: 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 value is an empty string.
  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:
      --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
  -c, --config PATH                    Read config from file path PATH
      --no-config                      Don't read config
      --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.
  -E, --enable strings                 Enable specific linter
  -D, --disable strings                Disable specific linter
      --enable-all                     Enable all linters
      --disable-all                    Disable all linters
  -p, --presets strings                Enable presets (bugs|comment|complexity|error|format|import|metalinter|module|performance|sql|style|test|unused) of linters. Run 'golangci-lint linters' to see them. This option implies option --disable-all
      --fast                           Run only fast linters from enabled linters set (first run won't be fast)
  -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|G307)
                                       
                                         # 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           Concurrency (default NumCPU) (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

Prev

Linters

Next

False Positives