docs: improve .golangci.reference.yml defaults (#4271)

Co-authored-by: Fernandez Ludovic <ldez@users.noreply.github.com>

.golangci.reference.yml

@@ -6,7 +6,8 @@
 
 # Options for analysis running.
 run:
-  # The default concurrency value is the number of available CPU.
+  # Number of CPUs to use when running golangci-lint.
+  # Default: the number of logical CPUs in the machine
   concurrency: 4
 
   # Timeout for analysis, e.g. 30s, 5m.
@@ -22,16 +23,16 @@ run:
   tests: false
 
   # List of build tags, all linters use it.
-  # Default: [].
+  # Default: []
   build-tags:
     - mytag
 
   # Which dirs to skip: issues from them won't be reported.
   # Can use regexp here: `generated.*`, regexp is applied on full path,
   # including the path prefix if one is set.
-  # Default value is empty list,
+  # Default dirs are skipped independently of this option's value (see skip-dirs-use-default).
-  # but default dirs are skipped independently of this option's value (see skip-dirs-use-default).
   # "/" will be replaced by current OS file path separator to properly work on Windows.
+  # Default: []
   skip-dirs:
     - src/external_libs
     - autogenerated_by_my_lib
@@ -42,16 +43,16 @@ run:
   skip-dirs-use-default: false
 
   # Which files to skip: they will be analyzed, but issues from them won't be reported.
-  # Default value is empty list,
+  # There is no need to include all autogenerated files,
-  # but there is no need to include all autogenerated files,
   # we confidently recognize autogenerated files.
-  # If it's not please let us know.
+  # If it's not, please let us know.
   # "/" will be replaced by current OS file path separator to properly work on Windows.
+  # Default: []
   skip-files:
     - ".*\\.my\\.go$"
     - lib/bad.go
 
-  # If set we pass it to "go list -mod={option}". From "go help modules":
+  # If set, we pass it to "go list -mod={option}". From "go help modules":
   # If invoked with -mod=readonly, the go command is disallowed from the implicit
   # automatic updating of go.mod described above. Instead, it fails when any changes
   # to go.mod are needed. This setting is most useful to check that go.mod does
@@ -61,11 +62,12 @@ run:
   # the dependency descriptions in go.mod.
   #
   # Allowed values: readonly|vendor|mod
-  # By default, it isn't set.
+  # Default: ""
   modules-download-mode: readonly
 
   # Allow multiple parallel golangci-lint instances running.
-  # If false (default) - golangci-lint acquires file lock on start.
+  # If false, golangci-lint acquires file lock on start.
+  # Default: false
   allow-parallel-runners: false
 
   # Define the Go version limit.
@@ -99,11 +101,12 @@ output:
   uniq-by-line: false
 
   # Add a prefix to the output file references.
-  # Default is no prefix.
+  # Default: ""
   path-prefix: ""
 
   # Sort results by: filepath, line and column.
-  sort-results: false
+  # Default: false
+  sort-results: true
 
 
 # All available settings of specific linters.
@@ -2564,6 +2567,7 @@ linters:
 
   # Enable presets.
   # https://golangci-lint.run/usage/linters
+  # Default: []
   presets:
     - bugs
     - comment
@@ -2631,7 +2635,7 @@ issues:
   # Independently of option `exclude` we use default exclude patterns,
   # it can be disabled by this option.
   # To list all excluded by default patterns execute `golangci-lint run --help`.
-  # Default: true.
+  # Default: true
   exclude-use-default: false
 
   # If set to true exclude and exclude-rules regular expressions become case-sensitive.
@@ -2674,16 +2678,19 @@ issues:
   # It's not practical to fix all existing issues at the moment of integration:
   # much better don't allow issues in new code.
   #
-  # Default: false.
+  # Default: false
   new: true
 
   # Show only new issues created after git revision `REV`.
+  # Default: ""
   new-from-rev: HEAD
 
   # Show only new issues created in git patch with set file path.
+  # Default: ""
   new-from-patch: path/to/patch/file
 
   # Fix found issues (if it's supported by the linter).
+  # Default: false
   fix: true
 
 
@@ -2698,7 +2705,7 @@ severity:
   # - GitHub: https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-error-message
   # - TeamCity: https://www.jetbrains.com/help/teamcity/service-messages.html#Inspection+Instance
   #
-  # Default value is an empty string.
+  # Default: ""
   default-severity: error
 
   # If set to true `severity-rules` regular expressions become case-sensitive.

pkg/commands/root.go

@@ -119,7 +119,7 @@ func formatMemory(memBytes uint64) string {
 
 func getDefaultConcurrency() int {
 	if os.Getenv(envHelpRun) == "1" {
-		// Make stable concurrency for README help generating builds.
+		// Make stable concurrency for generating help documentation.
 		const prettyConcurrency = 8
 		return prettyConcurrency
 	}
@@ -165,7 +165,8 @@ func initRootFlagSet(fs *pflag.FlagSet, cfg *config.Config, needVersionOption bo
 	fs.StringVar(&cfg.Run.CPUProfilePath, "cpu-profile-path", "", wh("Path to CPU profile output file"))
 	fs.StringVar(&cfg.Run.MemProfilePath, "mem-profile-path", "", wh("Path to memory profile output file"))
 	fs.StringVar(&cfg.Run.TracePath, "trace-path", "", wh("Path to trace output file"))
-	fs.IntVarP(&cfg.Run.Concurrency, "concurrency", "j", getDefaultConcurrency(), wh("Concurrency (default NumCPU)"))
+	fs.IntVarP(&cfg.Run.Concurrency, "concurrency", "j", getDefaultConcurrency(),
+		wh("Number of CPUs to use (Default: number of logical CPUs)"))
 	if needVersionOption {
 		fs.BoolVar(&cfg.Run.PrintVersion, "version", false, wh("Print version"))
 	}

pkg/commands/run.go

@@ -35,7 +35,7 @@ const (
 )
 
 func getDefaultIssueExcludeHelp() string {
-	parts := []string{"Use or not use default excludes:"}
+	parts := []string{color.GreenString("Use or not use default excludes:")}
 	for _, ep := range config.DefaultExcludePatterns {
 		parts = append(parts,
 			fmt.Sprintf("  # %s %s: %s", ep.ID, ep.Linter, ep.Why),
@@ -47,7 +47,7 @@ func getDefaultIssueExcludeHelp() string {
 }
 
 func getDefaultDirectoryExcludeHelp() string {
-	parts := []string{"Use or not use default excluded directories:"}
+	parts := []string{color.GreenString("Use or not use default excluded directories:")}
 	for _, dir := range packages.StdExcludeDirRegexps {
 		parts = append(parts, fmt.Sprintf("  - %s", color.YellowString(dir)))
 	}
@@ -98,7 +98,7 @@ func initFlagSet(fs *pflag.FlagSet, cfg *config.Config, m *lintersdb.Manager, is
 	// Run config
 	rc := &cfg.Run
 	fs.StringVar(&rc.ModulesDownloadMode, "modules-download-mode", "",
-		"Modules download mode. If not empty, passed as -mod=<mode> to go tools")
+		wh("Modules download mode. If not empty, passed as -mod=<mode> to go tools"))
 	fs.IntVar(&rc.ExitCodeIfIssuesFound, "issues-exit-code",
 		exitcodes.IssuesFound, wh("Exit code when issues were found"))
 	fs.StringVar(&rc.Go, "go", "", wh("Targeted Go version"))
@@ -203,7 +203,7 @@ func initFlagSet(fs *pflag.FlagSet, cfg *config.Config, m *lintersdb.Manager, is
 
 	fs.BoolVar(&lc.DisableAll, "disable-all", false, wh("Disable all linters"))
 	fs.StringSliceVarP(&lc.Presets, "presets", "p", nil,
-		wh(fmt.Sprintf("Enable presets (%s) of linters. Run 'golangci-lint linters' to see "+
+		wh(fmt.Sprintf("Enable presets (%s) of linters. Run 'golangci-lint help linters' to see "+
 			"them. This option implies option --disable-all", strings.Join(m.AllPresets(), "|"))))
 	fs.BoolVar(&lc.Fast, "fast", false, wh("Run only fast linters from enabled linters set (first run won't be fast)"))
 
@@ -232,7 +232,7 @@ func initFlagSet(fs *pflag.FlagSet, cfg *config.Config, m *lintersdb.Manager, is
 		wh("Show only new issues created in git patch with file path `PATH`"))
 	fs.BoolVar(&ic.WholeFiles, "whole-files", false,
 		wh("Show issues in any part of update files (requires new-from-rev or new-from-patch)"))
-	fs.BoolVar(&ic.NeedFix, "fix", false, "Fix found issues (if it's supported by the linter)")
+	fs.BoolVar(&ic.NeedFix, "fix", false, wh("Fix found issues (if it's supported by the linter)"))
 }
 
 func (e *Executor) initRunConfiguration(cmd *cobra.Command) {