gopls settings reference
Source: tip.golang.org/gopls/settings. Settings are passed via the LSP client's initializationOptions (editor-specific config file/UI) — there is no gopls.json read from the workspace by default. Full canonical list: gopls api-json. Store the settings in CLAUDE.md.
Table of contents
Build
| Setting |
Type |
Default |
Purpose |
buildFlags |
[]string |
[] |
Extra flags for the build system, most commonly -tags=<tag> to bring build-tagged files into scope |
env |
map[string]string |
{} |
Environment variables for external commands gopls shells out to (go list, etc.) |
directoryFilters |
[]string |
["-**/node_modules"] |
Include/exclude workspace directories from loading and from workspace-symbol search, using +/- prefixed glob patterns |
expandWorkspaceToModule |
bool |
true |
Whether the enclosing module (not just the opened directory) counts as "workspace" for diagnostics scope |
templateExtensions |
[]string |
[] |
File extensions treated as Go template files (templates have no canonical extension, so this is empty by default) |
When it matters: a symbol behind a build tag (//go:build integration) is invisible to references/go_search until buildFlags: ["-tags=integration"] is set — this is the same root cause as the References build-configuration scoping gotcha in features.md.
Formatting
| Setting |
Type |
Default |
Purpose |
local |
string |
"" |
Import path prefix treated as "local" for import grouping/sort order — equivalent to goimports -local |
gofumpt |
bool |
false |
Format with mvdan.cc/gofumpt's stricter ruleset instead of plain gofmt |
Diagnostics
| Setting |
Type |
Default |
Purpose |
analyses |
map[string]bool |
{} |
Enable/disable individual analyzers by name (the go vet-based framework plus gopls's own) |
staticcheck |
bool |
false |
Enable the staticcheck.io analyzer suite in addition to the built-in analyzers |
vulncheck |
enum: Off|Imports|Prompt |
"Prompt" (or "Off" in some client defaults) |
Whether/how vulnerability-driven diagnostics on go.mod run |
diagnosticsDelay |
time.Duration |
"1s" |
Idle time after an edit before workspace-wide analysis diagnostics recompute (open-file compile errors update sooner regardless) |
diagnosticsTrigger |
enum: Edit|Save |
"Edit" |
Whether diagnostics recompute on every edit or only on save |
pullDiagnostics |
bool |
false |
Let the client request diagnostics on demand (textDocument/diagnostic) instead of only receiving pushed updates |
When it matters: a large monorepo with diagnosticsTrigger: "Edit" (the default) can feel laggy under diagnosticsDelay: "1s" on every keystroke pause — switching to "Save" trades immediacy for fewer full-workspace recomputations. Turning on staticcheck surfaces a materially different (larger) set of findings than the default analyzer set — expect more go_diagnostics/gopls check output afterward, not a regression.
Documentation
| Setting |
Type |
Default |
Purpose |
hoverKind |
enum: FullDocumentation|SingleLine|Structured|NoDocumentation|SynopsisDocumentation |
"FullDocumentation" |
How much doc text Hover renders |
linksInHover |
bool |
true |
Whether hover markdown includes doc-comment links |
linkTarget |
string |
"pkg.go.dev" |
Base host used when generating documentation links (hover, Document Link, diagnostics) |
Inlay hints
| Setting |
Type |
Default |
Purpose |
hints |
map[string]bool |
{} (all off) |
Enables specific inlay hint kinds — keys are parameterNames, assignVariableTypes, compositeLiteralFields, compositeLiteralTypes, constantValues, functionTypeParameters, rangeVariableTypes |
Example:
Navigation
| Setting |
Type |
Default |
Purpose |
symbolMatcher |
enum: FastFuzzy|Fuzzy|CaseSensitive|CaseInsensitive |
"FastFuzzy" |
Matching algorithm for workspace/symbol / go_search |
symbolScope |
enum: all|workspace |
"all" |
Whether symbol search covers only workspace packages or every loaded package (including dependencies) |
symbolStyle |
enum |
— |
How matched symbols are qualified in the response (package-qualified vs. bare) |
codelenses |
map[string]bool |
— |
Enables/disables individual code lenses (e.g. generate, tidy, vendor, run_tests) |
For the complete, always-current settings surface (including experimental and client-specific keys), see gopls api-json or the upstream settings page linked above — this table covers the settings most likely to change how navigation, diagnostics, or refactors behave day-to-day, not the full API.
