This extension is highly configurable, and as such, offers a number of settings. These can be configured by modifying your User or Workspace Settings.

To navigate to your settings, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".

For tuning the features provided by gopls, see the section for gopls settings.

The settings described below are up-to-date as of January 2021. We do our best to keep documentation current, but if a setting is missing, you can always consult the full list in the Extensions view. Documentation for each setting should also be visible in the Settings UI.

To view the list of settings:

1. Navigate to the Extensions view (Ctrl+Shift+X).
2. Find the Go extension and click on it to open the Extension Editor.
3. Click on the Feature Contributions tab.
4. Scroll through the list under Settings.

This extension runs a few third-party command-line tools found from the locations determined by the PATH or Path environment variable, and the settings such as "go.alternateTools" or "go.toolsGopath". Configuring them in workspace settings allows users to conveniently select a different set of tools based on project's need, but also allows attackers to run arbitrary binaries on your machine if they successfuly convince you to open a random repository. In order to reduce the security risk, the extension reads those settings from user settings by default. If the repository can be trusted and workspace settings must be used, you can mark the workspace as a trusted workspace using the "Go: Toggle Workspace Trust Flag" command.

Tags and options configured here will be used by the Add Tags command to add tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, json tags are added.

Default:

{
	"options" :	"json=omitempty",
	"promptForTags" :	false,
	"tags" :	"json",
	"template" :	"",
	"transform" :	"snakecase",
}

Alternate tools or alternate paths for the same tools used by the Go extension. Provide either absolute path or the name of the binary in GOPATH/bin, GOROOT/bin or PATH. Useful when you want to use wrapper script for the Go tools.

Flags to go build/go test used during build-on-save or running tests. (e.g. ["-ldflags='-s'"]) This is propagated to the language server if gopls.build.buildFlags is not specified.

