Why does .golangci.reference.yml use non-default values, and can this be changed?

[rostislaved]

When I need to create a golangci-lint.yaml for my projects, I copy .golangci.reference.yml, delete what I don’t need, and keep only what I do. Anything I remove falls back to the tool’s defaults.

The problem comes when I upgrade golangci-lint (and the config). It’s hard to see what actually changed since last time: the diff is huge because I removed a lot in the initial pass.

Ideally, I wouldn’t delete anything; I’d leave all options explicitly set to their default values, so future diffs only show real changes. But the values in .golangci.reference.yml are not the defaults—they’re arbitrary/non-default—so that ideal workflow isn’t possible.

My questions:

1. What was the motivation for using non-default values in .golangci.reference.yml?
2. Could the reference file be changed to reflect the true defaults (or could you provide a separate, machine-readable “defaults” reference), so users can keep explicit defaults without diverging from actual behavior?

[ldez]

This file is not a configuration example, but a documentation.

https://github.com/golangci/golangci-lint/blob/fb3e4b2fb1ea3262448b01753a7125b83933eea2/.golangci.reference.yml#L1C1-L5C77

The reference should not be used as a basis for configuration.

The goal is not to define default values, but to expose all possible options.

In most cases, you don't need to configure a linter.
The settings are only here if you want to change the default values.

We don't want to provide a configuration example because there is no real default configuration: the enable linters and their settings must be specific to each project.

[ldez]

By reading the changelog.

[rostislaved]

Exactly! If you’ve skipped several versions of golangci-lint, you’d have to read through all the changelogs to catch it. And you'd basically have to be a linter enthusiast to actually do that - which most people aren't. Typically, people just bump the version number and never find out about some new check that could’ve been useful.

This could be made simpler if .golangci.reference.yml included the default values. Just to double-check - would that somehow make the file worse or break anything? To me, this seems like a change with no downsides.

[ldez]

.golangci.reference.yml already includes the default values.

The reference will never be a configuration example or a default-only configuration, and we will not create a default-only file.
I will not repeat what I already said.

If you want to play with diff, use the JSONSchemas.

[alexandear]

If so, maybe it would be useful to have an additional file that serves specifically as an example configuration?

You can use example configurations from @ccoVeille: https://github.com/ccoVeille/golangci-lint-config-examples

[rostislaved]

@alexandear thank you! I liked the Daredevil version :)

I also started maintaining my own config. It's basically everything turned on, with some linters turned off. I have many microservices, and it's a burden to maintain different configs in each repository, so there's only one repository with the config that's used in every microservice.