golangci-lint

Migration guide

Command migrate

You can use golangci-lint to migrate your configuration with the migrate command:

golangci-lint migrate

Be aware that comments inside a configuration file are not migrated. You need to add them manually after the migration.

Deprecated options from v1 or unknown fields are not migrated.

The migration file format is based on the extension of the configuration file. The format can be overridden by using the --format flag:

golangci-lint migrate --format json

Before the migration, the previous configuration file is copied and saved to a file named <config_file_name>.bck.<config_file_extension>.

By default, before the migration process, the configuration file is validated against the JSON Schema of configuration v1. If you want to skip this validation, you can use the --skip-validation flag:

golangci-lint migrate --skip-validation

The migrate command enforces the following default values:

  • run.timeout: the existing value is ignored because, in v2, there is no timeout by default.
  • issues.show-stats: the existing value is ignored because, in v2, stats are enabled by default.
  • run.concurrency: if the existing value was 0, it is removed as 0 is the new default.
  • run.relative-path-mode: if the existing value was cfg, it is removed as cfg is the new default.

issues.exclude-generated has a new default value (v1 lax, v2 strict), so this field will be added during the migration to maintain the previous behavior.

issues.exclude-dirs-use-default has been removed, so it is converted to linters.exclusions.paths and, if needed, formatters.exclusions.paths.

Other fields explicitly defined in the configuration file are migrated even if the value is the same as the default value.

Migrate configuration file from v1 to v2
Usage:
golangci-lint migrate [flags]
Flags:
-c, --config PATH Read config from file path PATH
--no-config Don't read config file
--format string Output file format.
By default, the format of the input configuration file is used.
It can be 'yml', 'yaml', 'toml', or 'json'.
--skip-validation Skip validation of the configuration file against the JSON Schema for v1.
Global Flags:
-h, --help Help for a command

Changes

linters

linters.disable-all

This property has been replaced with linters.default: none.

v1
linters:
disable-all: true
v2
linters:
default: none

linters.enable-all

This property has been replaced with linters.default: all.

v1
linters:
enable-all: true
v2
linters:
default: all

linters.enable[].<formatter_name>

The linters gci, gofmt, gofumpt, and goimports have been moved to the formatters section.

v1
linters:
enable:
- gci
- gofmt
- gofumpt
- goimports
v2
formatters:
enable:
- gci
- gofmt
- gofumpt
- goimports

linters.enable[].{stylecheck,gosimple,staticcheck}

The linters stylecheck, gosimple, and staticcheck has been merged inside the staticcheck.

v1
linters:
enable:
- gosimple
- staticcheck
- stylecheck
v2
linters:
enable:
- staticcheck

linters.fast

This property has been removed.

There are 2 new options (they are not strictly equivalent to the previous option):

  1. linters.default: fast: set all "fast" linters as the default set of linters.
    linters:
    default: fast
  2. --fast-only: filters all enabled linters to keep only "fast" linters.

linters.presets

This property have been removed.

v1

