GolangCI-Lint

https://github.com/golangci/golangci-lint
Admin
golangci-lint is a fast Go linters runner that executes linters in parallel, utilizes caching,...
Tokens:151,681
Snippets:1,031
Trust Score:9.4
License:GPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install golangci-lint binary with curl

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Downloads and installs the golangci-lint binary using the official install script. The first command installs to the Go bin directory ($(go env GOPATH)/bin), the second installs to ./bin/, and the third uses wget for Alpine Linux. Includes a version check with `golangci-lint --version`.

```bash
# binary will be $(go env GOPATH)/bin/golangci-lint
curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b $(go env GOPATH)/bin {{< golangci/latest-version >}}

# or install it into ./bin/
curl -sSfL https://golangci-lint.run/install.sh | sh -s {{< golangci/latest-version >}}

# In Alpine Linux (as it does not come with curl by default)
wget -O- -nv https://golangci-lint.run/install.sh | sh -s {{< golangci/latest-version >}}

golangci-lint --version

```

--------------------------------

### Install golangci-lint with go install

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs golangci-lint from source using the Go toolchain. This method is not recommended because it compiles locally, may use untested dependency upgrades, and can be affected by local Go version and module issues.

```bash
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@{{< golangci/latest-version >}}
```

--------------------------------

### Install golangci-lint with Chocolatey

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs golangci-lint on Windows using Chocolatey.

```bash
choco install golangci-lint
```

--------------------------------

### Shortcode usage example

Source: https://github.com/golangci/golangci-lint/blob/main/docs/layouts/_shortcodes/golangci/items/settings.html

Shows how to invoke the settings shortcode with the required info and settings data file names.

```text
{{% golangci/items/settings info="formatters_info" settings="formatter_settings" %}}
```

--------------------------------

### Build and run golangci-lint

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/workflow.md

Builds the project and runs golangci-lint with verbose output to verify the setup.

```bash
make build
./golangci-lint run -v
```

--------------------------------

### Install golangci-lint with Homebrew (brew install golangci-lint)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs or upgrades golangci-lint on macOS using Homebrew. Note that Homebrew may use an unexpected Go version to build the binary, so using the official binaries is recommended.

```bash
brew install golangci-lint
brew upgrade golangci-lint

```

--------------------------------

### Run local development server with make website_expand_templates and make serve

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/website.md

Alternative way to start the local server. First expand templates from the repository root, then change to the docs/ directory and run `make serve`. Requires Hugo Extended v0.148.1 or newer. After a successful build, navigate to http://localhost:1313.

```bash
# (in the root of the repository)
make website_expand_templates

cd docs/

# (inside the docs/ folder)
make serve
```

--------------------------------

### VS Code settings for golangci-lint installed via extension

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/integrations.md

Recommended VS Code settings when golangci-lint is installed via the extension. Install `golangci-lint-v2` via the `Go: Install/Update Tools` command after setting these configs. This enables golangci-lint v1 to co-exist with v2. Using it in an editor without `--fast-only` can freeze your editor.

```JSONata
"go.lintTool": "golangci-lint-v2",
"go.lintFlags": [
  "--path-mode=abs",
  "--fast-only"
],
"go.formatTool": "custom",
"go.alternateTools": {
  "customFormatter": "golangci-lint-v2"
},
"go.formatFlags": [
  "fmt",
  "--stdin"
]
```

--------------------------------

### Install golangci-lint with mise

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs golangci-lint globally using mise, which uses the aqua backend. The mise integration is not officially maintained by the golangci team.

```bash
mise use -g golangci-lint@{{< golangci/latest-version >}}
```

--------------------------------

### Run local development server with make docs_serve

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/website.md

Starts the Hugo development server from the repository root. Requires Hugo Extended v0.148.1 or newer. After a successful build, navigate to http://localhost:1313. The server supports hot reload, so no restart or manual refresh is needed for most changes.

```bash
# (in the root of the repository)
make docs_serve
```

--------------------------------

### Install golangci-lint with MacPorts (sudo port install golangci-lint)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs golangci-lint on macOS using MacPorts. This installation mode is community-driven and not officially maintained by the golangci team.

```bash
sudo port install golangci-lint

```

--------------------------------

### Install golangci-lint with Scoop

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Installs golangci-lint on Windows using Scoop. The Scoop package is not officially maintained by the golangci team.

```bash
scoop install main/golangci-lint
```

--------------------------------

### VS Code settings for manual golangci-lint installation

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/integrations.md