Enable the Go language server (#go.useLanguageServer#) to diagnose compile errors. Compiles code on file save using 'go build' or 'go test -c'. Not applicable when using the language server.
Allowed Options: package, workspace, off

Default: "package"

The Go build tags to use for all commands, that support a -tags '...' argument. When running tests, go.testTags will be used instead if it was set. This is propagated to the language server if gopls.build.buildFlags is not specified.

Default: ""

When generating code coverage, the value for -covermode. 'default' is the default value chosen by the 'go test' command.
Allowed Options: default, set, count, atomic

Default: "default"

If true, runs 'go test -coverprofile' on save and shows test coverage.

Default: false

If true, shows test coverage when Go: Test Function at cursor command is run.

Default: false

If true, shows test coverage when Go: Test Single File command is run.

Default: false

If true, shows test coverage when Go: Test Package command is run.

Default: true

When generating code coverage, should counts be shown as --374--

Default: false

This option lets you choose the way to display code coverage. Choose either to highlight the complete line or to show a decorator in the gutter. You can customize the colors and borders for the former and the style for the latter.

Default:

{
	"coveredBorderColor" :	"rgba(64,128,128,0.5)",
	"coveredGutterStyle" :	"blockblue",
	"coveredHighlightColor" :	"rgba(64,128,128,0.5)",
	"type" :	"highlight",
	"uncoveredBorderColor" :	"rgba(128,64,64,0.25)",
	"uncoveredGutterStyle" :	"slashyellow",
	"uncoveredHighlightColor" :	"rgba(128,64,64,0.25)",
}

Use these options to control whether only covered or only uncovered code or both should be highlighted after running test coverage
Allowed Options: showCoveredCodeOnly, showUncoveredCodeOnly, showBothCoveredAndUncoveredCode

Default: "showBothCoveredAndUncoveredCode"

Delve settings that applies to all debugging sessions. Debug configuration in the launch.json file will override these values.

(Experimental) vulncheck enables vulnerability scanning.
Allowed Options:

• Imports: "Imports": In Imports mode, gopls will report vulnerabilities that affect packages directly and indirectly used by the analyzed main module.
• Off: "Off": Disable vulnerability analysis.

Default: "Off"

If true, tests will not run concurrently. When a new test run is started, the previous will be cancelled.

Default: false

Experimental Feature: Enable/Disable entries from the context menu in the editor.

Default:

{
	"addImport" :	true,
	"addTags" :	true,
	"benchmarkAtCursor" :	false,
	"debugTestAtCursor" :	true,
	"fillStruct" :	false,
	"generateTestForFile" :	false,
	"generateTestForFunction" :	true,
	"generateTestForPackage" :	false,
	"playground" :	true,
	"removeTags" :	false,
	"testAtCursor" :	true,
	"testCoverage" :	true,
	"testFile" :	false,
	"testPackage" :	false,
	"toggleTestFile" :	true,
}

Feature level setting to enable/disable code lens for references and run/debug tests

Default:

{
	"runtest" :	true,
}

Disable experimental features. These features are only available in the pre-release version.

Default:

{
	"testExplorer" :	true,
}

Flags to pass to format tool (e.g. ["-s"]). Not applicable when using the language server.

When the language server is enabled and one of default/gofmt/goimports/gofumpt is chosen, the language server will handle formatting. If custom tool is selected, the extension will use the customFormatter tool in the #go.alternateTools# section.
Allowed Options:

• default: If the language server is enabled, format via the language server, which already supports gofmt, goimports, goreturns, and gofumpt. Otherwise, goimports.
• gofmt: Formats the file according to the standard Go style. (not applicable when the language server is enabled)
• goimports: Organizes imports and formats the file with gofmt. (not applicable when the language server is enabled)
• goformat: Configurable gofmt, see https://github.com/mbenkmann/goformat.
• gofumpt: Stricter version of gofmt, see https://github.com/mvdan/gofumpt. . Use #gopls.format.gofumpt# instead)
• custom: Formats using the custom tool specified as customFormatter in the #go.alternateTools# setting. The tool should take the input as STDIN and output the formatted code as STDOUT.

Default: "default"

Additional command line flags to pass to gotests for generating tests.

Specify GOPATH here to override the one that is set as environment variable. The inferred GOPATH from workspace root overrides this, if go.inferGopath is set to true.

Specifies the GOROOT to use when no environment variable is set.

Infer GOPATH from the workspace root. This is ignored when using Go Modules.

Default: false

"assignVariableTypes" controls inlay hints for variable types in assign statements:

	i/* int*/, j/* int*/ := 0, len(r)-1

Default: false

"compositeLiteralFields" inlay hints for composite literal field names:

	{/*in: */"Hello, world", /*want: */"dlrow ,olleH"}

Default: false

"compositeLiteralTypes" controls inlay hints for composite literal types:

	for _, c := range []struct {
		in, want string
	}{
		/*struct{ in string; want string }*/{"Hello, world", "dlrow ,olleH"},
	}

Default: false

"constantValues" controls inlay hints for constant values:

	const (
		KindNone   Kind = iota/* = 0*/
		KindPrint/*  = 1*/
		KindPrintf/* = 2*/
		KindErrorf/* = 3*/
	)

Default: false

"functionTypeParameters" inlay hints for implicit type parameters on generic functions:

	myFoo/*[int, string]*/(1, "hello")

Default: false

"parameterNames" controls inlay hints for parameter names:

	parseInt(/* str: */ "123", /* radix: */ 8)

Default: false

"rangeVariableTypes" controls inlay hints for variable types in range statements:

	for k/* int*/, v/* string*/ := range []string{} {
		fmt.Println(k, v)
	}

Default: false

If true, then -i flag will be passed to go build everytime the code is compiled. Since Go 1.10, setting this may be unnecessary unless you are in GOPATH mode and do not use the language server.

Default: false

Flags like -rpc.trace and -logfile to be used while running the language server.

Flags to pass to Lint tool (e.g. ["-min_confidence=.8"])

Lints code on file save using the configured Lint tool. Options are 'file', 'package', 'workspace' or 'off'.
Allowed Options:

• file: lint the current file on file saving
• package: lint the current package on file saving
• workspace: lint all the packages in the current workspace root folder on file saving
• off: do not run lint automatically

Default: "package"

Specifies Lint tool name.
Allowed Options: staticcheck, golint, golangci-lint, revive

Default: "staticcheck"

This setting is deprecated. Use 'Developer: Set Log Level...' command to control logging level instead.

The flags configured here will be passed through to command goplay

Default:

{
	"openbrowser" :	true,
	"run" :	true,
	"share" :	true,
}

Tags and options configured here will be used by the Remove Tags command to remove tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, all tags and options will be removed.

Default:

{
	"options" :	"",
	"promptForTags" :	false,
	"tags" :	"",
}

Specifies whether to show the Welcome experience on first install

Default: true

Prompt for surveys, including the gopls survey and the Go developer survey.

Default: true

enable the default go build/test task provider.

Default: true

Apply the Go & PATH environment variables used by the extension to all integrated terminals.

Default: true

Absolute path to a file containing environment variables definitions. File contents should be of the form key=value.

Environment variables that will be passed to the process that runs the Go tests

Run benchmarks when running all tests in a file or folder.

Default: false

Concatenate all test log messages for a given location into a single message.

Default: true

Enable the Go test explorer

Default: true

Present packages in the test explorer flat or nested.
Allowed Options: flat, nested

Default: "flat"

Set the source location of dynamically discovered subtests to the location of the containing function. As a result, dynamically discovered subtests will be added to the gutter test widget of the containing function.

Default: false

Open the test output terminal when a test run is started.

Default: true

Flags to pass to go test. If null, then buildFlags will be used. This is not propagated to the language server.

Run 'go test' on save for current package. It is not advised to set this to true when you have Auto Save enabled.

Default: false

The Go build tags to use for when running tests. If null, then buildTags will be used.

Specifies the timeout for go test in ParseDuration format.

Default: "30s"

Environment variables that will be passed to the tools that run the Go tools (e.g. CGO_CFLAGS) and debuggee process launched by Delve. Format as string key:value pairs. When debugging, merged with envFile and env values with precedence env > envFile > go.toolsEnvVars.

Location to install the Go tools that the extension depends on if you don't want them in your GOPATH.

Automatically update the tools used by the extension, without prompting the user.

Default: false

Specify whether to prompt about new versions of Go and the Go tools (currently, only gopls) the extension depends on
Allowed Options:

• proxy: keeps notified of new releases by checking the Go module proxy (GOPROXY)
• local: checks only the minimum tools versions required by the extension
• off: completely disables version check (not recommended)

Default: "proxy"

The path to the go binary used to install the Go tools. If it's empty, the same go binary chosen for the project will be used for tool installation.

Default: ""

Trace the communication between VS Code and the Go language server.
Allowed Options: off, messages, verbose

Default: "off"

Enable intellisense, code navigation, refactoring, formatting & diagnostics for Go. The features are powered by the Go language server "gopls".

Default: true

Flags to pass to go tool vet (e.g. ["-all", "-shadow"]). Not applicable when using the language server's diagnostics.

Vets code on file save using 'go tool vet'. Not applicable when using the language server's diagnostics.
Allowed Options:

• package: vet the current package on file saving
• workspace: vet all the packages in the current workspace root folder on file saving
• off: do not run vet automatically

Default: "package"

Customize gopls behavior by specifying the gopls' settings in this section. For example,

"gopls" : {
	"build.directoryFilters": ["-node_modules"]
	...
}

This section is directly read by gopls. See the gopls section section for the full list of gopls settings.

Configure the default Go language server ('gopls'). In most cases, configuring this section is unnecessary. See the documentation for all available settings.

buildFlags 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.

If unspecified, values of go.buildFlags, go.buildTags will be propagated.

directoryFilters can be used to exclude unwanted directories from the workspace. By default, all directories are included. Filters are an operator, + to include and - to exclude, followed by a path prefix relative to the workspace folder. They are evaluated in order, and the last filter that applies to a path controls whether it is included. The path prefix can be empty, so an initial - excludes everything.

DirectoryFilters also supports the ** operator to match 0 or more directories.

Examples:

Exclude node_modules at current depth: -node_modules

Exclude node_modules at any depth: -**/node_modules

Include only project_a: - (exclude everything), +project_a

Include only project_a, but not node_modules inside it: -, +project_a, -project_a/node_modules

Default: ["-**/node_modules"]

env adds environment variables to external commands run by gopls, most notably go list.

(Experimental) expandWorkspaceToModule determines which packages are considered "workspace packages" when the workspace is using modules.

Workspace packages affect the scope of workspace-wide operations. Notably, gopls diagnoses all packages considered to be part of the workspace after every keystroke, so by setting "ExpandWorkspaceToModule" to false, and opening a nested workspace directory, you can reduce the amount of work gopls has to do to keep your workspace up to date.

Default: true

(Experimental) obsolete, no effect

Default: ""

standaloneTags specifies a set of build constraints that identify individual Go source files that make up the entire main package of an executable.

A common example of standalone main files is the convention of using the directive //go:build ignore to denote files that are not intended to be included in any package, for example because they are invoked directly by the developer using go run.

Gopls considers a file to be a standalone main file if and only if it has package name "main" and has a build directive of the exact form "//go:build tag" or "// +build tag", where tag is among the list of tags configured by this setting. Notably, if the build constraint is more complicated than a simple tag (such as the composite constraint //go:build tag && go1.18), the file is not considered to be a standalone main file.

This setting is only supported when gopls is built with Go 1.16 or later.

Default: ["ignore"]

templateExtensions gives the extensions of file names that are treated as template files. (The extension is the part of the file name after the final dot.)

gofumpt indicates if we should run gofumpt formatting.

Default: false

local is the equivalent of the goimports -local flag, which puts imports beginning with this string after third-party packages. It should be the prefix of the import path whose imports should be grouped separately.

It is used when tidying imports (during an LSP Organize Imports request) or when inserting new ones (for example, during completion); an LSP Formatting request merely sorts the existing imports.

Default: ""

codelenses overrides the enabled/disabled state of each of gopls' sources of Code Lenses.

Example Usage:

"gopls": {
...
  "codelenses": {
    "generate": false,  // Don't show the `go generate` lens.
    "gc_details": true  // Show a code lens toggling the display of gc's choices.
  }
...
}

completeFunctionCalls enables function call completion.

When completing a statement, or when a function return type matches the expected of the expression being completed, completion may suggest call expressions (i.e. may include parentheses).

Default: true

(For Debugging) completionBudget is the soft latency goal for completion requests. Most requests finish in a couple milliseconds, but in some cases deep completions can take much longer. As we use up our budget we dynamically reduce the search scope to ensure we return timely results. Zero means unlimited.

Default: "100ms"

(Experimental) experimentalPostfixCompletions enables artificial method snippets such as "someSlice.sort!".

Default: true

(Advanced) matcher sets the algorithm that is used when calculating completion candidates.
Allowed Options: CaseInsensitive, CaseSensitive, Fuzzy

Default: "Fuzzy"

placeholders enables placeholders for function parameters or struct fields in completion responses.

Default: false

analyses specify analyses that the user would like to enable or disable. A map of the names of analysis passes that should be enabled/disabled. A full list of analyzers that gopls uses can be found in analyzers.md.

Example Usage:

...
"analyses": {
  "unreachable": false, // Disable the unreachable analyzer.
  "unusedvariable": true  // Enable the unusedvariable analyzer.
}
...

s := []string{"a", "b", "c"}
_ = append(s)

x = atomic.AddUint64(&x, 1)

err = &net.DNSConfigError{err}

err = &net.DNSConfigError{Err: err}

start := time.Now()
...
defer recordLatency(time.Since(start)) // error: call to time.Since is not deferred

defer func() { recordLatency(time.Since(start)) }()

func m() (int, string, *bool, error) {
	return
}

func m() (int, string, *bool, error) {
	return 0, "", nil, nil
}

resp, err := http.Head(url)
defer resp.Body.Close()
if err != nil {
	log.Fatal(err)
}
// (defer statement belongs here)

var v interface {
	Read()
}
_ = v.(io.Reader)

func fT any {}


func _() {
	fstring // string could be inferred
}

for _, v := range list {
    defer func() {
        use(v) // incorrect
    }()
}

for _, v := range list {
    v := v // new var per iteration
    defer func() {
        use(v) // ok
    }()
}

for _, v := range elem {
    go func() {
        use(v)  // incorrect, and a data race
    }()
}

func Test(t *testing.T) {
    for _, test := range tests {
        t.Run(test.name, func(t *testing.T) {
            t.Parallel()
            use(test) // incorrect, and a data race
        })
    }
}

if r := recover(); r != nil {

if f == nil { // impossible condition (f is a function)
}

p := &v
...
if p != nil { // tautological condition
}

if p == nil {
	print(*p) // nil dereference
}

if p == nil {
	panic(p)
}

...
err := g.Wait()
if err != nil {
	return err
}
partialSuccess := false
for _, err := range errs {
	if err == nil {
		partialSuccess = true
		break
	}
}
if partialSuccess {
	reportStatus(StatusMessage{
		Code:   code.ERROR,
		Detail: err.Error(), // "nil dereference in dynamic method call"
	})
	return nil
}

z := 1
z := 2

z := 1
z = 2

func z() { return nil }

func z() { return }

func BadRead(f *os.File, buf []byte) error {
	var err error
	for {
		n, err := f.Read(buf) // shadows the function variable 'err'
		if err != nil {
			break // causes return of wrong value
		}
		foo(buf)
	}
	return err
}

signal.Notify(c <-chan os.Signal, sig ...os.Signal),

[]T{T{}, T{}}

[]T{{}, {}}

for x, _ = range v {...}

for x = range v {...}

for _ = range v {...}

for range v {...}

s[a:len(s)]

s[a:]

slog.Warn("message", 11, "k") // slog.Warn arg "11" should be a string or a slog.Attr

slog.Info("message", "k1", v1, "k2") // call to slog.Info missing a final value

type myWriterTo struct{...}
func (myWriterTo) WriteTo(w io.Writer) error { ... }

Format GobEncode GobDecode MarshalJSON MarshalXML
Peek ReadByte ReadFrom ReadRune Scan Seek
UnmarshalJSON UnreadByte UnreadRune WriteByte
WriteTo

func TestFoo(t *testing.T) {
    go func() {
        t.Fatal("oops") // error: (*T).Fatal called from non-test goroutine
    }()
}

<> :=

func <>(inferred parameters) {
	panic("implement me!")
}

type T struct { x int }

func f(input []T) {
	for i, v := range input {  // v is a copy
		v.x = i  // unused write to field x
	}
}

type T struct { x int }

func (t T) f() {  // t is a copy
	t.x = i  // unused write to field x
}

analysisProgressReporting controls whether gopls sends progress notifications when construction of its index of analysis facts is taking a long time. Cancelling these notifications will cancel the indexing task, though it will restart after the next change in the workspace.

When a package is opened for the first time and heavyweight analyses such as staticcheck are enabled, it can take a while to construct the index of analysis facts for all its dependencies. The index is cached in the filesystem, so subsequent analysis should be faster.

Default: true

(Experimental) annotations specifies the various kinds of optimization diagnostics that should be reported by the gc_details command.

(Advanced) diagnosticsDelay controls the amount of time that gopls waits after the most recent file modification before computing deep diagnostics. Simple diagnostics (parsing and type-checking) are always run immediately on recently modified packages.

This option must be set to a valid duration string, for example "250ms".

Default: "1s"

(Experimental) diagnosticsTrigger controls when to run diagnostics.
Allowed Options:

• Edit: "Edit": Trigger diagnostics on file edit and save. (default)
• Save: "Save": Trigger diagnostics only on file save. Events like initial workspace load or configuration change will still trigger diagnostics.

Default: "Edit"

(Experimental) staticcheck enables additional analyses from staticcheck.io. These analyses are documented on Staticcheck's website.

Default: false

hoverKind controls the information that appears in the hover text. SingleLine and Structured are intended for use only by authors of editor plugins.
Allowed Options:

• FullDocumentation
• NoDocumentation
• SingleLine
• Structured: "Structured" is an experimental setting that returns a structured hover format. This format separates the signature from the documentation, so that the client can do more manipulation of these fields.
  This should only be used by clients that support this behavior.
• SynopsisDocumentation

Default: "FullDocumentation"

linkTarget is the base URL for links to Go package documentation returned by LSP operations such as Hover and DocumentLinks and in the CodeDescription field of each Diagnostic.

It might be one of:

• "godoc.org"
• "pkg.go.dev"

If company chooses to use its own godoc.org, its address can be used as well.

Modules matching the GOPRIVATE environment variable will not have documentation links in hover.

Default: "pkg.go.dev"

linksInHover controls the presence of documentation links in hover markdown.
Allowed Options:

• false: false: do not show links
• true: true: show links to the linkTarget domain
• gopls: "gopls": show links to gopls' internal documentation viewer

Default: true

importShortcut specifies whether import statements should link to documentation or go to definitions.
Allowed Options: Both, Definition, Link

Default: "Both"

(Advanced) symbolMatcher sets the algorithm that is used when finding workspace symbols.
Allowed Options: CaseInsensitive, CaseSensitive, FastFuzzy, Fuzzy

Default: "FastFuzzy"

symbolScope controls which packages are searched for workspace/symbol requests. When the scope is "workspace", gopls searches only workspace packages. When the scope is "all", gopls searches all loaded packages, including dependencies and the standard library.
Allowed Options:

• all: "all" matches symbols in any loaded package, including dependencies.
• workspace: "workspace" matches symbols in workspace packages only.

Default: "all"

(Advanced) symbolStyle controls how symbols are qualified in symbol responses.

Example Usage:

"gopls": {
...
  "symbolStyle": "Dynamic",
...
}

• Dynamic: "Dynamic" uses whichever qualifier results in the highest scoring match for the given symbol query. Here a "qualifier" is any "/" or "." delimited suffix of the fully qualified symbol. i.e. "to/pkg.Foo.Field" or just "Foo.Field".
• Full: "Full" is fully qualified symbols, i.e. "path/to/pkg.Foo.Field".
• Package: "Package" is package qualified symbols i.e. "pkg.Foo.Field".

Default: "Dynamic"

(Experimental) noSemanticNumber turns off the sending of the semantic token 'number'

Default: false

(Experimental) noSemanticString turns off the sending of the semantic token 'string'

Default: false

(Experimental) semanticTokens controls whether the LSP server will send semantic tokens to the client.

Default: false

(For Debugging) verboseOutput enables additional debug logging.

Default: false

✏️ Want to contribute to this wiki?

Update the source and send a PR.