go/gopls/doc/settings.md

Settings

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

In VSCode, this would be a section in your settings.json file that might look like this:

  "gopls": {
    "usePlaceholders": true,
    "completeUnimported": true
  },

Officially supported

Below is the list of settings that are officially supported for gopls.

buildFlags []string

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.

Default: [].

env []string

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

Default: [].

hoverKind golang.org/x/tools/internal/lsp/source.HoverKind

hoverKind controls the information that appears in the hover text. It must be one of:

• "NoDocumentation"
• "SynopsisDocumentation"
• "FullDocumentation"

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

• "SingleLine"
• "Structured"

Default: "FullDocumentation".

usePlaceholders bool

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

Default: false.

linkTarget string

linkTarget controls where documentation links go. 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.

Default: "pkg.go.dev".

local string

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

Default: "".

gofumpt bool

gofumpt indicates if we should run gofumpt formatting.

Default: false.

Experimental

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

analyses map[string]bool

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 here

Example Usage:

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

Default: null.

codelens map[string]bool

overrides the enabled/disabled state of various code lenses. Currently, we support several code lenses:

• generate: run go generate as specified by a //go:generate directive.
• upgrade_dependency: upgrade a dependency listed in a go.mod file.
• test: run go test -run for a test func.
• gc_details: Show the gc compiler's choices for inline analysis and escaping.

Example Usage:

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

Default: {"gc_details":false,"generate":true,"regenerate_cgo":true,"tidy":true,"upgrade_dependency":true,"vendor":true}.

completionDocumentation bool

completionDocumentation enables documentation with completion results.

Default: true.

completeUnimported bool

completeUnimported enables completion for packages that you do not currently import.

Default: true.

deepCompletion bool

deepCompletion If true, this turns on the ability to return completions from deep inside relevant entities, rather than just the locally accessible ones.

Consider this example:

package main

import "fmt"

type wrapString struct {
    str string
}

func main() {
    x := wrapString{"hello world"}
    fmt.Printf(<>)
}

At the location of the <> in this program, deep completion would suggest the result x.str.

Default: true.

matcher golang.org/x/tools/internal/lsp/source.Matcher

matcher sets the algorithm that is used when calculating completion candidates. Must be one of:

• "fuzzy"
• "caseSensitive"
• "caseInsensitive"

Default: "Fuzzy".

annotations map[string]bool

annotations suppress various kinds of optimization diagnostics that would be reported by the gc_details command. noNilcheck suppresses display of nilchecks. noEscape suppresses escape choices. noInline suppresses inlining choices. noBounds suppresses bounds checking diagnositcs.

Default: null.

staticcheck bool

staticcheck enables additional analyses from staticcheck.io.

Default: false.

symbolMatcher golang.org/x/tools/internal/lsp/source.SymbolMatcher

symbolMatcher sets the algorithm that is used when finding workspace symbols. Must be one of:

• "fuzzy"
• "caseSensitive"
• "caseInsensitive"

Default: "SymbolFuzzy".

symbolStyle golang.org/x/tools/internal/lsp/source.SymbolStyle

symbolStyle specifies what style of symbols to return in symbol requests. Must be one of:

• "full"
• "dynamic"
• "package"

Default: "PackageQualifiedSymbols".

linksInHover bool

linksInHover toggles the presence of links to documentation in hover.

Default: true.

tempModfile bool

tempModfile controls the use of the -modfile flag in Go 1.14.

Default: true.

importShortcut golang.org/x/tools/internal/lsp/source.ImportShortcut

importShortcut specifies whether import statements should link to documentation or go to definitions. Must be one of:

• "both"
• "link"
• "definition"

Default: "Both".

verboseWorkDoneProgress bool

verboseWorkDoneProgress controls whether the LSP server should send progress reports for all work done outside the scope of an RPC.

Default: false.

expandWorkspaceToModule bool

expandWorkspaceToModule instructs gopls to expand the scope of the workspace to include the modules containing the workspace folders. Set this to false to avoid loading your entire module. This is particularly useful for those working in a monorepo.

Default: true.

experimentalWorkspaceModule bool

experimentalWorkspaceModule opts a user into the experimental support for multi-module workspaces.

Default: false.