Presets:

  • bugs:
    • asasalint
    • asciicheck
    • bidichk
    • bodyclose
    • contextcheck
    • durationcheck
    • errcheck
    • errchkjson
    • errorlint
    • exhaustive
    • gocheckcompilerdirectives
    • gochecksumtype
    • gosec
    • gosmopolitan
    • govet
    • loggercheck
    • makezero
    • musttag
    • nilerr
    • nilnesserr
    • noctx
    • protogetter
    • reassign
    • recvcheck
    • rowserrcheck
    • spancheck
    • sqlclosecheck
    • staticcheck
    • testifylint
    • zerologlint
  • comment:
    • dupword
    • godot
    • godox
    • misspell
  • complexity:
    • cyclop
    • funlen
    • gocognit
    • gocyclo
    • maintidx
    • nestif
  • error:
    • err113
    • errcheck
    • errorlint
    • wrapcheck
  • format:
    • gci
    • gofmt
    • gofumpt
    • goimports
  • import:
    • depguard
    • gci
    • goimports
    • gomodguard
  • metalinter:
    • gocritic
    • govet
    • revive
    • staticcheck
  • module:
    • depguard
    • gomoddirectives
    • gomodguard
  • performance:
    • bodyclose
    • fatcontext
    • noctx
    • perfsprint
    • prealloc
  • sql:
    • rowserrcheck
    • sqlclosecheck
  • style:
    • asciicheck
    • canonicalheader
    • containedctx
    • copyloopvar
    • decorder
    • depguard
    • dogsled
    • dupl
    • err113
    • errname
    • exhaustruct
    • exptostd
    • forbidigo
    • forcetypeassert
    • ginkgolinter
    • gochecknoglobals
    • gochecknoinits
    • goconst
    • gocritic
    • godot
    • godox
    • goheader
    • gomoddirectives
    • gomodguard
    • goprintffuncname
    • gosimple
    • grouper
    • iface
    • importas
    • inamedparam
    • interfacebloat
    • intrange
    • ireturn
    • lll
    • loggercheck
    • makezero
    • mirror
    • misspell
    • mnd
    • musttag
    • nakedret
    • nilnil
    • nlreturn
    • nolintlint
    • nonamedreturns
    • nosprintfhostport
    • paralleltest
    • predeclared
    • promlinter
    • revive
    • sloglint
    • stylecheck
    • tagalign
    • tagliatelle
    • testpackage
    • tparallel
    • unconvert
    • usestdlibvars
    • varnamelen
    • wastedassign
    • whitespace
    • wrapcheck
    • wsl
  • test:
    • exhaustruct
    • paralleltest
    • testableexamples
    • testifylint
    • testpackage
    • thelper
    • tparallel
    • usetesting
  • unused:
    • ineffassign
    • unparam
    • unused
v2
# Removed

typecheck

This typecheck is not a linter, so it cannot be enabled or disabled:

Deprecated Linters

The following deprecated linters have been removed:

  • deadcode
  • execinquery
  • exhaustivestruct
  • exportloopref
  • golint
  • ifshort
  • interfacer
  • maligned
  • nosnakecase
  • scopelint
  • structcheck
  • tenv
  • varcheck

Alternative Linter Names

The alternative linters has been removed.

Alt Name v1Name v2
gasgosec
goerr113err113
gomndmnd
logrlintloggercheck
megacheckstaticcheck
vetgovet
vetshadowgovet
v1
linters:
enable:
- gas
- goerr113
- gomnd
- logrlint
- megacheck
- vet
- vetshadow
v2
linters:
enable:
- gosec
- err113
- mnd
- loggercheck
- staticcheck
- govet

linters-settings

The linters-settings section has been split into linters.settings and formatters.settings.

Settings for gci, gofmt, gofumpt, and goimports are moved to the formatters.settings section.

v1
linters-settings:
govet:
enable-all: true
gofmt:
simplify: false
v2
linters:
settings:
govet:
enable-all: true
formatters:
settings:
gofmt:
simplify: false

linters-settings.asasalint.ignore-test

This option has been removed.

To ignore test files, use linters.exclusions.rules.

v1
linters-settings:
asasalint:
ignore-test: true
v2
linters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- asasalint

linters-settings.copyloopvar.ignore-alias

This option has been deprecated since v1.58.0 and has been replaced with linters.settings.copyloopvar.check-alias.

v1
linters-settings:
copyloopvar:
ignore-alias: false
v2
linters:
settings:
copyloopvar:
check-alias: true

linters-settings.cyclop.skip-tests

This option has been removed.

To ignore test files, use linters.exclusions.rules.

v1
linters-settings:
cyclop:
skip-test: true
v2
linters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- cyclop

linters-settings.errcheck.exclude

This option has been deprecated since v1.42.0 and has been removed.

To exclude functions, use linters.settings.errcheck.exclude-functions instead.

