Make it more clear that golangci-lint run --fix will lint *and* format

[MadLittleMods]

Make it more clear that golangci-lint run --fix will lint and format

Spawning from my confusion in golangci/golangci-lint-action#1304 (comment)

Dev notes

Seems to be a common confusion: #5997

[boring-cyborg]

Hey, thank you for opening your first Pull Request !

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[ldez]

I will not accept the PR because:

• run doesn't "format" the code.
• A section already exists to explain the behavior: https://golangci-lint.run/docs/configuration/cli/#run

[MadLittleMods]

hmm, formatting only happens when using the --fix option (golangci-lint run --fix)

Note

This command executes enabled linters, and the formatters defined in formatters,
but it does not format the code.

To only format code, use golangci-lint fmt.
To apply both linter fixes and formatting, use golangci-lint run --fix.

-- docs/content/docs/configuration/cli.md#L16-L18

[ldez]

This note has been added because some users were confused.

run doesn't format the code, even with --fix, it only applies suggested fixes.

I know this can be seen as a semantic nitpick, but this is important, especially when users are not native English speakers, to have clear concepts.

Sometimes it's better not to be exhaustive when you are explaining a topic, because the details can create more confusion.

Documenting always involves finding a balance between exhaustiveness and ease of understanding.

There is no silver bullet even inside documentation 😄

[MadLittleMods]

@ldez The information is available in the docs 👍

Definitely could be chalked up to a case of "read the manual" type of thing so I understand push back on this.

I still feel like there is a blindspot here as a consumer who did reference the docs site to pick a set of linters and formatters and tried to navigate the CLI surface (golangci-lint --help). I did not reference the specific CLI docs page to notice the blue note explaining the nuance here.

To explain my journey:

1. Reference the docs site to create a simple .golangci.yml (default linters and a few formatters)
2. Look at the commands available:

   $ golangci-lint --help
   Smart, fast linters runner.
   
   Usage:
     golangci-lint [flags]
     golangci-lint [command]
   
   Available Commands:
     [...]
     fmt         Format Go source files.
     [...]
     run         Lint the code.
     [...]

3. Write a local developer linting script that does golangci-lint fmt ./... (to "Format Go source files") and golangci-lint run ./... ("Lint the code.")
4. Notice some of my linters rules aren't being auto-fixed as indicated on the docs site
5. Update lint script to be golangci-lint fmt ./... (to "Format Go source files") and golangci-lint run ./... --fix ("Lint the code." and auto-fix the rules it can)
6. Things work
7. Try to incorporate this in CI with golangci/golangci-lint-action
8. Run into my own confusion

Something to update

At the very-least we can update the --fix Fix found issues (if it's supported by the linter) help string to point out that it also runs the formatters. But I would not have dove that deep into the CLI help to find those specifics (golangci-lint run --help).

It would be nice if we could make this more clear from the top-level help or something. Any good ideas?

[ldez]

At the very-least we can update the --fix Fix found issues (if it's supported by the linter) help string to point out that it also runs the formatters

This can be improved.

It would be nice if we could make this more clear from the top-level help or something. Any good ideas?

I think this will create more confusion because this is not straightforward to explain.
And so, a detail will take up more space than the main subject.

[ldez]

#6175

[MadLittleMods]

👍 It's better than nothing but would not have prevented my journey

Thanks for talking this through @ldez 🙂

[MadLittleMods]

run doesn't format the code, even with --fix, it only applies suggested fixes.

I'm only catching this comment now but even more confused on the distinction 😅

Could I get a clear breakdown of how I can write an exhaustive lint script?

Based on that comment, I guess I need to keep both golangci-lint fmt ./... and golangci-lint run ./... --fix in my lint script.

And then for CI, is golangci/golangci-lint-action actually sufficient? Ideally, I would want it to catch any formatting/autofix difference (to call out someone who forget to run the lint script)

[ldez]

Could I get a clear breakdown of how I can write an exhaustive lint script?

The formatters are "converted" into linters when using the run command.

This is context; the formatters will produce suggested fixes.

golangci-lint run --fix will be the equivalent of running golangci-lint fmt.
But we cannot say that the run command is formatting the code.

[ldez]

In summary:

The run command will run linters (from the configuration file and the flags) and all explicitly defined formatters (from the configuration file only), and the flag --fix will apply suggested fixes from linters (if they produce suggested fixes) and suggested fixes from formatters (they always produce suggested fixes).

[MadLittleMods]

Ahh, perfect! Understandable 🙇