Migration guide
Command migrate
You can use golangci-lint to migrate your configuration with the migrate command:
golangci-lint migrateBe 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 jsonBefore 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-validationThe 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 was0, it is removed as0is the new default.run.relative-path-mode: if the existing value wascfg, it is removed ascfgis 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.
The migrate command automatically migrates linters.presets in individual linters to linters.enable.
$ golangci-lint migrate -h
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:
--color string Use color when printing; can be 'always', 'auto', or 'never' (default "auto")
-h, --help Help for a command
-v, --verbose Verbose output
Changes
linters
linters.disable-all
This property has been replaced with linters.default: none.
linters:
disable-all: truelinters:
default: nonelinters.enable-all
This property has been replaced with linters.default: all.
linters:
enable-all: truelinters:
default: alllinters.enable[].<formatter_name>
The linters gci, gofmt, gofumpt, and goimports have been moved to the formatters section.
linters:
enable:
- gci
- gofmt
- gofumpt
- goimportsformatters:
enable:
- gci
- gofmt
- gofumpt
- goimportslinters.enable[].{stylecheck,gosimple,staticcheck}
The linters stylecheck, gosimple, and staticcheck has been merged inside the staticcheck.
linters:
enable:
- gosimple
- staticcheck
- stylechecklinters:
enable:
- staticchecklinters.fast
This property has been removed.
There are 2 new options (they are not strictly equivalent to the previous option):
linters.default: fast: set all “fast” linters as the default set of linters.linters: default: fast--fast-only: filters all enabled linters to keep only “fast” linters.
linters.presets
This property has been removed.
The migrate command automatically migrates linters.presets in individual linters to linters.enable.
Presets:
| name | linters |
|---|---|
| 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 |
# Removedtypecheck
This typecheck is not a linter, so it cannot be enabled or disabled:
Deprecated Linters
The following deprecated linters have been removed:
deadcodeexecinqueryexhaustivestructexportlooprefgolintifshortinterfacermalignednosnakecasescopelintstructchecktenvvarcheck
Alternative Linter Names
The alternative linters has been removed.
| Alt Name v1 | Name v2 |
|---|---|
gas | gosec |
goerr113 | err113 |
gomnd | mnd |
logrlint | loggercheck |
megacheck | staticcheck |
vet | govet |
vetshadow | govet |
linters:
enable:
- gas
- goerr113
- gomnd
- logrlint
- megacheck
- vet
- vetshadowlinters:
enable:
- gosec
- err113
- mnd
- loggercheck
- staticcheck
- govetlinters-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.
linters-settings:
govet:
enable-all: true
gofmt:
simplify: falselinters:
settings:
govet:
enable-all: true
formatters:
settings:
gofmt:
simplify: falselinters-settings.asasalint.ignore-test
This option has been removed.
To ignore test files, use linters.exclusions.rules.
linters-settings:
asasalint:
ignore-test: truelinters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- asasalintlinters-settings.copyloopvar.ignore-alias
This option has been deprecated since v1.58.0 and has been replaced with linters.settings.copyloopvar.check-alias.
linters-settings:
copyloopvar:
ignore-alias: falselinters:
settings:
copyloopvar:
check-alias: truelinters-settings.cyclop.skip-tests
This option has been removed.
To ignore test files, use linters.exclusions.rules.
linters-settings:
cyclop:
skip-test: truelinters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- cycloplinters-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.
linters-settings:
errcheck:
exclude: ./errcheck_excludes.txtlinters:
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.
linters-settings:
errcheck:
ignore: 'io:.*'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.
linters-settings:
exhaustive:
check-generated: truelinters:
exclusions:
generated: disablelinters-settings.forbidigo.forbid[].p
This field has been replaced with linters-settings.forbidigo.forbid[].pattern.
linters-settings:
forbidigo:
forbid:
- p: '^fmt\.Print.*$'
msg: Do not commit print statements.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.
linters-settings:
forbidigo:
forbid:
- '^print(ln)?$'
- '^spew\.(ConfigState\.)?Dump$'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.
linters-settings:
gci:
local-prefixes: 'github.com/example/pkg'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.
linters:
settings:
gci:
skip-generated: falselinters:
exclusions:
generated: disablelinters-settings.goconst.ignore-tests
This option has been removed.
To ignore test files, use linters.exclusions.rules.
linters-settings:
goconst:
ignore-tests: truelinters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- goconstlinters-settings.gocritic.settings.ruleguard.rules
The special variable ${configDir} has been replaced with ${base-path}.
linters-settings:
gocritic:
settings:
ruleguard:
rules: '${configDir}/ruleguard/rules-*.go'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.
linters-settings:
govet:
check-shadowing: truelinters:
settings:
govet:
enable:
- shadowlinters-settings.misspell.ignore-words
This option has been replaced with linters.settings.misspell.ignore-rules.
linters-settings:
misspell:
ignore-words:
- foolinters:
settings:
misspell:
ignore-rules:
- foolinters-settings.predeclared.ignore
This string option has been replaced with the slice option with the same name.
linters-settings:
predeclared:
ignore: "new,int"linters:
settings:
predeclared:
ignore:
- new
- intlinters-settings.predeclared.q
This option has been replaced with linters.settings.predeclared.qualified-name.
linters-settings:
predeclared:
q: truelinters:
settings:
predeclared:
qualified-name: truelinters-settings.revive.ignore-generated-header
This option has been removed.
Use linters.exclusions.generated instead.
linters-settings:
revive:
ignore-generated-header: truelinters:
exclusions:
generated: strictlinters-settings.sloglint.context-only
This option has been deprecated since v1.58.0 and has been replaced with linters.settings.sloglint.context.
linters-settings:
sloglint:
context-only: truelinters:
settings:
sloglint:
context: alllinters-settings.staticcheck.go
This option has been deprecated since v1.47.0 and has been removed.
Use run.go instead.
linters-settings:
staticcheck:
go: '1.22'run:
go: '1.22'linters-settings.unused.exported-is-used
This option has been deprecated since v1.60.0 and has been removed.
linters-settings:
unused:
exported-is-used: true# Removedlinters-settings.usestdlibvars.os-dev-null
This option has been deprecated since v1.51.0 and has been removed.
linters-settings:
usestdlibvars:
os-dev-null: true# Removedlinters-settings.usestdlibvars.syslog-priority
This option has been deprecated since v1.51.0 and has been removed.
linters-settings:
usestdlibvars:
syslog-priority: true# Removedlinters-settings.wrapcheck.ignoreInterfaceRegexps
This option has been renamed to linters.settings.wrapcheck.ignore-interface-regexps.
linters-settings:
wrapcheck:
ignoreInterfaceRegexps:
- '^(?i)c(?-i)ach(ing|e)'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.
linters-settings:
wrapcheck:
ignorePackageGlobs:
- 'encoding/*'linters:
settings:
wrapcheck:
ignore-package-globs:
- 'encoding/*'linters-settings.wrapcheck.ignoreSigRegexps
This option has been renamed to linters.settings.wrapcheck.ignore-sig-regexps.
linters-settings:
wrapcheck:
ignoreSigRegexps:
- '\.New.*Error\('linters:
settings:
wrapcheck:
ignore-sig-regexps:
- '\.New.*Error\('linters-settings.wrapcheck.ignoreSigs
This option has been renamed to linters.settings.wrapcheck.ignore-sigs.
linters-settings:
wrapcheck:
ignoreSigs:
- '.Errorf('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.
issues:
exclude-case-sensitive: false
exclude:
- 'abcdef'linters:
exclusions:
rules:
- path: '(.+)\.go$'
text: (?i)abcdefissues.exclude-dirs-use-default
This property has been removed.
Use linters.exclusions.paths and formatters.exclusions.paths to exclude directories.
issues:
exclude-dirs-use-default: truelinters:
exclusions:
paths:
- third_party$
- builtin$
- examples$issues.exclude-dirs
This property has been replaced with linters.exclusions.paths and formatters.exclusions.paths.
issues:
exclude-dirs:
- src/external_libs
- autogenerated_by_my_liblinters:
exclusions:
paths:
- src/external_libs
- autogenerated_by_my_libissues.exclude-files
This property has been replaced with linters.exclusions.paths and formatters.exclusions.paths.
issues:
exclude-files:
- '.*\.my\.go$'
- lib/bad.golinters:
exclusions:
paths:
- '.*\.my\.go$'
- lib/bad.goissues.exclude-generated-strict
This property has been deprecated since v1.59.0 and has been replaced with linters.exclusions.generated: strict.
linters:
exclude-generated-strict: truelinters:
exclusions:
generated: strictissues.exclude-generated
This property has been replaced with linters.exclusions.generated.
linters:
exclude-generated: laxlinters:
exclusions:
generated: laxissues.exclude-rules
This property has been replaced with linters.exclusions.rules.
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"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:
- err113issues.exclude-use-default
This property has been replaced with linters.exclusions.presets.
issues:
exclude-use-default: truelinters:
exclusions:
presets:
- comments
- common-false-positives
- legacy
- std-error-handlingissues.exclude
This property has been replaced with linters.exclusions.rules.
issues:
exclude:
- abcdeflinters:
exclusions:
rules:
- path: '(.+)\.go$'
text: abcdefissues.include
This property has been replaced with linters.exclusions.presets.
issues:
include:
- EXC0014
- EXC0015linters:
exclusions:
presets:
- common-false-positives
- legacy
- std-error-handlingoutput
output.format
This property has been deprecated since v1.57.0 and has been replaced with output.formats.
output:
format: 'checkstyle:report.xml,json:stdout,colored-line-number'output:
formats:
checkstyle:
path: 'report.xml'
json:
path: stdout
text:
path: stdout
color: trueoutput.formats[].format: <name>
The property output.formats[].format has been replaced with output.formats[].<format_name>.
output:
formats:
- format: json
path: stderr
- format: checkstyle
path: report.xmloutput:
formats:
json:
path: stderr
checkstyle:
path: report.xmloutput.formats[].format: line-number
This format has been replaced by the format text.
output:
formats:
- format: line-numberoutput:
formats:
text:
path: stdoutoutput.formats[].format: colored-line-number
This format has been replaced by the format text with the option colors (true by default).
output:
formats:
- format: colored-line-numberoutput:
formats:
text:
path: stdout
colors: trueoutput.formats[].format: colored-tab
This format has been replaced by the format tab with the option colors (true by default).
output:
formats:
- format: colored-taboutput:
formats:
tab:
path: stdout
colors: trueoutput.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.
output:
formats:
- format: line-number
path: stdout
print-issued-lines: falseoutput:
formats:
text:
path: stdout
print-issued-lines: falseoutput.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.
output:
formats:
- format: line-number
path: stdout
print-linter-name: falseoutput:
formats:
text:
path: stdout
print-linter-name: falseoutput.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.
output:
uniq-by-line: trueissues:
uniq-by-line: truerun
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.
run:
# When not specified, relative-path-mode is set to 'wd' by defaultrun:
relative-path-mode: 'cfg'run.show-stats
This property has been deprecated since v1.57.0 and has been replaced by output.show-stats.
run:
show-stats: trueoutput:
show-stats: truerun.skip-dirs-use-default
This property has been deprecated since v1.57.0 and has been replaced by issues.exclude-dirs-use-default.
run:
skip-dirs-use-default: falseissues:
exclude-dirs-use-default: falserun.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.
run:
skip-dirs:
- src/external_libs
- autogenerated_by_my_liblinters:
exclusions:
paths:
- src/external_libs
- autogenerated_by_my_librun.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.
run:
skip-files:
- '.*\.my\.go$'
- lib/bad.golinters:
exclusions:
paths:
- '.*\.my\.go$'
- lib/bad.gorun.timeout
This property value is disabled by default (0).
severity
severity.default-severity
This property has been replaced with severity.default.
severity:
default-severity: errorseverity:
default: errorseverity.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.
severity:
case-sensitive: true
rules:
- severity: info
linters:
- foo
text: 'Example.*'severity:
rules:
- severity: info
linters:
- foo
text: '(?i)Example.*'version
The version property has been added to the configuration file.
version: "2"Integration
Visual Studio Code
"go.lintTool": "golangci-lint",
"go.lintFlags": [
"--fast"
]"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--print-issued-lines--print-linter-name
--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--print-issued-lines
--print-issued-lines has been replaced with --output.text.print-issued-lines.
--print-linter-name
--print-linter-name has been replaced with --output.text.print-linter-name or --output.tab.print-linter-name.
--disable-all and --enable-all
--disable-all has been replaced with --default=none.
--enable-all has been replaced with --default=all.
Examples
Run only the govet linter, output results to stdout in JSON format, and sort results:
golangci-lint run --disable-all --enable=govet --out-format=json --sort-order=linter --sort-resultsgolangci-lint run --default=none --enable=govet --output.json.path=stdoutDo not print issued lines, output results to stdout without colors in text format, and to gl-code-quality-report.json file in Code Climate’s format:
golangci-lint run --print-issued-lines=false --out-format code-climate:gl-code-quality-report.json,line-numbergolangci-lint run --output.text.path=stdout --output.text.colors=false --output.text.print-issued-lines=false --output.code-climate.path=gl-code-quality-report.json