v1
linters-settings:
errcheck:
exclude: ./errcheck_excludes.txt
v2
linters:
settings:
errcheck:
exclude-functions:
- io.ReadFile
- io.Copy(*bytes.Buffer)
- io.Copy(os.Stdout)

linters-settings.errcheck.ignore

This option has been deprecated since v1.13.0 and has been removed.

To exclude functions, use linters.settings.errcheck.exclude-functions instead.

v1
linters-settings:
errcheck:
ignore: 'io:.*'
v2
linters:
settings:
errcheck:
exclude-functions:
- 'io.ReadFile'
- 'io.Copy(*bytes.Buffer)'
- 'io.Copy(os.Stdout)'

linters-settings.exhaustive.check-generated

This option has been removed.

To analyze generated files, use linters.exclusions.generated.

v1
linters-settings:
exhaustive:
check-generated: true
v2
linters:
exclusions:
generated: disable

linters-settings.forbidigo.forbid[].p

This field has been replaced with linters-settings.forbidigo.forbid[].pattern.

v1
linters-settings:
forbidigo:
forbid:
- p: '^fmt\.Print.*$'
msg: Do not commit print statements.
v2
linters:
settings:
forbidigo:
forbid:
- pattern: '^fmt\.Print.*$'
msg: Do not commit print statements.

linters-settings.forbidigo.forbid[]<pattern>

The pattern has become mandatory for the forbid field.

v1
linters-settings:
forbidigo:
forbid:
- '^print(ln)?$'
- '^spew\.(ConfigState\.)?Dump$'
v2
linters:
settings:
forbidigo:
forbid:
- pattern: '^print(ln)?$'
- pattern: '^spew\.(ConfigState\.)?Dump$'

linters-settings.gci.local-prefixes

This option has been deprecated since v1.44.0 and has been removed.

Use linters.settings.gci.sections instead.

v1
linters-settings:
gci:
local-prefixes: 'github.com/example/pkg'
v2
linters:
settings:
gci:
sections:
- standard
- default
- prefix(github.com/example/pkg)

linters-settings.gci.skip-generated

This option has been removed.

To analyze generated files, use linters.exclusions.generated.

v1
linters:
settings:
gci:
skip-generated: false
v2
linters:
exclusions:
generated: disable

linters-settings.goconst.ignore-tests

This option has been removed.

To ignore test files, use linters.exclusions.rules.

v1
linters-settings:
goconst:
ignore-tests: true
v2
linters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- goconst

linters-settings.gocritic.settings.ruleguard.rules

The special variable ${configDir} has been replaced with ${base-path}.

v1
linters-settings:
gocritic:
settings:
ruleguard:
rules: '${configDir}/ruleguard/rules-*.go'
v2
linters:
settings:
gocritic:
settings:
ruleguard:
rules: '${base-path}/ruleguard/rules-*.go'

linters-settings.govet.check-shadowing

This option has been deprecated since v1.57.0 and has been removed.

Use linters.settings.govet.enable: shadow instead.

v1
linters-settings:
govet:
check-shadowing: true
v2
linters:
settings:
govet:
enable:
- shadow

linters-settings.misspell.ignore-words

This option has been replaced with linters.settings.misspell.ignore-rules.

v1
linters-settings:
misspell:
ignore-words:
- foo
v2
linters:
settings:
misspell:
ignore-rules:
- foo

linters-settings.predeclared.ignore

This string option has been replaced with the slice option with the same name.

v1
linters-settings:
predeclared:
ignore: "new,int"
v2
linters:
settings:
predeclared:
ignore:
- new
- int

linters-settings.predeclared.q

This option has been replaced with linters.settings.predeclared.qualified-name.

v1
linters-settings:
predeclared:
q: true
v2
linters:
settings:
predeclared:
qualified-name: true

linters-settings.revive.ignore-generated-header

This option has been removed.

Use linters.exclusions.generated instead.

