golang.org/x/tools/gopls@v0.15.3/doc/settings.md (about)

     1  # Settings
     2  
     3  <!--TODO: Generate this file from the documentation in golang.org/x/tools/gopls/internal/golang/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    * [Inlayhint](#inlayhint)
    39    * [Navigation](#navigation)
    40  
    41  ### Build
    42  
    43  #### **buildFlags** *[]string*
    44  
    45  buildFlags is the set of flags passed on to the build system when invoked.
    46  It is applied to queries like `go list`, which is used when discovering files.
    47  The most common use is to set `-tags`.
    48  
    49  Default: `[]`.
    50  
    51  #### **env** *map[string]string*
    52  
    53  env adds environment variables to external commands run by `gopls`, most notably `go list`.
    54  
    55  Default: `{}`.
    56  
    57  #### **directoryFilters** *[]string*
    58  
    59  directoryFilters can be used to exclude unwanted directories from the
    60  workspace. By default, all directories are included. Filters are an
    61  operator, `+` to include and `-` to exclude, followed by a path prefix
    62  relative to the workspace folder. They are evaluated in order, and
    63  the last filter that applies to a path controls whether it is included.
    64  The path prefix can be empty, so an initial `-` excludes everything.
    65  
    66  DirectoryFilters also supports the `**` operator to match 0 or more directories.
    67  
    68  Examples:
    69  
    70  Exclude node_modules at current depth: `-node_modules`
    71  
    72  Exclude node_modules at any depth: `-**/node_modules`
    73  
    74  Include only project_a: `-` (exclude everything), `+project_a`
    75  
    76  Include only project_a, but not node_modules inside it: `-`, `+project_a`, `-project_a/node_modules`
    77  
    78  Default: `["-**/node_modules"]`.
    79  
    80  #### **templateExtensions** *[]string*
    81  
    82  templateExtensions gives the extensions of file names that are treateed
    83  as template files. (The extension
    84  is the part of the file name after the final dot.)
    85  
    86  Default: `[]`.
    87  
    88  #### **memoryMode** *string*
    89  
    90  **This setting is experimental and may be deleted.**
    91  
    92  obsolete, no effect
    93  
    94  Default: `""`.
    95  
    96  #### **expandWorkspaceToModule** *bool*
    97  
    98  **This setting is experimental and may be deleted.**
    99  
   100  expandWorkspaceToModule determines which packages are considered
   101  "workspace packages" when the workspace is using modules.
   102  
   103  Workspace packages affect the scope of workspace-wide operations. Notably,
   104  gopls diagnoses all packages considered to be part of the workspace after
   105  every keystroke, so by setting "ExpandWorkspaceToModule" to false, and
   106  opening a nested workspace directory, you can reduce the amount of work
   107  gopls has to do to keep your workspace up to date.
   108  
   109  Default: `true`.
   110  
   111  #### **allowModfileModifications** *bool*
   112  
   113  **This setting is experimental and may be deleted.**
   114  
   115  allowModfileModifications disables -mod=readonly, allowing imports from
   116  out-of-scope modules. This option will eventually be removed.
   117  
   118  Default: `false`.
   119  
   120  #### **allowImplicitNetworkAccess** *bool*
   121  
   122  **This setting is experimental and may be deleted.**
   123  
   124  allowImplicitNetworkAccess disables GOPROXY=off, allowing implicit module
   125  downloads rather than requiring user action. This option will eventually
   126  be removed.
   127  
   128  Default: `false`.
   129  
   130  #### **standaloneTags** *[]string*
   131  
   132  standaloneTags specifies a set of build constraints that identify
   133  individual Go source files that make up the entire main package of an
   134  executable.
   135  
   136  A common example of standalone main files is the convention of using the
   137  directive `//go:build ignore` to denote files that are not intended to be
   138  included in any package, for example because they are invoked directly by
   139  the developer using `go run`.
   140  
   141  Gopls considers a file to be a standalone main file if and only if it has
   142  package name "main" and has a build directive of the exact form
   143  "//go:build tag" or "// +build tag", where tag is among the list of tags
   144  configured by this setting. Notably, if the build constraint is more
   145  complicated than a simple tag (such as the composite constraint
   146  `//go:build tag && go1.18`), the file is not considered to be a standalone
   147  main file.
   148  
   149  This setting is only supported when gopls is built with Go 1.16 or later.
   150  
   151  Default: `["ignore"]`.
   152  
   153  ### Formatting
   154  
   155  #### **local** *string*
   156  
   157  local is the equivalent of the `goimports -local` flag, which puts
   158  imports beginning with this string after third-party packages. It should
   159  be the prefix of the import path whose imports should be grouped
   160  separately.
   161  
   162  Default: `""`.
   163  
   164  #### **gofumpt** *bool*
   165  
   166  gofumpt indicates if we should run gofumpt formatting.
   167  
   168  Default: `false`.
   169  
   170  ### UI
   171  
   172  #### **codelenses** *map[string]bool*
   173  
   174  codelenses overrides the enabled/disabled state of code lenses. See the
   175  "Code Lenses" section of the
   176  [Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#code-lenses)
   177  for the list of supported lenses.
   178  
   179  Example Usage:
   180  
   181  ```json5
   182  "gopls": {
   183  ...
   184    "codelenses": {
   185      "generate": false,  // Don't show the `go generate` lens.
   186      "gc_details": true  // Show a code lens toggling the display of gc's choices.
   187    }
   188  ...
   189  }
   190  ```
   191  
   192  Default: `{"gc_details":false,"generate":true,"regenerate_cgo":true,"tidy":true,"upgrade_dependency":true,"vendor":true}`.
   193  
   194  #### **semanticTokens** *bool*
   195  
   196  **This setting is experimental and may be deleted.**
   197  
   198  semanticTokens controls whether the LSP server will send
   199  semantic tokens to the client.
   200  
   201  Default: `false`.
   202  
   203  #### **noSemanticString** *bool*
   204  
   205  **This setting is experimental and may be deleted.**
   206  
   207  noSemanticString turns off the sending of the semantic token 'string'
   208  
   209  Default: `false`.
   210  
   211  #### **noSemanticNumber** *bool*
   212  
   213  **This setting is experimental and may be deleted.**
   214  
   215  noSemanticNumber  turns off the sending of the semantic token 'number'
   216  
   217  Default: `false`.
   218  
   219  #### Completion
   220  
   221  ##### **usePlaceholders** *bool*
   222  
   223  placeholders enables placeholders for function parameters or struct
   224  fields in completion responses.
   225  
   226  Default: `false`.
   227  
   228  ##### **completionBudget** *time.Duration*
   229  
   230  **This setting is for debugging purposes only.**
   231  
   232  completionBudget is the soft latency goal for completion requests. Most
   233  requests finish in a couple milliseconds, but in some cases deep
   234  completions can take much longer. As we use up our budget we
   235  dynamically reduce the search scope to ensure we return timely
   236  results. Zero means unlimited.
   237  
   238  Default: `"100ms"`.
   239  
   240  ##### **matcher** *enum*
   241  
   242  **This is an advanced setting and should not be configured by most `gopls` users.**
   243  
   244  matcher sets the algorithm that is used when calculating completion
   245  candidates.
   246  
   247  Must be one of:
   248  
   249  * `"CaseInsensitive"`
   250  * `"CaseSensitive"`
   251  * `"Fuzzy"`
   252  
   253  Default: `"Fuzzy"`.
   254  
   255  ##### **experimentalPostfixCompletions** *bool*
   256  
   257  **This setting is experimental and may be deleted.**
   258  
   259  experimentalPostfixCompletions enables artificial method snippets
   260  such as "someSlice.sort!".
   261  
   262  Default: `true`.
   263  
   264  ##### **completeFunctionCalls** *bool*
   265  
   266  completeFunctionCalls enables function call completion.
   267  
   268  When completing a statement, or when a function return type matches the
   269  expected of the expression being completed, completion may suggest call
   270  expressions (i.e. may include parentheses).
   271  
   272  Default: `true`.
   273  
   274  #### Diagnostic
   275  
   276  ##### **analyses** *map[string]bool*
   277  
   278  analyses specify analyses that the user would like to enable or disable.
   279  A map of the names of analysis passes that should be enabled/disabled.
   280  A full list of analyzers that gopls uses can be found in
   281  [analyzers.md](https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md).
   282  
   283  Example Usage:
   284  
   285  ```json5
   286  ...
   287  "analyses": {
   288    "unreachable": false, // Disable the unreachable analyzer.
   289    "unusedvariable": true  // Enable the unusedvariable analyzer.
   290  }
   291  ...
   292  ```
   293  
   294  Default: `{}`.
   295  
   296  ##### **staticcheck** *bool*
   297  
   298  **This setting is experimental and may be deleted.**
   299  
   300  staticcheck enables additional analyses from staticcheck.io.
   301  These analyses are documented on
   302  [Staticcheck's website](https://staticcheck.io/docs/checks/).
   303  
   304  Default: `false`.
   305  
   306  ##### **annotations** *map[string]bool*
   307  
   308  **This setting is experimental and may be deleted.**
   309  
   310  annotations specifies the various kinds of optimization diagnostics
   311  that should be reported by the gc_details command.
   312  
   313  Can contain any of:
   314  
   315  * `"bounds"` controls bounds checking diagnostics.
   316  * `"escape"` controls diagnostics about escape choices.
   317  * `"inline"` controls diagnostics about inlining choices.
   318  * `"nil"` controls nil checks.
   319  
   320  Default: `{"bounds":true,"escape":true,"inline":true,"nil":true}`.
   321  
   322  ##### **vulncheck** *enum*
   323  
   324  **This setting is experimental and may be deleted.**
   325  
   326  vulncheck enables vulnerability scanning.
   327  
   328  Must be one of:
   329  
   330  * `"Imports"`: In Imports mode, `gopls` will report vulnerabilities that affect packages
   331  directly and indirectly used by the analyzed main module.
   332  * `"Off"`: Disable vulnerability analysis.
   333  
   334  Default: `"Off"`.
   335  
   336  ##### **diagnosticsDelay** *time.Duration*
   337  
   338  **This is an advanced setting and should not be configured by most `gopls` users.**
   339  
   340  diagnosticsDelay controls the amount of time that gopls waits
   341  after the most recent file modification before computing deep diagnostics.
   342  Simple diagnostics (parsing and type-checking) are always run immediately
   343  on recently modified packages.
   344  
   345  This option must be set to a valid duration string, for example `"250ms"`.
   346  
   347  Default: `"1s"`.
   348  
   349  ##### **diagnosticsTrigger** *enum*
   350  
   351  **This setting is experimental and may be deleted.**
   352  
   353  diagnosticsTrigger controls when to run diagnostics.
   354  
   355  Must be one of:
   356  
   357  * `"Edit"`: Trigger diagnostics on file edit and save. (default)
   358  * `"Save"`: Trigger diagnostics only on file save. Events like initial workspace load
   359  or configuration change will still trigger diagnostics.
   360  
   361  Default: `"Edit"`.
   362  
   363  ##### **analysisProgressReporting** *bool*
   364  
   365  analysisProgressReporting controls whether gopls sends progress
   366  notifications when construction of its index of analysis facts is taking a
   367  long time. Cancelling these notifications will cancel the indexing task,
   368  though it will restart after the next change in the workspace.
   369  
   370  When a package is opened for the first time and heavyweight analyses such as
   371  staticcheck are enabled, it can take a while to construct the index of
   372  analysis facts for all its dependencies. The index is cached in the
   373  filesystem, so subsequent analysis should be faster.
   374  
   375  Default: `true`.
   376  
   377  #### Documentation
   378  
   379  ##### **hoverKind** *enum*
   380  
   381  hoverKind controls the information that appears in the hover text.
   382  SingleLine and Structured are intended for use only by authors of editor plugins.
   383  
   384  Must be one of:
   385  
   386  * `"FullDocumentation"`
   387  * `"NoDocumentation"`
   388  * `"SingleLine"`
   389  * `"Structured"` is an experimental setting that returns a structured hover format.
   390  This format separates the signature from the documentation, so that the client
   391  can do more manipulation of these fields.\
   392  This should only be used by clients that support this behavior.
   393  * `"SynopsisDocumentation"`
   394  
   395  Default: `"FullDocumentation"`.
   396  
   397  ##### **linkTarget** *string*
   398  
   399  linkTarget controls where documentation links go.
   400  It might be one of:
   401  
   402  * `"godoc.org"`
   403  * `"pkg.go.dev"`
   404  
   405  If company chooses to use its own `godoc.org`, its address can be used as well.
   406  
   407  Modules matching the GOPRIVATE environment variable will not have
   408  documentation links in hover.
   409  
   410  Default: `"pkg.go.dev"`.
   411  
   412  ##### **linksInHover** *bool*
   413  
   414  linksInHover toggles the presence of links to documentation in hover.
   415  
   416  Default: `true`.
   417  
   418  #### Inlayhint
   419  
   420  ##### **hints** *map[string]bool*
   421  
   422  **This setting is experimental and may be deleted.**
   423  
   424  hints specify inlay hints that users want to see. A full list of hints
   425  that gopls uses can be found in
   426  [inlayHints.md](https://github.com/golang/tools/blob/master/gopls/doc/inlayHints.md).
   427  
   428  Default: `{}`.
   429  
   430  #### Navigation
   431  
   432  ##### **importShortcut** *enum*
   433  
   434  importShortcut specifies whether import statements should link to
   435  documentation or go to definitions.
   436  
   437  Must be one of:
   438  
   439  * `"Both"`
   440  * `"Definition"`
   441  * `"Link"`
   442  
   443  Default: `"Both"`.
   444  
   445  ##### **symbolMatcher** *enum*
   446  
   447  **This is an advanced setting and should not be configured by most `gopls` users.**
   448  
   449  symbolMatcher sets the algorithm that is used when finding workspace symbols.
   450  
   451  Must be one of:
   452  
   453  * `"CaseInsensitive"`
   454  * `"CaseSensitive"`
   455  * `"FastFuzzy"`
   456  * `"Fuzzy"`
   457  
   458  Default: `"FastFuzzy"`.
   459  
   460  ##### **symbolStyle** *enum*
   461  
   462  **This is an advanced setting and should not be configured by most `gopls` users.**
   463  
   464  symbolStyle controls how symbols are qualified in symbol responses.
   465  
   466  Example Usage:
   467  
   468  ```json5
   469  "gopls": {
   470  ...
   471    "symbolStyle": "Dynamic",
   472  ...
   473  }
   474  ```
   475  
   476  Must be one of:
   477  
   478  * `"Dynamic"` uses whichever qualifier results in the highest scoring
   479  match for the given symbol query. Here a "qualifier" is any "/" or "."
   480  delimited suffix of the fully qualified symbol. i.e. "to/pkg.Foo.Field" or
   481  just "Foo.Field".
   482  * `"Full"` is fully qualified symbols, i.e.
   483  "path/to/pkg.Foo.Field".
   484  * `"Package"` is package qualified symbols i.e.
   485  "pkg.Foo.Field".
   486  
   487  Default: `"Dynamic"`.
   488  
   489  ##### **symbolScope** *enum*
   490  
   491  symbolScope controls which packages are searched for workspace/symbol
   492  requests. The default value, "workspace", searches only workspace
   493  packages. The legacy behavior, "all", causes all loaded packages to be
   494  searched, including dependencies; this is more expensive and may return
   495  unwanted results.
   496  
   497  Must be one of:
   498  
   499  * `"all"` matches symbols in any loaded package, including
   500  dependencies.
   501  * `"workspace"` matches symbols in workspace packages only.
   502  
   503  Default: `"all"`.
   504  
   505  #### **verboseOutput** *bool*
   506  
   507  **This setting is for debugging purposes only.**
   508  
   509  verboseOutput enables additional debug logging.
   510  
   511  Default: `false`.
   512  
   513  <!-- END User: DO NOT MANUALLY EDIT THIS SECTION -->
   514  
   515  #### **newDiff** *string*
   516  
   517  newDiff enables the new diff implementation. If this is "both", for now both
   518  diffs will be run and statistics will be generated in a file in $TMPDIR. This
   519  is a risky setting; help in trying it is appreciated. If it is "old" the old
   520  implementation is used, and if it is "new", just the new implementation is
   521  used. This setting will eventually be deleted, once gopls has fully migrated to
   522  the new diff algorithm.
   523  
   524  Default: 'both'.
   525  
   526  ## Code Lenses
   527  
   528  These are the code lenses that `gopls` currently supports. They can be enabled
   529  and disabled using the `codelenses` setting, documented above. Their names and
   530  features are subject to change.
   531  
   532  <!-- BEGIN Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
   533  ### **Toggle gc_details**
   534  
   535  Identifier: `gc_details`
   536  
   537  Toggle the calculation of gc annotations.
   538  ### **Run go generate**
   539  
   540  Identifier: `generate`
   541  
   542  Runs `go generate` for a given directory.
   543  ### **Regenerate cgo**
   544  
   545  Identifier: `regenerate_cgo`
   546  
   547  Regenerates cgo definitions.
   548  ### **Run vulncheck**
   549  
   550  Identifier: `run_govulncheck`
   551  
   552  Run vulnerability check (`govulncheck`).
   553  ### **Run test(s) (legacy)**
   554  
   555  Identifier: `test`
   556  
   557  Runs `go test` for a specific set of test or benchmark functions.
   558  ### **Run go mod tidy**
   559  
   560  Identifier: `tidy`
   561  
   562  Runs `go mod tidy` for a module.
   563  ### **Upgrade a dependency**
   564  
   565  Identifier: `upgrade_dependency`
   566  
   567  Upgrades a dependency in the go.mod file for a module.
   568  ### **Run go mod vendor**
   569  
   570  Identifier: `vendor`
   571  
   572  Runs `go mod vendor` for a module.
   573  <!-- END Lenses: DO NOT MANUALLY EDIT THIS SECTION -->