Recommended VS Code settings when golangci-lint is installed manually. Using it in an editor without `--fast-only` can freeze your editor. Golangci-lint automatically discovers the `.golangci.yml` config for the edited file.

```JSONata
"go.lintTool": "golangci-lint",
"go.lintFlags": [
  "--path-mode=abs",
  "--fast-only"
],
"go.formatTool": "custom",
"go.alternateTools": {
  "customFormatter": "golangci-lint"
},
"go.formatFlags": [
  "fmt",
  "--stdin"
]
```

--------------------------------

### Add golangci-lint bash completion

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/integrations.md

Commands to add golangci-lint bash completion to your shell. Run after installing bash-completion v2.

```bash
echo 'source <(golangci-lint completion bash)' >>~/.bashrc
source ~/.bashrc
```

--------------------------------

### Configure .golangci.yml for module plugin linter

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/plugins/module-plugins.md

Defines a .golangci.yml configuration that enables the custom plugin linter 'foo' with type 'module'. This example is used in the automatic build method, but the same configuration applies to the manual approach. The settings block passes a 'message' parameter to the plugin.

```yaml
version: "2"

linters:
  default: none
  enable:
    - foo
  settings:
    custom:
      foo:
        type: "module"
        description: This is an example usage of a plugin linter.
        settings:
          message: hello

```

--------------------------------

### output.format deprecated, use output.formats (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows migrating the deprecated output.format property to the new output.formats structure. The v1 example uses a comma-separated format string with path, while v2 defines a map of format names to paths and color options.

```yaml
output:
  format: 'checkstyle:report.xml,json:stdout,colored-line-number'
```

```yaml
output:
  formats:
    checkstyle:
      path: 'report.xml'
    json:
      path: stdout
    text:
      path: stdout
      color: true
```

--------------------------------

### Install bash-completion v2 on macOS

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/integrations.md

Commands to install bash-completion v2 on macOS. Requires Bash 4.1+ and bash-completion v2. The completion script does not work with bash-completion v1 and Bash 3.2.

```bash
brew install bash-completion@2
echo 'export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"' >>~/.bashrc
echo '[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"' >>~/.bashrc
exec bash # reload and replace (if it was updated) shell
type _init_completion && echo "completion is OK" # verify that bash-completion v2 is correctly installed
```

--------------------------------

### Build website with make website_copy_jsonschema website_expand_templates and make build

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/website.md

Alternative build process: first copy JSON schemas and expand templates from the repository root, then change to the docs/ directory and run `make build`.

```bash
# (in the root of the repository)
make website_copy_jsonschema website_expand_templates

cd docs/

# (inside the docs/ folder)
make build
```

--------------------------------

### Build the plugin with go build -buildmode=plugin

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/plugins/go-plugins.md

Run this command from the root project directory to build the plugin. It creates a .so file that can be copied into your project.

```bash
go build -buildmode=plugin plugin/example.go
```

--------------------------------

### Build website with make docs_build

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/website.md

Builds the website for production from the repository root. This is the primary build command.

```bash
# (in the root of the repository)
make docs_build
```

--------------------------------

### Run golangci-lint migrate

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Migrates the configuration file to v2 format. Comments and deprecated options are not migrated.

```bash
golangci-lint migrate
```

--------------------------------

### Define the New function in plugin/example.go

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/plugins/go-plugins.md

The plugin must be in package main and define an exposed function New with this signature. It returns a slice of analysis.Analyzer structs.

```go
func New(conf any) ([]*analysis.Analyzer, error) {
	// ...
}
```

--------------------------------

### List configured linters with golangci-lint linters

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/_index.md

Shows the linters enabled by your current configuration.

```bash
golangci-lint linters
```

--------------------------------

### Run with text output and Code Climate report (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 command using --print-issued-lines=false and --out-format code-climate, and the v2 equivalent using --output.text.path and --output.code-climate.path.

```bash
golangci-lint run --print-issued-lines=false --out-format code-climate:gl-code-quality-report.json,line-number
```

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

--------------------------------

### Use go tool with dedicated module and workspace (Method 2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Method 2 for using `go tool` with a dedicated module and Go workspace. This isolates golangci-lint from other tools and project dependencies. Steps: create a directory, initialize a module file, set up a workspace, add golangci-lint as a tool, run it, and update it. Never update golangci-lint dependencies manually.

```sh
# Create a dedicated directory
mkdir golangci-lint
```

```sh
# Create a dedicated module file
go mod init -modfile=tools/go.mod <your_module_path>/golangci-lint
# Example: go mod init -modfile=golangci-lint/go.mod github.com/org/repo/golangci-lint
```