v1
linters-settings:
revive:
ignore-generated-header: true
v2
linters:
exclusions:
generated: strict

linters-settings.sloglint.context-only

This option has been deprecated since v1.58.0 and has been replaced with linters.settings.sloglint.context.

v1
linters-settings:
sloglint:
context-only: true
v2
linters:
settings:
sloglint:
context: all

linters-settings.staticcheck.go

This option has been deprecated since v1.47.0 and has been removed.

Use run.go instead.

v1
linters-settings:
staticcheck:
go: '1.22'
v2
run:
go: '1.22'

linters-settings.unused.exported-is-used

This option has been deprecated since v1.60.0 and has been removed.

v1
linters-settings:
unused:
exported-is-used: true
v2
# Removed

linters-settings.usestdlibvars.os-dev-null

This option has been deprecated since v1.51.0 and has been removed.

v1
linters-settings:
usestdlibvars:
os-dev-null: true
v2
# Removed

linters-settings.usestdlibvars.syslog-priority

This option has been deprecated since v1.51.0 and has been removed.

v1
linters-settings:
usestdlibvars:
syslog-priority: true
v2
# Removed

linters-settings.wrapcheck.ignoreInterfaceRegexps

This option has been renamed to linters.settings.wrapcheck.ignore-interface-regexps.

v1
linters-settings:
wrapcheck:
ignoreInterfaceRegexps:
- '^(?i)c(?-i)ach(ing|e)'
v2
linters:
settings:
wrapcheck:
ignore-interface-regexps:
- '^(?i)c(?-i)ach(ing|e)'

linters-settings.wrapcheck.ignorePackageGlobs

This option has been renamed to linters.settings.wrapcheck.ignore-package-globs.

v1
linters-settings:
wrapcheck:
ignorePackageGlobs:
- 'encoding/*'
v2
linters:
settings:
wrapcheck:
ignore-package-globs:
- 'encoding/*'

linters-settings.wrapcheck.ignoreSigRegexps

This option has been renamed to linters.settings.wrapcheck.ignore-sig-regexps.

v1
linters-settings:
wrapcheck:
ignoreSigRegexps:
- '\.New.*Error\('
v2
linters:
settings:
wrapcheck:
ignore-sig-regexps:
- '\.New.*Error\('

linters-settings.wrapcheck.ignoreSigs

This option has been renamed to linters.settings.wrapcheck.ignore-sigs.

v1
linters-settings:
wrapcheck:
ignoreSigs:
- '.Errorf('
v2
linters:
settings:
wrapcheck:
ignore-sigs:
- '.Errorf('

issues

issues.exclude-case-sensitive

This property has been removed.

issues.exclude, issues.exclude-rules.text, and issues.exclude-rules.source are case-sensitive by default.

To ignore case, use (?i) at the beginning of a regex syntax.

v1
issues:
exclude-case-sensitive: false
exclude:
- 'abcdef'
v2
linters:
exclusions:
rules:
- path: '(.+)\.go$'
text: (?i)abcdef

issues.exclude-dirs-use-default

This property has been removed.

Use linters.exclusions.paths and formatters.exclusions.paths to exclude directories.

v1
issues:
exclude-dirs-use-default: true
v2
linters:
exclusions:
paths:
- third_party$
- builtin$
- examples$

issues.exclude-dirs

This property has been replaced with linters.exclusions.paths and formatters.exclusions.paths.

v1
issues:
exclude-dirs:
- src/external_libs
- autogenerated_by_my_lib
v2
linters:
exclusions:
paths:
- src/external_libs
- autogenerated_by_my_lib

issues.exclude-files

This property has been replaced with linters.exclusions.paths and formatters.exclusions.paths.

v1
issues:
exclude-files:
- '.*\.my\.go$'
- lib/bad.go
v2
linters:
exclusions:
paths:
- '.*\.my\.go$'
- lib/bad.go

issues.exclude-generated-strict

