Gopls: Settings - The Go Programming Language

Common problems companies solve with Go
Stories about how and why companies use Go
How Go can help keep you secure by default
The official Go language specification
A complete introduction to building software with Go
Reference documentation for Go's standard library
Learn what's new in each Go release
Tips for writing clear, performant, and idiomatic Go code
Videos from prior events
Meet other local Go developers
Learn and network with Go developers from around the world
The Go project's official blog.
Get help and stay informed from Go
This document describes gopls’ configuration settings.
Gopls settings are defined by a JSON object whose valid fields are described below. These fields are gopls-specific, and generic LSP clients have no knowledge of them.
Different clients present configuration settings in their user interfaces in a wide variety of ways. For example, some expect the user to edit the raw JSON object while others use a data structure in the editor’s configuration language; still others (such as VS Code) have a graphical configuration system. Be sure to consult the documentation for how to express configuration settings in your client. Some clients also permit settings to be configured differently for each workspace folder.
Any settings that are experimental or for debugging purposes are marked as such.
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.
env adds environment variables to external commands run by gopls, most notably go list.
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.
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"].
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.)
This setting is experimental and may be deleted.
This setting is experimental and may be deleted.
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.
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"].
workspaceFiles configures the set of globs that match files defining the logical build of the current workspace. Any on-disk changes to any files matching a glob specified here will trigger a reload of the workspace.
This setting need only be customized in environments with a custom GOPACKAGESDRIVER.
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.