gopls: Navigation, Refactoring & Diagnostics

gopls is the official Go language server.

It turns your editor into a type-aware client: jump to definitions, rename symbols across packages, surface diagnostics, and apply fixes before you run go build.

Summary

gopls loads your module (or go.work workspace), type-checks packages incrementally, and answers LSP requests from the editor.

Navigation commands resolve through the type checker, so they respect imports, build tags, and generics.

Refactoring operations (rename, add import, extract function) edit the AST with type-checked patches rather than blind search-and-replace.

Diagnostics merge compiler errors from go/types with selected analyzers (unused variables, printf mistakes, and more).

Recipe

Quick-reference recipe card - copy-paste ready.

Editor actions (names vary by IDE):

When to reach for this:

• Tracing a symbol from HTTP handler to store implementation across packages.
• Renaming an exported function without missing importers.
• Fixing import cycles and unused imports before commit.
• Reading squiggles that mirror go build and vet-style issues early.

Working Example

Consider a small module:

// example.com/demo/internal/greet/greet.go
package greet
 
func Hello(name string) string {
    return "hello, " + name
}

// example.com/demo/cmd/app/main.go
package main
 
import (
    "fmt"
    "example.com/demo/internal/greet"
)
 
func main() {
    fmt.Println(greet.Hello("world"))
}

With gopls running at the module root:

1. Go to definition on greet.Hello in main.go opens greet.go on the function body.
2. Find references on Hello lists main.go and any test files importing greet.
3. Rename Hello to Greet updates both files and adjusts import usage if the symbol moves packages (gopls may prompt or refuse if it would break visibility).
4. Organize imports removes unused fmt if you delete the println, adds missing imports when you reference new packages.

What this demonstrates:

• Cross-package navigation follows import paths, not directory proximity.
• Rename is safe because gopls knows all references from type-checked metadata.
• Diagnostics appear on unused imports and wrong arity calls before go run.

Deep Dive

How It Works

• gopls maintains a session per workspace root (go.mod or go.work).
• File changes trigger incremental recomputation of package syntax and types.
• LSP clients send URI-based positions; gopls maps them to AST nodes and type objects.
• Results are cached; unchanged packages skip rework.

Navigation Features

Refactoring Features

Diagnostics and Code Actions

gopls publishes diagnostics with severity (error, warning, hint).

Many include code actions: quick fixes for missing imports, suggested types, or trivial refactors.

Analyzer diagnostics approximate go vet and friends; they are not guaranteed to match every CI linter you enable later.

Go Notes

// build tags affect what gopls type-checks
//go:build integration
 
package myapp

Align gopls.build.buildFlags or GOFLAGS with CI so tagged files do not flip between green locally and red in CI.

Gotchas

• Wrong workspace root - Opening a parent folder without go.mod leaves gopls guessing; open the module or go.work directory. Fix: File → Open Folder on module root.
• Stale diagnostics after git branch switch - gopls cache may lag. Fix: Restart language server or run "Go: Restart Language Server" in VS Code.
• Rename across modules without workspace - Without go.work or a published version, cross-module rename may be incomplete. Fix: Add go.work for local multi-module edits.
• Build tags mismatch - Files behind //go:build tags show as excluded or error in editor. Fix: Set buildFlags: ["-tags=integration"] in gopls settings to match CI.
• Generated code noise - Protobuf or stringer outputs clutter navigation. Fix: Exclude *.pb.go from editor features or mark generated directories in gopls directory filters.
• gopls vs golangci-lint gap - Editor may be clean while CI fails on stricter linters. Fix: Run golangci-lint run locally with the committed config.

Alternatives

FAQs

Related

• Go Developer Tooling: LSP, Debugger, and Analyzers - toolchain overview
• Go Tooling Setup Basics - install and configure gopls
• Debugging with Delve - runtime inspection when types are not enough
• staticcheck & golangci-lint in CI - CI analyzers beyond editor subset
• gopls & Analysis Tooling Best Practices - team editor hygiene

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).