```sh
# Setup a Go workspace
go work init . golangci-lint
```

```sh
# Add golangci-lint as a tool
go get -tool -modfile=golangci-lint/go.mod github.com/golangci/golangci-lint/v2/cmd/golangci-lint
```

```sh
# Run golangci-lint as a tool
go tool golangci-lint run
```

```sh
# Update golangci-lint
go get -tool -modfile=golangci-lint/go.mod github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
```

--------------------------------

### Run golangci-lint on all packages recursively

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Equivalent to `golangci-lint run` but explicitly targets all packages in the current directory and subdirectories.

```bash
golangci-lint run ./...
```

--------------------------------

### Run golangci-lint in Docker

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Runs golangci-lint in a Docker container, mounting the current directory to /app and setting the working directory. The image tag uses the latest version placeholder.

```bash
docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run
```

--------------------------------

### Run only govet linter with JSON output (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 command using --disable-all and --out-format=json, and the v2 equivalent using --default=none and --output.json.path=stdout.

```bash
golangci-lint run --disable-all --enable=govet --out-format=json --sort-order=linter --sort-results
```

```bash
golangci-lint run --default=none --enable=govet --output.json.path=stdout
```

--------------------------------

### PackageLoader.Load method (Go)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/architecture.md

Entry point for loading packages. It determines the load mode from enabled linters and loads packages, returning an error if loading fails.

```go
func (l *PackageLoader) Load(ctx context.Context, linters []*linter.Config) (pkgs, deduplicatedPkgs []*packages.Package, err error) {
	loadMode := findLoadMode(linters)

	pkgs, err = l.loadPackages(ctx, loadMode)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to load packages: %w", err)
	}
// ...
```

--------------------------------

### Proper nolint directives with explanation (//nolint:gosec)

Source: https://github.com/golangci/golangci-lint/blob/main/pkg/golinters/nolintlint/internal/README.md

Shows properly formatted `//nolint` directives with explanations and specific linter names (`gosec`), which `nolintlint` can require.

```go
import "crypto/md5" //nolint:gosec // this is not used in a secure application

func hash(data []byte) []byte {
	return md5.New().Sum(data) //nolint:gosec // this result is not used in a secure application
}
```

--------------------------------

### Benchmark one linter with local version

Source: https://github.com/golangci/golangci-lint/blob/main/scripts/bench/readme.md

Runs a benchmark for a single linter using a locally built version of golangci-lint. Specify the linter with LINTER and the version tag with VERSION.

```bash
make bench_local LINTER=gosec VERSION=v1.59.0
```

--------------------------------

### Run golangci-lint in Docker with cache preservation

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Runs golangci-lint in Docker while preserving caches between consecutive runs by mounting Go build, module, and golangci-lint caches.

```bash
docker run --rm -t -v $(pwd):/app -w /app \
--user $(id -u):$(id -g) \
-v $(go env GOCACHE):/.cache/go-build -e GOCACHE=/.cache/go-build \
-v $(go env GOMODCACHE):/.cache/mod -e GOMODCACHE=/.cache/mod \
-v ~/.cache/golangci-lint:/.cache/golangci-lint -e GOLANGCI_LINT_CACHE=/.cache/golangci-lint \
golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run
```

--------------------------------

### Run golangci-lint in Docker with colored output

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Runs golangci-lint in Docker with colored output enabled via the -t flag.

```bash
docker run -t --rm -v $(pwd):/app -w /app golangci/golangci-lint:{{< golangci/latest-version >}} golangci-lint run
```

--------------------------------

### Run golangci-lint on specific directories or files

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Analyzes the specified directories or files. Directories are not analyzed recursively unless `/...` is appended. Mixing files and packages/directories is not allowed, and files must come from the same package.

```bash
golangci-lint run dir1 dir2/...
golangci-lint run file1.go
```

--------------------------------

### WithLoadForGoAnalysis configuration (Go)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/architecture.md

Configures a linter to load additional data for go/analysis, including imports, dependencies, export files, and type sizes. Marks the linter as slow.

```go
func (lc *Config) WithLoadForGoAnalysis() *Config {
	lc = lc.WithLoadFiles()
	lc.LoadMode |= packages.NeedImports | packages.NeedDeps | packages.NeedExportFile | packages.NeedTypesSizes
	lc.IsSlow = true
	return lc
}
```

--------------------------------

### Migrate govet check-shadowing to enable shadow

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.govet.check-shadowing` and the v2 replacement using `linters.settings.govet.enable` with the `shadow` analyzer.

```yaml
linters-settings:
  govet:
    check-shadowing: true
