Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
+3 −3
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/data/cli_help.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"defaultEnabledLinters": "Enabled by default linters:\nerrcheck: Errcheck is a program for checking for unchecked errors in Go code. These unchecked errors can be critical bugs in some cases.\ngovet: Vet examines Go source code and reports suspicious constructs. It is roughly the same as 'go vet' and uses its passes. [auto-fix]\nineffassign: Detects when assignments to existing variables are not used. [fast]\nstaticcheck: It's the set of rules from staticcheck. [auto-fix]\nunused: Checks Go code for unused constants, variables, functions and types.",
"rootOutput": "Smart, fast linters runner.\n\nUsage:\n golangci-lint [flags]\n golangci-lint [command]\n\nAvailable Commands:\n cache Cache control and information.\n completion Generate the autocompletion script for the specified shell\n config Configuration file information and verification.\n custom Build a version of golangci-lint with custom linters.\n fmt Format Go source files.\n formatters List current formatters configuration.\n help Display extra help\n linters List current linters configuration.\n migrate Migrate configuration file from v1 to v2.\n run Lint the code.\n version Display the golangci-lint version.\n\nFlags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n --version Print version\n\nUse \"golangci-lint [command] --help\" for more information about a command.\n",
"runOutput": "Lint the code.\n\nUsage:\n golangci-lint run [flags]\n\nFlags:\n -c, --config PATH Read config from file path PATH\n --no-config Don't read config file\n --default string Default set of linters to enable (default \"standard\")\n -D, --disable strings Disable specific linter\n -E, --enable strings Enable specific linter\n --enable-only strings Override linters configuration section to only run the specific linter(s)\n --fast-only Filter enabled linters to run only fast linters\n -j, --concurrency int Number of CPUs to use (Default: Automatically set to match Linux container CPU quota and fall back to the number of logical CPUs in the machine)\n --modules-download-mode string Modules download mode. If not empty, passed as -mod=\u003cmode\u003e to go tools\n --issues-exit-code int Exit code when issues were found (default 1)\n --build-tags strings Build tags\n --timeout duration Timeout for total work. Disabled by default\n --tests Analyze tests (*_test.go) (default true)\n --allow-parallel-runners Allow multiple parallel golangci-lint instances running.\n If false (default) - golangci-lint acquires file lock on start.\n --allow-serial-runners Allow multiple golangci-lint instances running, but serialize them around a lock.\n If false (default) - golangci-lint exits with an error if it fails to acquire file lock on start.\n --path-prefix string Path prefix to add to output\n --path-mode string Path mode to use (empty, or 'abs')\n --show-stats Show statistics per linter (default true)\n --output.text.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.text.print-linter-name Print linter name in the end of issue text. (default true)\n --output.text.print-issued-lines Print lines of code with issue. (default true)\n --output.text.colors Use colors. (default true)\n --output.json.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.tab.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.tab.print-linter-name Print linter name in the end of issue text. (default true)\n --output.tab.colors Use colors. (default true)\n --output.html.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.checkstyle.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.code-climate.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.junit-xml.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.junit-xml.extended Support extra JUnit XML fields.\n --output.teamcity.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.sarif.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --max-issues-per-linter int Maximum issues count per one linter. Set to 0 to disable (default 50)\n --max-same-issues int Maximum count of issues with the same text. Set to 0 to disable (default 3)\n --uniq-by-line Make issues output unique by line (default true)\n -n, --new Show only new issues: if there are unstaged changes or untracked files, only those changes are analyzed, else only changes in HEAD~ are analyzed.\n It's a super-useful option for integration of golangci-lint into existing large codebase.\n It's not practical to fix all existing issues at the moment of integration: much better to not allow issues in new code.\n For CI setups, prefer --new-from-rev=HEAD~, as --new can skip linting the current patch if any scripts generate unstaged files before golangci-lint runs.\n --new-from-rev REV Show only new issues created after git revision REV\n --new-from-patch PATH Show only new issues created in git patch with file path PATH\n --new-from-merge-base string Show only new issues created after the best common ancestor (merge-base against HEAD)\n --whole-files Show issues in any part of update files (requires new-from-rev or new-from-patch)\n --fix Fix found issues (if it's supported by the linter)\n --cpu-profile-path string Path to CPU profile output file\n --mem-profile-path string Path to memory profile output file\n --trace-path string Path to trace output file\n\nGlobal Flags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n",
"rootOutput": "Smart, fast linters runner.\n\nUsage:\n golangci-lint [flags]\n golangci-lint [command]\n\nAvailable Commands:\n cache Cache control and information.\n completion Generate the autocompletion script for the specified shell\n config Configuration file information and verification.\n custom Build a version of golangci-lint with custom linters.\n fmt Format Go source files.\n formatters List current formatters configuration.\n help Display extra help\n linters List current linters configuration.\n migrate Migrate configuration file from v1 to v2.\n run Lint and format the code.\n version Display the golangci-lint version.\n\nFlags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n --version Print version\n\nUse \"golangci-lint [command] --help\" for more information about a command.\n",
"runOutput": "Lint and format the code.\n\nUsage:\n golangci-lint run [flags]\n\nFlags:\n -c, --config PATH Read config from file path PATH\n --no-config Don't read config file\n --default string Default set of linters to enable (default \"standard\")\n -D, --disable strings Disable specific linter\n -E, --enable strings Enable specific linter\n --enable-only strings Override linters configuration section to only run the specific linter(s)\n --fast-only Filter enabled linters to run only fast linters\n -j, --concurrency int Number of CPUs to use (Default: Automatically set to match Linux container CPU quota and fall back to the number of logical CPUs in the machine)\n --modules-download-mode string Modules download mode. If not empty, passed as -mod=\u003cmode\u003e to go tools\n --issues-exit-code int Exit code when issues were found (default 1)\n --build-tags strings Build tags\n --timeout duration Timeout for total work. Disabled by default\n --tests Analyze tests (*_test.go) (default true)\n --allow-parallel-runners Allow multiple parallel golangci-lint instances running.\n If false (default) - golangci-lint acquires file lock on start.\n --allow-serial-runners Allow multiple golangci-lint instances running, but serialize them around a lock.\n If false (default) - golangci-lint exits with an error if it fails to acquire file lock on start.\n --path-prefix string Path prefix to add to output\n --path-mode string Path mode to use (empty, or 'abs')\n --show-stats Show statistics per linter (default true)\n --output.text.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.text.print-linter-name Print linter name in the end of issue text. (default true)\n --output.text.print-issued-lines Print lines of code with issue. (default true)\n --output.text.colors Use colors. (default true)\n --output.json.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.tab.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.tab.print-linter-name Print linter name in the end of issue text. (default true)\n --output.tab.colors Use colors. (default true)\n --output.html.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.checkstyle.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.code-climate.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.junit-xml.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.junit-xml.extended Support extra JUnit XML fields.\n --output.teamcity.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --output.sarif.path stdout Output path can be either stdout, `stderr` or path to the file to write to.\n --max-issues-per-linter int Maximum issues count per one linter. Set to 0 to disable (default 50)\n --max-same-issues int Maximum count of issues with the same text. Set to 0 to disable (default 3)\n --uniq-by-line Make issues output unique by line (default true)\n -n, --new Show only new issues: if there are unstaged changes or untracked files, only those changes are analyzed, else only changes in HEAD~ are analyzed.\n It's a super-useful option for integration of golangci-lint into existing large codebase.\n It's not practical to fix all existing issues at the moment of integration: much better to not allow issues in new code.\n For CI setups, prefer --new-from-rev=HEAD~, as --new can skip linting the current patch if any scripts generate unstaged files before golangci-lint runs.\n --new-from-rev REV Show only new issues created after git revision REV\n --new-from-patch PATH Show only new issues created in git patch with file path PATH\n --new-from-merge-base string Show only new issues created after the best common ancestor (merge-base against HEAD)\n --whole-files Show issues in any part of update files (requires new-from-rev or new-from-patch)\n --fix Fix found issues (if it's supported by the linter)\n --cpu-profile-path string Path to CPU profile output file\n --mem-profile-path string Path to memory profile output file\n --trace-path string Path to trace output file\n\nGlobal Flags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n",
"lintersOutput": "List current linters configuration.\n\nUsage:\n golangci-lint linters [flags]\n\nFlags:\n -c, --config PATH Read config from file path PATH\n --no-config Don't read config file\n --default string Default set of linters to enable (default \"standard\")\n -D, --disable strings Disable specific linter\n -E, --enable strings Enable specific linter\n --enable-only strings Override linters configuration section to only run the specific linter(s)\n --fast-only Filter enabled linters to run only fast linters\n --json Display as JSON\n\nGlobal Flags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n",
"fmtOutput": "Format Go source files.\n\nUsage:\n golangci-lint fmt [flags]\n\nFlags:\n -c, --config PATH Read config from file path PATH\n --no-config Don't read config file\n -E, --enable strings Enable specific formatter\n -d, --diff Display diffs instead of rewriting files\n --diff-colored Display diffs instead of rewriting files (with colors)\n --stdin Use standard input for piping source files\n\nGlobal Flags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n",
"formattersOutput": "List current formatters configuration.\n\nUsage:\n golangci-lint formatters [flags]\n\nFlags:\n -c, --config PATH Read config from file path PATH\n --no-config Don't read config file\n -E, --enable strings Enable specific formatter\n --json Display as JSON\n\nGlobal Flags:\n --color string Use color when printing; can be 'always', 'auto', or 'never' (default \"auto\")\n -h, --help Help for a command\n -v, --verbose Verbose output\n",
Expand Down
2 changes: 1 addition & 1 deletion pkg/commands/run.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ func newRunCommand(logger logutils.Log, info BuildInfo) *runCommand {

runCmd := &cobra.Command{
Use: "run",
Short: "Lint the code.",
Short: "Lint and format the code.",
Copy link
Author

@MadLittleMods MadLittleMods Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@ldez ldez Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 😄

Copy link
Author

@MadLittleMods MadLittleMods Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@ldez ldez Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@ldez ldez Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#6175

Copy link
Author

@MadLittleMods MadLittleMods Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Thanks for talking this through @ldez 🙂

Copy link
Author

@MadLittleMods MadLittleMods Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Member

@ldez ldez Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@ldez ldez Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

@MadLittleMods MadLittleMods Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh, perfect! Understandable 🙇

Run: c.execute,
PreRunE: c.preRunE,
PostRun: c.postRun,
Expand Down