From 487aee999af1d002447d35c643d8ec7266e2ca36 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Tue, 25 Mar 2025 16:18:21 +0100 Subject: [PATCH 1/4] docs: clean old examples --- .golangci.reference.yml | 11 +-- docs/src/docs/plugins/go-plugins.mdx | 25 +++--- docs/src/docs/plugins/module-plugins.mdx | 34 ++++---- docs/src/docs/usage/false-positives.mdx | 102 +++++++++++------------ 4 files changed, 83 insertions(+), 89 deletions(-) diff --git a/.golangci.reference.yml b/.golangci.reference.yml index ff5b11d64865..1fd85366eed1 100644 --- a/.golangci.reference.yml +++ b/.golangci.reference.yml @@ -415,11 +415,12 @@ linters: # if check-error-free-encoding is set to true and errcheck linter is enabled, # it is recommended to add the following exceptions to prevent from false positives: # - # linters-settings: - # errcheck: - # exclude-functions: - # - encoding/json.Marshal - # - encoding/json.MarshalIndent + # linters: + # settings: + # errcheck: + # exclude-functions: + # - encoding/json.Marshal + # - encoding/json.MarshalIndent # # Default: false check-error-free-encoding: true diff --git a/docs/src/docs/plugins/go-plugins.mdx b/docs/src/docs/plugins/go-plugins.mdx index a5df6b9b5b00..9142db39d049 100644 --- a/docs/src/docs/plugins/go-plugins.mdx +++ b/docs/src/docs/plugins/go-plugins.mdx @@ -50,18 +50,19 @@ If you're looking for instructions on how to configure your own custom linter, t 1. If the project you want to lint does not have one already, copy the [.golangci.yml](https://github.com/golangci/golangci-lint/blob/HEAD/.golangci.yml) to the root directory. 2. Adjust the YAML to appropriate `linters-settings.custom` entries as so: ```yaml title=.golangci.yml - 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 + 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 ``` That is all the configuration that is required to run a custom linter in your project. diff --git a/docs/src/docs/plugins/module-plugins.mdx b/docs/src/docs/plugins/module-plugins.mdx index 44f3b40502e8..17c5ee98fd22 100644 --- a/docs/src/docs/plugins/module-plugins.mdx +++ b/docs/src/docs/plugins/module-plugins.mdx @@ -31,18 +31,17 @@ plugins: ``` ```yaml title=.golangci.yml -linters-settings: - custom: - foo: - type: "module" - description: This is an example usage of a plugin linter. - settings: - message: hello - linters: - disable-all: true + default: none enable: - foo + settings: + custom: + foo: + type: "module" + description: This is an example usage of a plugin linter. + settings: + message: hello ``` ## The Manual Way @@ -56,18 +55,17 @@ linters: ### Configuration Example ```yaml title=.golangci.yml -linters-settings: - custom: - foo: - type: "module" - description: This is an example usage of a plugin linter. - settings: - message: hello - linters: - disable-all: true + default: none enable: - foo + settings: + custom: + foo: + type: "module" + description: This is an example usage of a plugin linter. + settings: + message: hello ``` ## Reference diff --git a/docs/src/docs/usage/false-positives.mdx b/docs/src/docs/usage/false-positives.mdx index d01cdc9a13b2..4d6b967ef131 100644 --- a/docs/src/docs/usage/false-positives.mdx +++ b/docs/src/docs/usage/false-positives.mdx @@ -17,12 +17,13 @@ Otherwise, some linters have dedicated configuration to exclude or disable rules An example with `staticcheck`: ```yaml -linters-settings: - staticcheck: - checks: - - all - - '-SA1000' # disable the rule SA1000 - - '-SA1004' # disable the rule SA1004 +linters: + settings: + staticcheck: + checks: + - all + - '-SA1000' # disable the rule SA1000 + - '-SA1004' # disable the rule SA1004 ``` ## Exclude or Skip @@ -33,90 +34,83 @@ Exclude issue by text using command-line option `-e` or config option `issues.ex It's helpful when you decided to ignore all issues of this type. Also, you can use `issues.exclude-rules` config option for per-path or per-linter configuration. -In the following example, all the reports that contains the sentences defined in `exclude` are excluded: - -```yaml -issues: - exclude: - - "Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*printf?|os\\.(Un)?Setenv). is not checked" - - "exported (type|method|function) (.+) should have comment or be unexported" - - "ST1000: at least one file in a package should have a package comment" -``` - In the following example, all the reports from the linters (`linters`) that contains the text (`text`) are excluded: ```yaml -issues: - exclude-rules: - - linters: - - mnd - text: "Magic number: 9" +linters: + exclusions: + rules: + - linters: + - mnd + text: "Magic number: 9" ``` In the following example, all the reports from the linters (`linters`) that originated from the source (`source`) are excluded: ```yaml -issues: - exclude-rules: - - linters: - - lll - source: "^//go:generate " +linters: + exclusions: + rules: + - linters: + - lll + source: "^//go:generate " ``` In the following example, all the reports that contains the text (`text`) in the path (`path`) are excluded: ```yaml -issues: - exclude-rules: - - path: path/to/a/file.go - text: "string `example` has (\\d+) occurrences, make it a constant" +linters: + exclusions: + rules: + - path: path/to/a/file.go + text: "string `example` has (\\d+) occurrences, make it a constant" ``` ### Exclude Issues by Path -Exclude issues in path by `issues.exclude-dirs`, `issues.exclude-files` or `issues.exclude-rules` config options. - -Beware that the paths that get matched here are relative to the current working directory. -When the configuration contains path patterns that check for specific directories, -the `--path-prefix` parameter can be used to extend the paths before matching. +Exclude issues in path by `linters.exclusions.paths`, or `issues.exclude-rules` config options. In the following example, all the reports from the linters (`linters`) that concerns the path (`path`) are excluded: ```yaml -issues: - exclude-rules: - - path: '(.+)_test\.go' - linters: - - funlen - - goconst +linters: + exclusions: + rules: + - path: '(.+)_test\.go' + linters: + - funlen + - goconst ``` The opposite, excluding reports **except** for specific paths, is also possible. In the following example, only test files get checked: ```yaml -issues: - exclude-rules: - - path-except: '(.+)_test\.go' - linters: - - funlen - - goconst +linters: + exclusions: + rules: + - path-except: '(.+)_test\.go' + linters: + - funlen + - goconst ``` -In the following example, all the reports related to the files (`exclude-files`) are excluded: +In the following example, all the reports related to the files (`paths`) are excluded: ```yaml -issues: - exclude-files: - - path/to/a/file.go +linters: + exclusions: + paths: + - path/to/a/file.go ``` -In the following example, all the reports related to the directories (`exclude-dirs`) are excluded: +In the following example, all the reports related to the directories (`paths`) are excluded: ```yaml issues: - exclude-dirs: - - path/to/a/dir/ + exclusions: + paths: + - path/to/a/dir/ ``` ## Nolint Directive From d429bc394cd2e14232982b6dbe6124cf372cdd41 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Tue, 25 Mar 2025 17:56:27 +0100 Subject: [PATCH 2/4] review --- docs/src/docs/usage/false-positives.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/src/docs/usage/false-positives.mdx b/docs/src/docs/usage/false-positives.mdx index 4d6b967ef131..3a489d7560ab 100644 --- a/docs/src/docs/usage/false-positives.mdx +++ b/docs/src/docs/usage/false-positives.mdx @@ -3,7 +3,6 @@ title: False Positives --- False positives are inevitable, but we did our best to reduce their count. -For example, we have a default enabled set of [exclude patterns](/usage/configuration#command-line-options). If a false positive occurred, you have the several choices. @@ -26,13 +25,11 @@ linters: - '-SA1004' # disable the rule SA1004 ``` -## Exclude or Skip +## Exclude ### Exclude Issue by Text -Exclude issue by text using command-line option `-e` or config option `issues.exclude`. -It's helpful when you decided to ignore all issues of this type. -Also, you can use `issues.exclude-rules` config option for per-path or per-linter configuration. +You can use `linters.exclusions.rules` config option for per-path or per-linter configuration. In the following example, all the reports from the linters (`linters`) that contains the text (`text`) are excluded: @@ -68,7 +65,7 @@ linters: ### Exclude Issues by Path -Exclude issues in path by `linters.exclusions.paths`, or `issues.exclude-rules` config options. +Exclude issues in path by `linters.exclusions.paths` or `linters.exclusions.rules` config options. In the following example, all the reports from the linters (`linters`) that concerns the path (`path`) are excluded: @@ -107,7 +104,7 @@ linters: In the following example, all the reports related to the directories (`paths`) are excluded: ```yaml -issues: +linters: exclusions: paths: - path/to/a/dir/ From 80c45e7a901a5387a42cca47afc34641ad031d85 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Tue, 25 Mar 2025 18:02:26 +0100 Subject: [PATCH 3/4] review --- docs/src/docs/plugins/go-plugins.mdx | 4 +++- docs/src/docs/plugins/module-plugins.mdx | 8 ++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/src/docs/plugins/go-plugins.mdx b/docs/src/docs/plugins/go-plugins.mdx index 9142db39d049..5ba8f9324b9e 100644 --- a/docs/src/docs/plugins/go-plugins.mdx +++ b/docs/src/docs/plugins/go-plugins.mdx @@ -48,8 +48,10 @@ An example linter can be found at [here](https://github.com/golangci/example-plu If you're looking for instructions on how to configure your own custom linter, they can be found further down. 1. If the project you want to lint does not have one already, copy the [.golangci.yml](https://github.com/golangci/golangci-lint/blob/HEAD/.golangci.yml) to the root directory. -2. Adjust the YAML to appropriate `linters-settings.custom` entries as so: +2. Adjust the YAML to appropriate `linters.settings.custom` entries as so: ```yaml title=.golangci.yml + version: "2" + linters: settings: custom: diff --git a/docs/src/docs/plugins/module-plugins.mdx b/docs/src/docs/plugins/module-plugins.mdx index 17c5ee98fd22..9fa36766ebb6 100644 --- a/docs/src/docs/plugins/module-plugins.mdx +++ b/docs/src/docs/plugins/module-plugins.mdx @@ -8,7 +8,7 @@ An example linter can be found at [here](https://github.com/golangci/example-plu - Define your building configuration into `.custom-gcl.yml`. - Run the command `golangci-lint custom` (or `golangci-lint custom -v` to have logs). -- Define the plugin inside the `linters-settings.custom` section with the type `module`. +- Define the plugin inside the `linters.settings.custom` section with the type `module`. - Run your custom version of golangci-lint. Requirements: @@ -31,6 +31,8 @@ plugins: ``` ```yaml title=.golangci.yml +version: "2" + linters: default: none enable: @@ -49,12 +51,14 @@ linters: - Add a blank-import of your module inside `cmd/golangci-lint/plugins.go`. - Run `go mod tidy` (the module containing the plugin will be imported). - Run `make build`. -- Define the plugin inside the configuration `linters-settings.custom` section with the type `module`. +- Define the plugin inside the `linters.settings.custom` section with the type `module`. - Run your custom version of golangci-lint. ### Configuration Example ```yaml title=.golangci.yml +version: "2" + linters: default: none enable: From 22a5b944f4593083592bfe471ce176b249cf391e Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Tue, 25 Mar 2025 18:18:28 +0100 Subject: [PATCH 4/4] review --- docs/src/docs/plugins/go-plugins.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/docs/plugins/go-plugins.mdx b/docs/src/docs/plugins/go-plugins.mdx index 5ba8f9324b9e..ce742b9bc62c 100644 --- a/docs/src/docs/plugins/go-plugins.mdx +++ b/docs/src/docs/plugins/go-plugins.mdx @@ -71,9 +71,9 @@ That is all the configuration that is required to run a custom linter in your pr Custom linters are enabled by default, but abide by the same rules as other linters. -If the disable all option is specified either on command line or in `.golang.yml` files `linters.disable-all: true`, custom linters will be disabled; +If the disable all option is specified either on command line or in `.golangci.yml` files `linters.default: none`, custom linters will be disabled; they can be re-enabled by adding them to the `linters.enable` list, or providing the enabled option on the command line, `golangci-lint run -Eexample`. -The configuration inside the `settings` field of linter have some limitations (there are NOT related to the plugin system itself): +The configuration inside the `linters.settings` field of linter have some limitations (there are NOT related to the plugin system itself): we use Viper to handle the configuration but Viper put all the keys in lowercase, and `.` cannot be used inside a key.