```

```yaml
linters:
  settings:
    govet:
      enable:
        - shadow
```

--------------------------------

### Run golangci-lint

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Runs golangci-lint on the current directory. Equivalent to `golangci-lint run ./...`.

```bash
golangci-lint run
```

--------------------------------

### Run golangci-lint with verbose output

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/debug.md

Use the -v option to see verbose output of the linter.

```bash
golangci-lint run -v
```

--------------------------------

### Migrate staticcheck go to run.go

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.staticcheck.go` and the v2 replacement using `run.go`.

```yaml
linters-settings:
  staticcheck:
    go: '1.22'
```

```yaml
run:
  go: '1.22'
```

--------------------------------

### Use go tool with dedicated module file (Method 1)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/local.md

Method 1 for using `go tool` with a dedicated module file. This isolates golangci-lint from other tools and project dependencies. The steps are: create a module file, add golangci-lint as a tool, run it, and update it. Never update golangci-lint dependencies manually.

```sh
# Create a dedicated module file
go mod init -modfile=golangci-lint.mod <your_module_path>/golangci-lint
# Example: go mod init -modfile=golangci-lint.mod github.com/org/repo/golangci-lint
```

```sh
# Add golangci-lint as a tool
go get -tool -modfile=golangci-lint.mod github.com/golangci/golangci-lint/v2/cmd/golangci-lint@{{< golangci/latest-version >}}
```

```sh
# Run golangci-lint as a tool
go tool -modfile=golangci-lint.mod golangci-lint run
```

```sh
# Update golangci-lint
go get -tool -modfile=golangci-lint.mod github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
```

--------------------------------

### run.relative-path-mode: v1 default vs v2 cfg

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 default behavior for run.relative-path-mode (unset, defaults to 'wd') and the v2 configuration that sets it to 'cfg'.

```yaml
run:
# When not specified, relative-path-mode is set to 'wd' by default
```

```yaml
run:
  relative-path-mode: 'cfg'
```

--------------------------------

### Execution steps diagram (Mermaid)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/architecture.md

Mermaid graph showing the sequence of golangci-lint execution steps: Init, Load packages, Run linters, Postprocess issues, Print issues.

```mermaid
graph LR
    init[Init]
    loadPackages[Load packages]
    runLinters[Run linters]
    postprocess[Postprocess issues]
    print[Print issues]

    init --> loadPackages --> runLinters --> postprocess --> print
```

--------------------------------

### List supported linters with golangci-lint help linters

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/_index.md

Displays a list of supported linters and which are enabled or disabled.

```bash
golangci-lint help linters
```

--------------------------------

### Benchmark one linter between two versions

Source: https://github.com/golangci/golangci-lint/blob/main/scripts/bench/readme.md

Runs a benchmark comparing two existing versions of golangci-lint for a single linter. Provide the linter name and both version tags.

```bash
make bench_version LINTER=gosec VERSION_OLD=v1.58.1 VERSION_NEW=v1.59.0
```

--------------------------------

### Run golangci-lint migrate with --format json

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Overrides the migration file format to JSON using the --format flag.

```bash
golangci-lint migrate --format json
```

--------------------------------

### Format specific directories or files with golangci-lint fmt

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Formats the specified directories or files. Directories are not analyzed recursively unless `/...` is appended. Mixing files and packages/directories is not allowed, and files must come from the same package.

```bash
golangci-lint fmt dir1 dir2/...
golangci-lint fmt file1.go
```

--------------------------------

### Run golangci-lint with GL_DEBUG tags

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/debug.md

Set the GL_DEBUG environment variable to a comma-separated list of debug tags to enable detailed logs. The tags are documented in /pkg/logutils/logutils.go.

```bash
GL_DEBUG="loader,gocritic" golangci-lint run
```

```bash
GL_DEBUG="loader,env" golangci-lint run
```

--------------------------------

### WithLoadFiles configuration (Go)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/architecture.md

Configures a linter to load only filenames and compiled Go files, suitable for AST-only linters.

```go
func (lc *Config) WithLoadFiles() *Config {
	lc.LoadMode |= packages.NeedName | packages.NeedFiles | packages.NeedCompiledGoFiles
	return lc
}
```

--------------------------------

### Replace enable-all with default: all

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

In v1, linters.enable-all enabled all linters. In v2, use linters.default: all.

```yaml
linters:
  enable-all: true
```

```yaml
linters:
  default: all
```

--------------------------------

### Buildkite plugin configuration

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/ci.md

