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 was0
, it is removed as0
is the new default.run.relative-path-mode
: if the existing value wascfg
, it is removed ascfg
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.
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: true
linters:
default: none
linters.enable-all
This property has been replaced with linters.default: all
.
linters:
enable-all: true
linters:
default: all
linters.enable[].<formatter_name>
The linters gci
, gofmt
, gofumpt
, and goimports
have been moved to the formatters
section.
linters:
enable:
- gci
- gofmt
- gofumpt
- goimports
formatters:
enable:
- gci
- gofmt
- gofumpt
- goimports
linters.enable[].{stylecheck,gosimple,staticcheck}
The linters stylecheck
, gosimple
, and staticcheck
has been merged inside the staticcheck
.
linters:
enable:
- gosimple
- staticcheck
- stylecheck
linters:
enable:
- staticcheck
linters.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 |
# 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 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
- vetshadow
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.
linters-settings:
govet:
enable-all: true
gofmt:
simplify: false
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
.
linters-settings:
asasalint:
ignore-test: true
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
.
linters-settings:
copyloopvar:
ignore-alias: false
linters:
settings:
copyloopvar:
check-alias: true
linters-settings.cyclop.skip-tests
This option has been removed.
To ignore test files, use linters.exclusions.rules
.
linters-settings:
cyclop:
skip-test: true
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.
linters-settings:
errcheck:
exclude: ./errcheck_excludes.txt
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.
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: true
linters:
exclusions:
generated: disable
linters-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: false
linters:
exclusions:
generated: disable
linters-settings.goconst.ignore-tests
This option has been removed.
To ignore test files, use linters.exclusions.rules
.
linters-settings:
goconst:
ignore-tests: true
linters:
exclusions:
rules:
- path: '(.+)_test\.go'
linters:
- goconst
linters-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: true
linters:
settings:
govet:
enable:
- shadow
linters-settings.misspell.ignore-words
This option has been replaced with linters.settings.misspell.ignore-rules
.
linters-settings:
misspell:
ignore-words:
- foo
linters:
settings:
misspell:
ignore-rules:
- foo
linters-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
- int
linters-settings.predeclared.q
This option has been replaced with linters.settings.predeclared.qualified-name
.
linters-settings:
predeclared:
q: true
linters:
settings:
predeclared:
qualified-name: true
linters-settings.revive.ignore-generated-header
This option has been removed.
Use linters.exclusions.generated
instead.
linters-settings:
revive:
ignore-generated-header: true
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
.
linters-settings:
sloglint:
context-only: true
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.
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
# Removed
linters-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
# Removed
linters-settings.usestdlibvars.syslog-priority
This option has been deprecated since v1.51.0 and has been removed.
linters-settings:
usestdlibvars:
syslog-priority: true
# Removed
linters-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)abcdef
issues.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: true
linters:
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_lib
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
.
issues:
exclude-files:
- '.*\.my\.go$'
- lib/bad.go
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
.
linters:
exclude-generated-strict: true
linters:
exclusions:
generated: strict
issues.exclude-generated
This property has been replaced with linters.exclusions.generated
.
linters:
exclude-generated: lax
linters:
exclusions:
generated: lax
issues.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:
- err113
issues.exclude-use-default
This property has been replaced with linters.exclusions.presets
.
issues:
exclude-use-default: true
linters:
exclusions:
presets:
- comments
- common-false-positives
- legacy
- std-error-handling
issues.exclude
This property has been replaced with linters.exclusions.rules
.
issues:
exclude:
- abcdef
linters:
exclusions:
rules:
- path: '(.+)\.go$'
text: abcdef
issues.include
This property has been replaced with linters.exclusions.presets
.
issues:
include:
- EXC0014
- EXC0015
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
.
output:
format: 'checkstyle:report.xml,json:stdout,colored-line-number'
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>
.
output:
formats:
- format: json
path: stderr
- format: checkstyle
path: report.xml
output:
formats:
json:
path: stderr
checkstyle:
path: report.xml
output.formats[].format: line-number
This format has been replaced by the format text
.
output:
formats:
- format: line-number
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).
output:
formats:
- format: colored-line-number
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).
output:
formats:
- format: colored-tab
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
.
output:
formats:
- format: line-number
path: stdout
print-issued-lines: false
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
.
output:
formats:
- format: line-number
path: stdout
print-linter-name: false
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
.
output:
uniq-by-line: true
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
.
run:
# When not specified, relative-path-mode is set to 'wd' by default
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
.
run:
show-stats: true
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
.
run:
skip-dirs-use-default: false
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.
run:
skip-dirs:
- src/external_libs
- autogenerated_by_my_lib
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.
run:
skip-files:
- '.*\.my\.go$'
- lib/bad.go
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
.
severity:
default-severity: error
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.
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
VSCode
"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-results
golangci-lint run --default=none --enable=govet --output.json.path=stdout
Do 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-number
golangci-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