1# Settings
2
3<!--TODO: Generate this file from the documentation in golang/org/x/tools/internal/lsp/source/options.go.-->
4
5This document describes the global settings for `gopls` inside the editor. The settings block will be called `"gopls"` and contains a collection of controls for `gopls` that the editor is not expected to understand or control. These settings can also be configured differently per workspace folder.
6
7In VSCode, this would be a section in your `settings.json` file that might look like this:
8
9```json5
10  "gopls": {
11    "usePlaceholders": true,
12    "completeUnimported": true
13  },
14```
15
16## Officially supported
17
18Below is the list of settings that are officially supported for `gopls`.
19
20### **buildFlags** *array of strings*
21
22This is the set of flags passed on to the build system when invoked. It is applied to queries like `go list`, which is used when discovering files. The most common use is to set `-tags`.
23
24### **env** *map of string to value*
25
26This can be used to add environment variables. These will not affect `gopls` itself, but will be used for any external commands it invokes.
27
28### **hoverKind** *string*
29
30This controls the information that appears in the hover text.
31It must be one of:
32* `"NoDocumentation"`
33* `"SynopsisDocumentation"`
34* `"FullDocumentation"`
35
36Authors of editor clients may wish to handle hover text differently, and so might use different settings. The options below are not intended for use by anyone other than the authors of editor plugins.
37
38* `"SingleLine"`
39* `"Structured"`
40
41Default: `"SynopsisDocumentation"`.
42
43### **usePlaceholders** *boolean*
44
45If true, then completion responses may contain placeholders for function parameters or struct fields.
46
47Default: `false`.
48
49### **linkTarget** *string*
50
51This controls where points documentation for given package in `textDocument/documentLink`.
52It might be one of:
53* `"godoc.org"`
54* `"pkg.go.dev"`
55If company chooses to use its own `godoc.org`, its address can be used as well.
56
57Default: `"pkg.go.dev"`.
58
59## Experimental
60
61The below settings are considered experimental. They may be deprecated or changed in the future. They are typically used to test experimental opt-in features or to disable features.
62
63### **experimentalDisabledAnalyses** *array of strings*
64
65A list of the names of analysis passes that should be disabled. You can use this to turn off analyses that you feel are not useful in the editor.
66
67### **staticcheck** *boolean*
68
69If true, it enables the use of the staticcheck.io analyzers.
70
71### **completionDocumentation** *boolean*
72
73If false, indicates that the user does not want documentation with completion results.
74
75Default value: `true`.
76
77### **completeUnimported** *boolean*
78
79If true, the completion engine is allowed to make suggestions for packages that you do not currently import.
80
81Default: `false`.
82
83### **deepCompletion** *boolean*
84
85If true, this turns on the ability to return completions from deep inside relevant entities, rather than just the locally accessible ones.
86
87Default: `true`.
88
89Consider this example:
90
91```go
92package main
93
94import "fmt"
95
96type wrapString struct {
97    str string
98}
99
100func main() {
101    x := wrapString{"hello world"}
102    fmt.Printf(<>)
103}
104```
105
106At the location of the `<>` in this program, deep completion would suggest the result `x.str`.
107
108### **fuzzyMatching** *boolean*
109
110If true, this enables server side fuzzy matching of completion candidates.
111
112Default: `true`.
113