Configures the golangci-lint Buildkite plugin in a pipeline. The plugin uses the Docker image by default but can be set to use a binary if available on the agent, and it annotates builds with results.

```yaml
plugins:
  - golangci-lint#v1.0.0:
      config: .golangci.yml
```

--------------------------------

### Bad nolint directives without explanation (//nolint:all)

Source: https://github.com/golangci/golangci-lint/blob/main/pkg/golinters/nolintlint/internal/README.md

Shows an import and function where `//nolint:all` suppresses all linters without explanation, demonstrating an ill-formed or insufficiently explained nolint directive.

```go
import "crypto/md5" //nolint:all

func hash(data []byte) []byte {
	return md5.New().Sum(data) //nolint:all
}
```

--------------------------------

### Run tests

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/workflow.md

Runs all linters and tests.

```bash
make test
```

--------------------------------

### Configure custom linter in .golangci.yml

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/plugins/go-plugins.md

Add a custom linter entry under linters.settings.custom. The path is required, description and original-url are optional, and settings are optional. Custom linters are enabled by default but can be disabled with 'disable all'.

```yaml
version: "2"

linters:
  settings:
    custom:
      example:
        path: /example.so
        description: The description of the linter
        original-url: github.com/golangci/example-linter
        settings: # Settings are optional.
          one: Foo
          two:
            - name: Bar
          three:
            name: Bar
```

--------------------------------

### VS Code settings: v1 --fast vs v2 --fast-only

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the Visual Studio Code settings for golangci-lint v1 (using --fast) and v2 (using --fast-only and configuring the formatter).

```JSONata
"go.lintTool": "golangci-lint",
"go.lintFlags": [
  "--fast"
]
```

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

--------------------------------

### Migrate usestdlibvars os-dev-null (removed)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.usestdlibvars.os-dev-null` and the v2 replacement which is a comment indicating removal.

```yaml
linters-settings:
  usestdlibvars:
    os-dev-null: true
```

```yaml
# Removed
```

--------------------------------

### List supported formatters with golangci-lint help formatters

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/formatters/_index.md

Displays a list of supported formatters and indicates which are enabled or disabled.

```bash
golangci-lint help formatters
```

--------------------------------

### Migrate predeclared q to qualified-name

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `q` and the v2 replacement using `qualified-name`.

```yaml
linters-settings:
  predeclared:
    q: true
```

```yaml
linters:
  settings:
    predeclared:
      qualified-name: true
```

--------------------------------

### Run golangci-lint migrate with --skip-validation

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Skips validation against the JSON Schema of configuration v1 before migration.

```bash
golangci-lint migrate --skip-validation
```

--------------------------------

### linters-settings split: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration with linters-settings for govet and gofmt, and the v2 configuration splitting settings into linters.settings and formatters.settings.

```yaml
linters-settings:
  govet:
    enable-all: true
  gofmt:
    simplify: false
```

```yaml
linters:
  settings:
    govet:
      enable-all: true

formatters:
  settings:
    gofmt:
      simplify: false
```

--------------------------------

### Migrate sloglint context-only to context

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `context-only` and the v2 replacement using `context` with value `all`.

```yaml
linters-settings:
  sloglint:
    context-only: true
```

```yaml
linters:
  settings:
    sloglint:
      context: all
```

--------------------------------

### Format code with golangci-lint fmt

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Formats the code in the current directory using the `fmt` command.

```bash
golangci-lint fmt
```

--------------------------------

### Migrate predeclared ignore from string to slice

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using a string for `ignore` and the v2 replacement using a slice.

```yaml
linters-settings:
  predeclared:
    ignore: "new,int"
```

```yaml
linters:
  settings:
    predeclared:
      ignore:
        - new
        - int
```

--------------------------------

### Enable a specific linter with --default=none

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/quick-start.md

Runs golangci-lint with no default linters and enables only the `errcheck` linter using the `-E` flag.

```bash
golangci-lint run --default=none -E errcheck
```

--------------------------------

### Configure .custom-gcl.yml for custom plugin build

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/plugins/module-plugins.md

Defines the .custom-gcl.yml configuration for building a custom golangci-lint binary. It specifies plugins from a Go proxy (with module, import, and version) and from local source (with module and path). The {{< golangci/latest-version >}} placeholder is a Hugo shortcode that must be replaced by the actual version.

```yaml
version: {{< golangci/latest-version >}}
plugins:
  # a plugin from a Go proxy
  - module: 'github.com/golangci/plugin1'
    import: 'github.com/golangci/plugin1/foo'
    version: v1.0.0

  # a plugin from local source
  - module: 'github.com/golangci/plugin2'
    path: /my/local/path/plugin2

```

