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.

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):

  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 has been removed.

The migrate command automatically migrates linters.presets in individual linters to linters.enable.

Presets:

namelinters
bugsasasalint, 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
commentdupword, godot, godox, misspell
complexitycyclop, funlen, gocognit, gocyclo, maintidx, nestif
errorerr113, errcheck, errorlint, wrapcheck
formatgci, gofmt, gofumpt, goimports
importdepguard, gci, goimports, gomodguard
metalintergocritic, govet, revive, staticcheck
moduledepguard, gomoddirectives, gomodguard
performancebodyclose, fatcontext, noctx, perfsprint, prealloc
sqlrowserrcheck, sqlclosecheck
styleasciicheck, 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
testexhaustruct, paralleltest, testableexamples, testifylint, testpackage, thelper, tparallel, usetesting
unusedineffassign, 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 v1Name v2
gasgosec
goerr113err113
gomndmnd
logrlintloggercheck
megacheckstaticcheck
vetgovet
vetshadowgovet
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
Last updated on