This property has been deprecated since v1.59.0 and has been replaced with linters.exclusions.generated: strict.

v1
linters:
exclude-generated-strict: true
v2
linters:
exclusions:
generated: strict

issues.exclude-generated

This property has been replaced with linters.exclusions.generated.

v1
linters:
exclude-generated: lax
v2
linters:
exclusions:
generated: lax

issues.exclude-rules

This property has been replaced with linters.exclusions.rules.

v1
issues:
exclude-rules:
- path: '_test\.go'
linters:
- gocyclo
- errcheck
- dupl
- gosec
- path-except: '_test\.go'
linters:
- staticcheck
- path: internal/hmac/
text: "weak cryptographic primitive"
linters:
- gosec
- linters:
- staticcheck
text: "SA9003:"
- linters:
- err113
source: "foo"
v2
linters:
exclusions:
rules:
- path: '_test\.go'
linters:
- dupl
- errcheck
- gocyclo
- gosec
- path-except: '_test\.go'
linters:
- staticcheck
- path: internal/hmac/
text: weak cryptographic primitive
linters:
- gosec
- text: 'SA9003:'
linters:
- staticcheck
- source: foo
linters:
- err113

issues.exclude-use-default

This property has been replaced with linters.exclusions.presets.

v1
issues:
exclude-use-default: true
v2
linters:
exclusions:
presets:
- comments
- common-false-positives
- legacy
- std-error-handling

issues.exclude

This property has been replaced with linters.exclusions.rules.

v1
issues:
exclude:
- abcdef
v2
linters:
exclusions:
rules:
- path: '(.+)\.go$'
text: abcdef

issues.include

This property has been replaced with linters.exclusions.presets.

v1
issues:
include:
- EXC0014
- EXC0015
v2
linters:
exclusions:
presets:
- common-false-positives
- legacy
- std-error-handling

output

output.format

This property has been deprecated since v1.57.0 and has been replaced with output.formats.

v1
output:
format: 'checkstyle:report.xml,json:stdout,colored-line-number'
v2
output:
formats:
checkstyle:
path: 'report.xml'
json:
path: stdout
text:
path: stdout
color: true

output.formats[].format: <name>

The property output.formats[].format has been replaced with output.formats[].<format_name>.

v1
output:
formats:
- format: json
path: stderr
- format: checkstyle
path: report.xml
v2
output:
formats:
json:
path: stderr
checkstyle:
path: report.xml

output.formats[].format: line-number

This format has been replaced by the format text.

v1
output:
formats:
- format: line-number
v2
output:
formats:
text:
path: stdout

output.formats[].format: colored-line-number

This format has been replaced by the format text with the option colors (true by default).

v1
output:
formats:
- format: colored-line-number
v2
output:
formats:
text:
path: stdout
colors: true

output.formats[].format: colored-tab

This format has been replaced by the format tab with the option colors (true by default).

v1
output:
formats:
- format: colored-tab
v2
output:
formats:
tab:
path: stdout
colors: true

output.print-issued-lines

This property has been removed.

To not print the lines with issues, use the text format with the option print-issued-lines: false.

v1
output:
formats:
- format: line-number
path: stdout
print-issued-lines: false
v2
output:
formats:
text:
path: stdout
print-issued-lines: false

output.print-linter-name

This property has been removed.

To not print the linter name, use the text format with the option print-linter-name: false.

v1
output:
formats:
- format: line-number
path: stdout
print-linter-name: false
v2
output:
formats:
text:
path: stdout
print-linter-name: false

output.show-stats

This property is true by default.

output.sort-order

This property has a new default value ['linter', 'file'] instead of ['file'].

output.sort-results

The property has been removed.

The output results are always sorted.

output.uniq-by-line

This property has been deprecated since v1.63.0 and has been replaced by issues.uniq-by-line.

v1
output:
uniq-by-line: true
v2
issues:
uniq-by-line: true

run

run.go