--------------------------------

### List enabled formatters with golangci-lint formatters

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/formatters/_index.md

Shows the formatters enabled by your current configuration.

```bash
golangci-lint formatters
```

--------------------------------

### Migrate gci local-prefixes to sections

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.gci.local-prefixes` and the v2 replacement using `linters.settings.gci.sections` with a `prefix` section.

```yaml
linters-settings:
  gci:
    local-prefixes: 'github.com/example/pkg'
```

```yaml
linters:
  settings:
    gci:
      sections:
        - standard
        - default
        - prefix(github.com/example/pkg)
```

--------------------------------

### Migrate gocritic ruleguard ${configDir} to ${base-path}

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `${configDir}` and the v2 replacement using `${base-path}` in the ruleguard rules path.

```yaml
linters-settings:
  gocritic:
    settings:
      ruleguard:
        rules: '${configDir}/ruleguard/rules-*.go'
```

```yaml
linters:
  settings:
    gocritic:
      settings:
        ruleguard:
          rules: '${base-path}/ruleguard/rules-*.go'
```

--------------------------------

### Migrate goconst ignore-tests to exclusions.rules

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.goconst.ignore-tests` and the v2 replacement using `linters.exclusions.rules` with a path rule for test files.

```yaml
linters-settings:
  goconst:
    ignore-tests: true
```

```yaml
linters:
  exclusions:
    rules:
      - path: '(.+)_test\.go'
        linters:
          - goconst
```

--------------------------------

### Add version: "2" to configuration

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Adds the version property to the configuration file to specify v2.

```yaml
version: "2"
```

--------------------------------

### Migrate issues.exclude-dirs to v2 paths

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration for excluding directories and the v2 replacement using linters.exclusions.paths. The v1 property is replaced; the v2 syntax moves the list under linters.exclusions.paths.

```yaml
issues:
  exclude-dirs:
    - src/external_libs
    - autogenerated_by_my_lib
```

```yaml
linters:
  exclusions:
    paths:
      - src/external_libs
      - autogenerated_by_my_lib
```

--------------------------------

### Migrate issues.exclude-dirs-use-default to v2 paths

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 setting for default directory exclusions and the v2 replacement using linters.exclusions.paths. The v1 property is removed; v2 requires listing the default directories explicitly.

```yaml
issues:
  exclude-dirs-use-default: true
```

```yaml
linters:
  exclusions:
    paths:
      - third_party$
      - builtin$
      - examples$
```

--------------------------------

### Register linters in LinterBuilder.Build

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/contributing/architecture.md

Shows how linters are registered in the LinterBuilder.Build method, including configuration options like WithSince, WithLoadForGoAnalysis, and WithURL. This is the central registry for all enabled linters.

```go
func (b LinterBuilder) Build(cfg *config.Config) []*linter.Config {
	// ...
	return []*linter.Config{
		// ...
		linter.NewConfig(golinters.NewBodyclose()).
			WithSince("v1.18.0").
			WithLoadForGoAnalysis().
			WithURL("https://github.com/timakin/bodyclose"),
		// ...
		linter.NewConfig(golinters.NewGovet(govetCfg)).
			WithGroups(config.GroupStandard).
			WithSince("v1.0.0").
			WithLoadForGoAnalysis().
			WithURL("https://pkg.go.dev/cmd/vet"),
		// ...
	}
}
```

--------------------------------

### output.formats[].format replaced by format name key (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Migrates the list-style output.formats where each item has a format field to a map keyed by format name. Paths remain as values.

```yaml
output:
  formats:
    - format: json
      path: stderr
    - format: checkstyle
      path: report.xml
```

```yaml
output:
  formats:
    json:
      path: stderr
    checkstyle:
      path: report.xml
```

--------------------------------

### Migrate issues.exclude-files to v2 paths

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration for excluding files and the v2 replacement using linters.exclusions.paths. The v1 property is replaced; the v2 syntax moves the list under linters.exclusions.paths.

```yaml
issues:
  exclude-files:
    - '.*\.my\.go$'
    - lib/bad.go
```

```yaml
linters:
  exclusions:
    paths:
      - '.*\.my\.go$'
      - lib/bad.go
```

--------------------------------

### forbidigo forbid p to pattern: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using linters-settings.forbidigo.forbid[].p and the v2 replacement using linters.settings.forbidigo.forbid[].pattern.

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

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

--------------------------------

### asasalint ignore-test removal: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using linters-settings.asasalint.ignore-test and the v2 replacement using linters.exclusions.rules to ignore test files.

