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.

# Removed

typecheck

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

• FAQ: Why do you have typecheck errors?
• FAQ: Why is it not possible to skip/ignore typecheck errors?

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.

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

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