.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.6.9/doc/settings.md

   1 # Settings
   2
   3 <!--TODO: Generate this file from the documentation in golang/org/x/tools/internal/lsp/source/options.go.-->
   4
   5 This document describes the global settings for `gopls` inside the editor.
   6 The settings block will be called `"gopls"` and contains a collection of
   7 controls for `gopls` that the editor is not expected to understand or control.
   8 These settings can also be configured differently per workspace folder.
   9
  10 In VSCode, this would be a section in your `settings.json` file that might look
  11 like this:
  12
  13 ```json5
  14   "gopls": {
  15     "ui.completion.usePlaceholders": true,
  16      ...
  17   },
  18 ```
  19
  20 ## Officially supported
  21
  22 Below is the list of settings that are officially supported for `gopls`.
  23
  24 Any settings that are experimental or for debugging purposes are marked as
  25 such.
  26
  27 To enable all experimental features, use **allExperiments: `true`**. You will
  28 still be able to independently override specific experimental features.
  29
  30 <!-- BEGIN User: DO NOT MANUALLY EDIT THIS SECTION -->
  31
  32 * [Build](#build)
  33 * [Formatting](#formatting)
  34 * [UI](#ui)
  35   * [Completion](#completion)
  36   * [Diagnostic](#diagnostic)
  37   * [Documentation](#documentation)
  38   * [Navigation](#navigation)
  39
  40 ### Build
  41
  42 #### **buildFlags** *[]string*
  43
  44 buildFlags is the set of flags passed on to the build system when invoked.
  45 It is applied to queries like `go list`, which is used when discovering files.
  46 The most common use is to set `-tags`.
  47
  48 Default: `[]`.
  49
  50 #### **env** *map[string]string*
  51
  52 env adds environment variables to external commands run by `gopls`, most notably `go list`.
  53
  54 Default: `{}`.
  55
  56 #### **directoryFilters** *[]string*
  57
  58 directoryFilters can be used to exclude unwanted directories from the
  59 workspace. By default, all directories are included. Filters are an
  60 operator, `+` to include and `-` to exclude, followed by a path prefix
  61 relative to the workspace folder. They are evaluated in order, and
  62 the last filter that applies to a path controls whether it is included.
  63 The path prefix can be empty, so an initial `-` excludes everything.
  64
  65 Examples:
  66 Exclude node_modules: `-node_modules`
  67 Include only project_a: `-` (exclude everything), `+project_a`
  68 Include only project_a, but not node_modules inside it: `-`, `+project_a`, `-project_a/node_modules`
  69
  70 Default: `[]`.
  71
  72 #### **expandWorkspaceToModule** *bool*
  73
  74 **This setting is experimental and may be deleted.**
  75
  76 expandWorkspaceToModule instructs `gopls` to adjust the scope of the
  77 workspace to find the best available module root. `gopls` first looks for
  78 a go.mod file in any parent directory of the workspace folder, expanding
  79 the scope to that directory if it exists. If no viable parent directory is
  80 found, gopls will check if there is exactly one child directory containing
  81 a go.mod file, narrowing the scope to that directory if it exists.
  82
  83 Default: `true`.
  84
  85 #### **experimentalWorkspaceModule** *bool*
  86
  87 **This setting is experimental and may be deleted.**
  88
  89 experimentalWorkspaceModule opts a user into the experimental support
  90 for multi-module workspaces.
  91
  92 Default: `false`.
  93
  94 #### **experimentalPackageCacheKey** *bool*
  95
  96 **This setting is experimental and may be deleted.**
  97
  98 experimentalPackageCacheKey controls whether to use a coarser cache key
  99 for package type information to increase cache hits. This setting removes
 100 the user's environment, build flags, and working directory from the cache
 101 key, which should be a safe change as all relevant inputs into the type
 102 checking pass are already hashed into the key. This is temporarily guarded
 103 by an experiment because caching behavior is subtle and difficult to
 104 comprehensively test.
 105
 106 Default: `true`.
 107
 108 #### **allowModfileModifications** *bool*
 109
 110 **This setting is experimental and may be deleted.**
 111
 112 allowModfileModifications disables -mod=readonly, allowing imports from
 113 out-of-scope modules. This option will eventually be removed.
 114
 115 Default: `false`.
 116
 117 #### **allowImplicitNetworkAccess** *bool*
 118
 119 **This setting is experimental and may be deleted.**
 120
 121 allowImplicitNetworkAccess disables GOPROXY=off, allowing implicit module
 122 downloads rather than requiring user action. This option will eventually
 123 be removed.
 124
 125 Default: `false`.
 126
 127 ### Formatting
 128
 129 #### **local** *string*
 130
 131 local is the equivalent of the `goimports -local` flag, which puts
 132 imports beginning with this string after third-party packages. It should
 133 be the prefix of the import path whose imports should be grouped
 134 separately.
 135
 136 Default: `""`.
 137
 138 #### **gofumpt** *bool*
 139
 140 gofumpt indicates if we should run gofumpt formatting.
 141
 142 Default: `false`.
 143
 144 ### UI
 145
 146 #### **codelenses** *map[string]bool*
 147
 148 codelenses overrides the enabled/disabled state of code lenses. See the
 149 "Code Lenses" section of the
 150 [Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md)
 151 for the list of supported lenses.
 152
 153 Example Usage:
 154
 155 ```json5
 156 "gopls": {
 157 ...
 158   "codelens": {
 159     "generate": false,  // Don't show the `go generate` lens.
 160     "gc_details": true  // Show a code lens toggling the display of gc's choices.
 161   }
 162 ...
 163 }
 164 ```
 165
 166 Default: `{"gc_details":false,"generate":true,"regenerate_cgo":true,"tidy":true,"upgrade_dependency":true,"vendor":true}`.
 167
 168 #### **semanticTokens** *bool*
 169
 170 **This setting is experimental and may be deleted.**
 171
 172 semanticTokens controls whether the LSP server will send
 173 semantic tokens to the client.
 174
 175 Default: `false`.
 176
 177 #### Completion
 178
 179 ##### **usePlaceholders** *bool*
 180
 181 placeholders enables placeholders for function parameters or struct
 182 fields in completion responses.
 183
 184 Default: `false`.
 185
 186 ##### **completionBudget** *time.Duration*
 187
 188 **This setting is for debugging purposes only.**
 189
 190 completionBudget is the soft latency goal for completion requests. Most
 191 requests finish in a couple milliseconds, but in some cases deep
 192 completions can take much longer. As we use up our budget we
 193 dynamically reduce the search scope to ensure we return timely
 194 results. Zero means unlimited.
 195
 196 Default: `"100ms"`.
 197
 198 ##### **matcher** *enum*
 199
 200 **This is an advanced setting and should not be configured by most `gopls` users.**
 201
 202 matcher sets the algorithm that is used when calculating completion
 203 candidates.
 204
 205 Must be one of:
 206
 207 * `"CaseInsensitive"`
 208 * `"CaseSensitive"`
 209 * `"Fuzzy"`
 210 Default: `"Fuzzy"`.
 211
 212 #### Diagnostic
 213
 214 ##### **analyses** *map[string]bool*
 215
 216 analyses specify analyses that the user would like to enable or disable.
 217 A map of the names of analysis passes that should be enabled/disabled.
 218 A full list of analyzers that gopls uses can be found
 219 [here](https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md).
 220
 221 Example Usage:
 222
 223 ```json5
 224 ...
 225 "analyses": {
 226   "unreachable": false, // Disable the unreachable analyzer.
 227   "unusedparams": true  // Enable the unusedparams analyzer.
 228 }
 229 ...
 230 ```
 231
 232 Default: `{}`.
 233
 234 ##### **staticcheck** *bool*
 235
 236 **This setting is experimental and may be deleted.**
 237
 238 staticcheck enables additional analyses from staticcheck.io.
 239
 240 Default: `false`.
 241
 242 ##### **annotations** *map[string]bool*
 243
 244 **This setting is experimental and may be deleted.**
 245
 246 annotations specifies the various kinds of optimization diagnostics
 247 that should be reported by the gc_details command.
 248
 249 Can contain any of:
 250
 251 * `"bounds"` controls bounds checking diagnostics.
 252
 253 * `"escape"` controls diagnostics about escape choices.
 254
 255 * `"inline"` controls diagnostics about inlining choices.
 256
 257 * `"nil"` controls nil checks.
 258
 259 Default: `{"bounds":true,"escape":true,"inline":true,"nil":true}`.
 260
 261 ##### **experimentalDiagnosticsDelay** *time.Duration*
 262
 263 **This setting is experimental and may be deleted.**
 264
 265 experimentalDiagnosticsDelay controls the amount of time that gopls waits
 266 after the most recent file modification before computing deep diagnostics.
 267 Simple diagnostics (parsing and type-checking) are always run immediately
 268 on recently modified packages.
 269
 270 This option must be set to a valid duration string, for example `"250ms"`.
 271
 272 Default: `"250ms"`.
 273
 274 #### Documentation
 275
 276 ##### **hoverKind** *enum*
 277
 278 hoverKind controls the information that appears in the hover text.
 279 SingleLine and Structured are intended for use only by authors of editor plugins.
 280
 281 Must be one of:
 282
 283 * `"FullDocumentation"`
 284 * `"NoDocumentation"`
 285 * `"SingleLine"`
 286 * `"Structured"` is an experimental setting that returns a structured hover format.
 287 This format separates the signature from the documentation, so that the client
 288 can do more manipulation of these fields.\
 289 This should only be used by clients that support this behavior.
 290
 291 * `"SynopsisDocumentation"`
 292 Default: `"FullDocumentation"`.
 293
 294 ##### **linkTarget** *string*
 295
 296 linkTarget controls where documentation links go.
 297 It might be one of:
 298
 299 * `"godoc.org"`
 300 * `"pkg.go.dev"`
 301
 302 If company chooses to use its own `godoc.org`, its address can be used as well.
 303
 304 Default: `"pkg.go.dev"`.
 305
 306 ##### **linksInHover** *bool*
 307
 308 linksInHover toggles the presence of links to documentation in hover.
 309
 310 Default: `true`.
 311
 312 #### Navigation
 313
 314 ##### **importShortcut** *enum*
 315
 316 importShortcut specifies whether import statements should link to
 317 documentation or go to definitions.
 318
 319 Must be one of:
 320
 321 * `"Both"`
 322 * `"Definition"`
 323 * `"Link"`
 324 Default: `"Both"`.
 325
 326 ##### **symbolMatcher** *enum*
 327
 328 **This is an advanced setting and should not be configured by most `gopls` users.**
 329
 330 symbolMatcher sets the algorithm that is used when finding workspace symbols.
 331
 332 Must be one of:
 333
 334 * `"CaseInsensitive"`
 335 * `"CaseSensitive"`
 336 * `"Fuzzy"`
 337 Default: `"Fuzzy"`.
 338
 339 ##### **symbolStyle** *enum*
 340
 341 **This is an advanced setting and should not be configured by most `gopls` users.**
 342
 343 symbolStyle controls how symbols are qualified in symbol responses.
 344
 345 Example Usage:
 346
 347 ```json5
 348 "gopls": {
 349 ...
 350   "symbolStyle": "dynamic",
 351 ...
 352 }
 353 ```
 354
 355 Must be one of:
 356
 357 * `"Dynamic"` uses whichever qualifier results in the highest scoring
 358 match for the given symbol query. Here a "qualifier" is any "/" or "."
 359 delimited suffix of the fully qualified symbol. i.e. "to/pkg.Foo.Field" or
 360 just "Foo.Field".
 361
 362 * `"Full"` is fully qualified symbols, i.e.
 363 "path/to/pkg.Foo.Field".
 364
 365 * `"Package"` is package qualified symbols i.e.
 366 "pkg.Foo.Field".
 367
 368 Default: `"Dynamic"`.
 369
 370 #### **verboseOutput** *bool*
 371
 372 **This setting is for debugging purposes only.**
 373
 374 verboseOutput enables additional debug logging.
 375
 376 Default: `false`.
 377
 378 <!-- END User: DO NOT MANUALLY EDIT THIS SECTION -->
 379
 380 ## Code Lenses
 381
 382 These are the code lenses that `gopls` currently supports. They can be enabled
 383 and disabled using the `codelenses` setting, documented above. Their names and
 384 features are subject to change.
 385
 386 <!-- BEGIN Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
 387 ### **Toggle gc_details**
 388
 389 Identifier: `gc_details`
 390
 391 Toggle the calculation of gc annotations.
 392 ### **Run go generate**
 393
 394 Identifier: `generate`
 395
 396 Runs `go generate` for a given directory.
 397 ### **Regenerate cgo**
 398
 399 Identifier: `regenerate_cgo`
 400
 401 Regenerates cgo definitions.
 402 ### **Run test(s) (legacy)**
 403
 404 Identifier: `test`
 405
 406 Runs `go test` for a specific set of test or benchmark functions.
 407 ### **Run go mod tidy**
 408
 409 Identifier: `tidy`
 410
 411 Runs `go mod tidy` for a module.
 412 ### **Upgrade dependency**
 413
 414 Identifier: `upgrade_dependency`
 415
 416 Upgrades a dependency in the go.mod file for a module.
 417 ### **Run go mod vendor**
 418
 419 Identifier: `vendor`
 420
 421 Runs `go mod vendor` for a module.
 422 <!-- END Lenses: DO NOT MANUALLY EDIT THIS SECTION -->