```yaml
linters-settings:
  asasalint:
    ignore-test: true
```

```yaml
linters:
  exclusions:
    rules:
      - path: '(.+)_test\.go'
        linters:
          - asasalint
```

--------------------------------

### run.show-stats to output.show-stats migration

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Migrates the deprecated run.show-stats property to output.show-stats in v2.

```yaml
run:
  show-stats: true
```

```yaml
output:
  show-stats: true
```

--------------------------------

### Migrate issues.exclude-use-default to v2 presets

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 setting for using default exclusions and the v2 replacement using linters.exclusions.presets. The v1 property is replaced; the v2 syntax lists the default presets explicitly.

```yaml
issues:
  exclude-use-default: true
```

```yaml
linters:
  exclusions:
    presets:
      - comments
      - common-false-positives
      - legacy
      - std-error-handling
```

--------------------------------

### Removed usestdlibvars syslog-priority option (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration for the deprecated `linters-settings.usestdlibvars.syslog-priority` option and the v2 equivalent where the option is removed.

```yaml
linters-settings:
  usestdlibvars:
    syslog-priority: true
```

```yaml
# Removed
```

--------------------------------

### Migrate misspell ignore-words to ignore-rules

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.misspell.ignore-words` and the v2 replacement using `linters.settings.misspell.ignore-rules`.

```yaml
linters-settings:
  misspell:
    ignore-words:
      - foo
```

```yaml
linters:
  settings:
    misspell:
      ignore-rules:
        - foo
```

--------------------------------

### Alternative Linter Names: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using old linter names (gas, goerr113, gomnd, logrlint, megacheck, vet, vetshadow) and the v2 configuration using the new names (gosec, err113, mnd, loggercheck, staticcheck, govet).

```yaml
linters:
  enable:
    - gas
    - goerr113
    - gomnd
    - logrlint
    - megacheck
    - vet
    - vetshadow
```

```yaml
linters:
  enable:
    - gosec
    - err113
    - mnd
    - loggercheck
    - staticcheck
    - govet
```

--------------------------------

### copyloopvar ignore-alias to check-alias: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using linters-settings.copyloopvar.ignore-alias and the v2 replacement using linters.settings.copyloopvar.check-alias.

```yaml
linters-settings:
  copyloopvar:
    ignore-alias: false
```

```yaml
linters:
  settings:
    copyloopvar:
      check-alias: true
```

--------------------------------

### Exclude all issues in a file with //nolint:unparam

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/false-positives.md

Place //nolint:unparam before the package declaration to exclude all issues from the unparam linter for the entire file.

```go
//nolint:unparam
package pkg
```

--------------------------------

### Merge stylecheck, gosimple, staticcheck into staticcheck

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

In v1, three separate linters were enabled. In v2, only staticcheck is needed as it now includes the others.

```yaml
linters:
  enable:
    - gosimple
    - staticcheck
    - stylecheck
```

```yaml
linters:
  enable:
    - staticcheck
```

--------------------------------

### Migrate revive ignore-generated-header to exclusions.generated

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters-settings.revive.ignore-generated-header` and the v2 replacement using `linters.exclusions.generated`.

```yaml
linters-settings:
  revive:
    ignore-generated-header: true
```

```yaml
linters:
  exclusions:
    generated: strict
```

--------------------------------

### Renamed wrapcheck ignorePackageGlobs to ignore-package-globs (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `ignorePackageGlobs` and the v2 configuration using the renamed key `ignore-package-globs` under `linters.settings.wrapcheck`.

```yaml
linters-settings:
  wrapcheck:
    ignorePackageGlobs:
      - 'encoding/*'
```

```yaml
linters:
  settings:
    wrapcheck:
      ignore-package-globs:
        - 'encoding/*'
```

--------------------------------

### Migrate gci skip-generated to exclusions.generated

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `linters.settings.gci.skip-generated` and the v2 replacement using `linters.exclusions.generated`.

```yaml
linters:
  settings:
    gci:
      skip-generated: false
```

```yaml
linters:
  exclusions:
    generated: disable
```

--------------------------------

### Migrate issues.include to v2 presets

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration for including specific exclusion codes and the v2 replacement using linters.exclusions.presets. The v1 property is replaced; the v2 syntax uses preset names instead of codes.

```yaml
issues:
  include:
    - EXC0014
    - EXC0015
```

```yaml
linters:
  exclusions:
    presets:
      - common-false-positives
      - legacy
      - std-error-handling
```

--------------------------------