The new fallback value for this property is 1.22 instead of 1.17.

run.concurrency

This property value set to match Linux container CPU quota by default and fallback on the number of logical CPUs in the machine.

run.relative-path-mode

This property has a new default value of cfg instead of wd.

v1
run:
# When not specified, relative-path-mode is set to 'wd' by default
v2
run:
relative-path-mode: 'cfg'

run.show-stats

This property has been deprecated since v1.57.0 and has been replaced by output.show-stats.

v1
run:
show-stats: true
v2
output:
show-stats: true

run.skip-dirs-use-default

This property has been deprecated since v1.57.0 and has been replaced by issues.exclude-dirs-use-default.

v1
run:
skip-dirs-use-default: false
v2
issues:
exclude-dirs-use-default: false

run.skip-dirs

This property has been deprecated since v1.57.0 and has been removed.

Use linters.exclusions.paths and formatters.exclusions.paths to exclude directories.

v1
run:
skip-dirs:
- src/external_libs
- autogenerated_by_my_lib
v2
linters:
exclusions:
paths:
- src/external_libs
- autogenerated_by_my_lib

run.skip-files

This property has been deprecated since v1.57.0 and has been removed.

Use linters.exclusions.paths and formatters.exclusions.paths to exclude files.

v1
run:
skip-files:
- '.*\.my\.go$'
- lib/bad.go
v2
linters:
exclusions:
paths:
- '.*\.my\.go$'
- lib/bad.go

run.timeout

This property value is disabled by default (0).

severity

severity.default-severity

This property has been replaced with severity.default.

v1
severity:
default-severity: error
v2
severity:
default: error

severity.rules.case-sensitive

severity.rules.text and severity.rules.source are case-sensitive by default.

To ignore case, use (?i) at the beginning of a regex syntax.

v1
severity:
case-sensitive: true
rules:
- severity: info
linters:
- foo
text: 'Example.*'
v2
severity:
rules:
- severity: info
linters:
- foo
text: '(?i)Example.*'

version

The version property has been added to the configuration file.

version: "2"

Integration

VSCode

v1
"go.lintTool": "golangci-lint",
"go.lintFlags": [
"--fast"
]
v2
"go.lintTool": "golangci-lint",
"go.lintFlags": [
"--fast-only"
],
"go.formatTool": "custom",
"go.alternateTools": {
"customFormatter": "golangci-lint"
},
"go.formatFlags": [
"fmt",
"--stdin"
]

Command Line Flags

The following flags have been removed:

  • --disable-all
  • --enable-all
  • -p, --presets
  • --fast
  • -e, --exclude
  • --exclude-case-sensitive
  • --exclude-dirs-use-default
  • --exclude-dirs
  • --exclude-files
  • --exclude-generated
  • --exclude-use-default
  • --go string
  • --sort-order
  • --sort-results
  • --out-format

--out-format

--out-format has been replaced with the following flags:

# Previously 'colored-line-number' and 'line-number'
--output.text.path
--output.text.print-linter-name
--output.text.print-issued-lines
--output.text.colors
# Previously 'json'
--output.json.path
# Previously 'colored-tab' and 'tab'
--output.tab.path
--output.tab.print-linter-name
--output.tab.colors
# Previously 'html'
--output.html.path
# Previously 'checkstyle'
--output.checkstyle.path
# Previously 'code-climate'
--output.code-climate.path
# Previously 'junit-xml' and 'junit-xml-extended'
--output.junit-xml.path
--output.junit-xml.extended
# Previously 'teamcity'
--output.teamcity.path
# Previously 'sarif'
--output.sarif.path

--disable-all and --enable-all

--disable-all has been replaced with --default=none.

--enable-all has been replaced with --default=all.

Example

v1
golangci-lint run --disable-all --enable=govet --out-format=json --sort-order=linter --sort-results
v2
golangci-lint run --default=none --enable=govet --output.json.path=stdout
Edit this page on GitHub