### cyclop skip-tests removal: v1 vs v2 YAML

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using linters-settings.cyclop.skip-test and the v2 replacement using linters.exclusions.rules to ignore test files.

```yaml
linters-settings:
  cyclop:
    skip-test: true
```

```yaml
linters:
  exclusions:
    rules:
      - path: '(.+)_test\.go'
        linters:
          - cyclop
```

--------------------------------

### Exclude issues for a block with //nolint directives

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/false-positives.md

Use //nolint:all at the beginning of a line to exclude all issues for the following block. //nolint:govet before a var block excludes govet issues for that block.

```go
//nolint:all
func allIssuesInThisFunctionAreExcluded() *string {
  // ...
}

//nolint:govet
var (
  a int
  b int
)
```

--------------------------------

### Renamed wrapcheck ignoreInterfaceRegexps to ignore-interface-regexps (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `ignoreInterfaceRegexps` and the v2 configuration using the renamed key `ignore-interface-regexps` under `linters.settings.wrapcheck`.

```yaml
linters-settings:
  wrapcheck:
    ignoreInterfaceRegexps:
      - '^(?i)c(?-i)ach(ing|e)'
```

```yaml
linters:
  settings:
    wrapcheck:
      ignore-interface-regexps:
        - '^(?i)c(?-i)ach(ing|e)'
```

--------------------------------

### Add explanatory comment to //nolint directive

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/false-positives.md

Add an explanatory comment on the same line as the //nolint directive to justify why it is used.

```go
//nolint:gocyclo // This legacy function is complex, but the team too busy to simplify it
func someLegacyFunction() *string {
  // ...
}
```

--------------------------------

### Valid nolint directive syntax

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/linters/false-positives.md

Valid nolint directive syntax with no spaces.

```go
//nolint:xxx
```

--------------------------------

### Renamed wrapcheck ignoreSigRegexps to ignore-sig-regexps (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `ignoreSigRegexps` and the v2 configuration using the renamed key `ignore-sig-regexps` under `linters.settings.wrapcheck`.

```yaml
  linters-settings:
    wrapcheck:
      ignoreSigRegexps:
        - '\.New.*Error\('
```

```yaml
linters:
  settings:
    wrapcheck:
      ignore-sig-regexps:
        - '\.New.*Error\('
```

--------------------------------

### Migrate issues.exclude-rules to v2 exclusions.rules

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration for exclusion rules and the v2 replacement using linters.exclusions.rules. The v1 property is replaced; the v2 syntax moves the rules under linters.exclusions.rules and reorders some fields.

```yaml
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"
```

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

--------------------------------

### GitLab CI component include

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/welcome/install/ci.md

Adds the golangci-lint Code Quality component to a GitLab CI pipeline. The component is referenced by its full path and version, and can only be used within the same GitLab instance as the project.

```yaml
include:
  - component: $CI_SERVER_FQDN/components/code-quality-oss/codequality-os-scanners-integration/golangci@1.0.1
```

--------------------------------

### Create exclusion presets configuration snippet

Source: https://github.com/golangci/golangci-lint/blob/main/docs/layouts/_shortcodes/golangci/exclusion-presets-snippet.html

Renders a YAML configuration block for the using in the `linters.exclusions.presets` setting. The presets are pulled from the Hugo data file `exclusion_presets`. The generated YAML lists each preset name as a list item.

```markup
{{- /* Creates an exclusion presets configuration snippet. @example {{% golangci/exclusion-presets-snippet %}} */ -}}
{{- $presets := index hugo.Data.exclusion_presets -}}
```yaml
linters:
  exclusions:
    presets:
      {{- range $key, $values := $presets }}
      - {{ $key }}
      {{- end }}
```
```

--------------------------------

### Renamed wrapcheck ignoreSigs to ignore-sigs (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows the v1 configuration using `ignoreSigs` and the v2 configuration using the renamed key `ignore-sigs` under `linters.settings.wrapcheck`.

```yaml
linters-settings:
  wrapcheck:
    ignoreSigs:
      - '.Errorf('
```

```yaml
linters:
  settings:
    wrapcheck:
      ignore-sigs:
        - '.Errorf('
```

--------------------------------

### colored-tab format replaced by tab with colors option (v1 vs v2)

Source: https://github.com/golangci/golangci-lint/blob/main/docs/content/docs/product/migration-guide.md

Shows that colored-tab is now the tab format with colors: true (the default).

```yaml
output:
  formats:
    - format: colored-tab
```

```yaml
output:
  formats:
    tab:
      path: stdout
      colors: true
```
Tokens:
Raw