README
¶
gopls, the Go language server
gopls (pronounced "Go please") is the official Go language server developed
by the Go team.
It provides a wide variety of IDE features
to any LSP-compatible editor.
You should not need to interact with gopls directly--it will be automatically
integrated into your editor. The specific features and settings vary slightly
by editor, so we recommend that you proceed to the
documentation for your editor below.
Also, the gopls documentation for each feature describes whether it is
supported in each client editor.
Editors
To get started with gopls, install an LSP plugin in your editor of choice.
TODO: ensure that each editor has a local page (and move these to doc/clients/$EDITOR.md). TODO: also, be more consistent about editor (e.g. Emacs) vs. client (e.g. eglot).
If you use gopls with an editor that is not on this list, please send us a CL
updating this documentation.
Installation
For the most part, you should not need to install or update gopls. Your
editor should handle that step for you.
If you do want to get the latest stable version of gopls, run the following
command:
go install github.com/asahasrabuddhe/tools/gopls@latest
Learn more in the advanced installation instructions.
Learn more about gopls releases in the release policy.
Setting up your workspace
gopls supports both Go module, multi-module and GOPATH modes. See the
workspace documentation for information on supported
workspace layouts.
Configuration
You can configure gopls to change your editor experience or view additional
debugging information. Configuration options will be made available by your
editor, so see your editor's instructions for specific details. A
full list of gopls settings can be found in the settings documentation.
Environment variables
gopls inherits your editor's environment, so be aware of any environment
variables you configure. Some editors, such as VS Code, allow users to
selectively override the values of some environment variables.
Support Policy
Gopls is maintained by engineers on the Go tools team, who actively monitor the Go and VS Code Go issue trackers.
Supported Go versions
gopls follows the
Go Release Policy, meaning
that it officially supports only the two most recent major Go releases. Until
August 2024, the Go team will also maintain best-effort support for the last
4 major Go releases, as described in issue #39146.
When using gopls, there are three versions to be aware of:
- The gopls build go version: the version of Go used to build gopls.
- The go command version: the version of the go list command executed by gopls to load information about your workspace.
- The language version: the version in the go directive of the current file's enclosing go.mod file, which determines the file's Go language semantics.
Starting with the release of Go 1.23.0 and gopls@v0.17.0 in August 2024, we will only support the most recent Go version as the gopls build go version. However, due to the forward compatibility support added in Go 1.21, as long as Go 1.21 or later are used to install gopls, any necessary toolchain upgrade will be handled automatically, just like any other dependency.
Additionally, starting with gopls@v0.17.0, the go command version will narrow from 4 versions to 3. This is more consistent with the Go Release Policy.
Gopls supports all Go versions as its language version, by providing compiler errors based on the language version and filtering available standard library symbols based on the standard library APIs available at that Go version.
Maintaining support for building gopls with legacy versions of Go caused significant friction for gopls maintainers and held back other improvements. If you are unable to install a supported version of Go on your system, you can still install an older version of gopls. The following table shows the final gopls version that supports a given Go version. Go releases more recent than those in the table can be used with any version of gopls.
| Go Version | Final gopls version with support (without warnings) |
|---|---|
| Go 1.12 | gopls@v0.7.5 |
| Go 1.15 | gopls@v0.9.5 |
| Go 1.17 | gopls@v0.11.0 |
| Go 1.18 | gopls@v0.14.2 |
| Go 1.20 | gopls@v0.15.3 |
Supported build systems
gopls currently only supports the go command, so if you are using
a different build system, gopls will not work well. Bazel is not officially
supported, but may be made to work with an appropriately configured
go/packages driver. See
bazelbuild/rules_go#512
for more information.
You can follow these instructions
to configure your gopls to work with Bazel.
Troubleshooting
If you are having issues with gopls, please follow the steps described in the
troubleshooting guide.
Additional information
Documentation
¶
Overview ¶
Gopls (pronounced “go please”) is an LSP server for Go. The Language Server Protocol allows any text editor to be extended with IDE-like features; see https://langserver.org/ for details.
See https://github.com/golang/tools/blob/master/gopls/README.md for the most up-to-date documentation.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
doc
|
|
|
generate
The generate command updates the following files of documentation:
|
The generate command updates the following files of documentation: |
|
assets
Module
|
|
|
integration
|
|
|
internal
|
|
|
analysis/deprecated
Package deprecated defines an Analyzer that marks deprecated symbols and package imports.
|
Package deprecated defines an Analyzer that marks deprecated symbols and package imports. |
|
analysis/embeddirective
Package embeddirective defines an Analyzer that validates //go:embed directives.
|
Package embeddirective defines an Analyzer that validates //go:embed directives. |
|
analysis/fillreturns
Package fillreturns defines an Analyzer that will attempt to automatically fill in a return statement that has missing values with zero value elements.
|
Package fillreturns defines an Analyzer that will attempt to automatically fill in a return statement that has missing values with zero value elements. |
|
analysis/fillstruct
Package fillstruct defines an Analyzer that automatically fills in a struct declaration with zero value elements for each field.
|
Package fillstruct defines an Analyzer that automatically fills in a struct declaration with zero value elements for each field. |
|
analysis/fillswitch
Package fillswitch identifies switches with missing cases.
|
Package fillswitch identifies switches with missing cases. |
|
analysis/nonewvars
Package nonewvars defines an Analyzer that applies suggested fixes to errors of the type "no new variables on left side of :=".
|
Package nonewvars defines an Analyzer that applies suggested fixes to errors of the type "no new variables on left side of :=". |
|
analysis/noresultvalues
Package noresultvalues defines an Analyzer that applies suggested fixes to errors of the type "no result values expected".
|
Package noresultvalues defines an Analyzer that applies suggested fixes to errors of the type "no result values expected". |
|
analysis/simplifycompositelit
Package simplifycompositelit defines an Analyzer that simplifies composite literals.
|
Package simplifycompositelit defines an Analyzer that simplifies composite literals. |
|
analysis/simplifyrange
Package simplifyrange defines an Analyzer that simplifies range statements.
|
Package simplifyrange defines an Analyzer that simplifies range statements. |
|
analysis/simplifyslice
Package simplifyslice defines an Analyzer that simplifies slice statements.
|
Package simplifyslice defines an Analyzer that simplifies slice statements. |
|
analysis/stubmethods
Package stubmethods defines a code action for missing interface methods.
|
Package stubmethods defines a code action for missing interface methods. |
|
analysis/undeclaredname
Package undeclaredname defines an Analyzer that applies suggested fixes to errors of the type "undeclared name: %s".
|
Package undeclaredname defines an Analyzer that applies suggested fixes to errors of the type "undeclared name: %s". |
|
analysis/unusedparams
Package unusedparams defines an analyzer that checks for unused parameters of functions.
|
Package unusedparams defines an analyzer that checks for unused parameters of functions. |
|
analysis/unusedparams/cmd
The unusedparams command runs the unusedparams analyzer.
|
The unusedparams command runs the unusedparams analyzer. |
|
analysis/unusedvariable
Package unusedvariable defines an analyzer that checks for unused variables.
|
Package unusedvariable defines an analyzer that checks for unused variables. |
|
analysis/useany
Package useany defines an Analyzer that checks for usage of interface{} in constraints, rather than the predeclared any.
|
Package useany defines an Analyzer that checks for usage of interface{} in constraints, rather than the predeclared any. |
|
cache
Package cache is the core of gopls: it is concerned with state management, dependency analysis, and invalidation; and it holds the machinery of type checking and modular static analysis.
|
Package cache is the core of gopls: it is concerned with state management, dependency analysis, and invalidation; and it holds the machinery of type checking and modular static analysis. |
|
cache/metadata
The metadata package defines types and functions for working with package metadata, which describes Go packages and their relationships.
|
The metadata package defines types and functions for working with package metadata, which describes Go packages and their relationships. |
|
cache/methodsets
Package methodsets defines an incremental, serializable index of method-set information that allows efficient 'implements' queries across packages of the workspace without using the type checker.
|
Package methodsets defines an incremental, serializable index of method-set information that allows efficient 'implements' queries across packages of the workspace without using the type checker. |
|
cache/typerefs
Package typerefs extracts symbol-level reachability information from the syntax of a Go package.
|
Package typerefs extracts symbol-level reachability information from the syntax of a Go package. |
|
cache/xrefs
Package xrefs defines the serializable index of cross-package references that is computed during type checking.
|
Package xrefs defines the serializable index of cross-package references that is computed during type checking. |
|
cmd
Package cmd handles the gopls command line.
|
Package cmd handles the gopls command line. |
|
debug
Package debug exports debug information for gopls.
|
Package debug exports debug information for gopls. |
|
debug/log
Package log provides helper methods for exporting log events to the internal/event package.
|
Package log provides helper methods for exporting log events to the internal/event package. |
|
doc
The doc package provides JSON metadata that documents gopls' public interfaces.
|
The doc package provides JSON metadata that documents gopls' public interfaces. |
|
file
The file package defines types used for working with LSP files.
|
The file package defines types used for working with LSP files. |
|
filecache
The filecache package provides a file-based shared durable blob cache.
|
The filecache package provides a file-based shared durable blob cache. |
|
fuzzy
Package fuzzy implements a fuzzy matching algorithm.
|
Package fuzzy implements a fuzzy matching algorithm. |
|
golang
Package golang defines the LSP features for navigation, analysis, and refactoring of Go source code.
|
Package golang defines the LSP features for navigation, analysis, and refactoring of Go source code. |
|
golang/completion
Package completion provides core functionality for code completion in Go editors and tools.
|
Package completion provides core functionality for code completion in Go editors and tools. |
|
golang/completion/snippet
Package snippet implements the specification for the LSP snippet format.
|
Package snippet implements the specification for the LSP snippet format. |
|
label
Package label provides common labels used to annotate gopls log messages and events.
|
Package label provides common labels used to annotate gopls log messages and events. |
|
lsprpc
Package lsprpc implements a jsonrpc2.StreamServer that may be used to serve the LSP on a jsonrpc2 channel.
|
Package lsprpc implements a jsonrpc2.StreamServer that may be used to serve the LSP on a jsonrpc2 channel. |
|
mod
Package mod provides core features related to go.mod file handling for use by Go editors and tools.
|
Package mod provides core features related to go.mod file handling for use by Go editors and tools. |
|
progress
The progress package defines utilities for reporting the progress of long-running operations using features of the LSP client interface such as Progress and ShowMessage.
|
The progress package defines utilities for reporting the progress of long-running operations using features of the LSP client interface such as Progress and ShowMessage. |
|
protocol
Package protocol contains the structs that map directly to the request and response messages of the Language Server Protocol.
|
Package protocol contains the structs that map directly to the request and response messages of the Language Server Protocol. |
|
protocol/command
Package command defines the interface provided by gopls for the workspace/executeCommand LSP request.
|
Package command defines the interface provided by gopls for the workspace/executeCommand LSP request. |
|
protocol/command/commandmeta
Package commandmeta provides metadata about LSP commands, by statically analyzing the command.Interface type.
|
Package commandmeta provides metadata about LSP commands, by statically analyzing the command.Interface type. |
|
protocol/command/gen
Package gen is used to generate command bindings from the gopls command interface.
|
Package gen is used to generate command bindings from the gopls command interface. |
|
protocol/generate
The generate command generates Go declarations from VSCode's description of the Language Server Protocol.
|
The generate command generates Go declarations from VSCode's description of the Language Server Protocol. |
|
protocol/semtok
The semtok package provides an encoder for LSP's semantic tokens.
|
The semtok package provides an encoder for LSP's semantic tokens. |
|
server
Package server defines gopls' implementation of the LSP server interface, protocol.Server.
|
Package server defines gopls' implementation of the LSP server interface, protocol.Server. |
|
telemetry/cmd/stacks
The stacks command finds all gopls stack traces reported by telemetry in the past 7 days, and reports their associated GitHub issue, creating new issues as needed.
|
The stacks command finds all gopls stack traces reported by telemetry in the past 7 days, and reports their associated GitHub issue, creating new issues as needed. |
|
template
Package template contains code for dealing with templates
|
Package template contains code for dealing with templates |
|
test/integration
Package integration provides a framework for writing integration tests of gopls.
|
Package integration provides a framework for writing integration tests of gopls. |
|
test/integration/bench
The bench package implements benchmarks for various LSP operations.
|
The bench package implements benchmarks for various LSP operations. |
|
test/integration/fake
Package fake provides a fake implementation of an LSP-enabled text editor, its LSP client plugin, and a Sandbox environment for use in integration tests.
|
Package fake provides a fake implementation of an LSP-enabled text editor, its LSP client plugin, and a Sandbox environment for use in integration tests. |
|
test/integration/fake/glob
Package glob implements an LSP-compliant glob pattern matcher for testing.
|
Package glob implements an LSP-compliant glob pattern matcher for testing. |
|
test/marker
Package marker defines a framework for running "marker" tests, each defined by a file in the testdata subdirectory.
|
Package marker defines a framework for running "marker" tests, each defined by a file in the testdata subdirectory. |
|
util/astutil
Package astutil provides various AST utility functions for gopls.
|
Package astutil provides various AST utility functions for gopls. |
|
util/browser
Package browser provides utilities for interacting with users' browsers.
|
Package browser provides utilities for interacting with users' browsers. |
|
util/bug
Package bug provides utilities for reporting internal bugs, and being notified when they occur.
|
Package bug provides utilities for reporting internal bugs, and being notified when they occur. |
|
util/constraints
Package constraints defines a set of useful constraints to be used with type parameters.
|
Package constraints defines a set of useful constraints to be used with type parameters. |
|
util/frob
Package frob is a fast restricted object encoder/decoder in the spirit of encoding/gob.
|
Package frob is a fast restricted object encoder/decoder in the spirit of encoding/gob. |
|
util/goversion
Package goversions defines gopls's policy for which versions of Go it supports.
|
Package goversions defines gopls's policy for which versions of Go it supports. |
|
util/immutable
The immutable package defines immutable wrappers around common data structures.
|
The immutable package defines immutable wrappers around common data structures. |
|
util/lru
The lru package implements a fixed-size in-memory LRU cache.
|
The lru package implements a fixed-size in-memory LRU cache. |
|
util/persistent
The persistent package defines various persistent data structures; that is, data structures that can be efficiently copied and modified in sublinear time.
|
The persistent package defines various persistent data structures; that is, data structures that can be efficiently copied and modified in sublinear time. |
|
util/safetoken
Package safetoken provides wrappers around methods in go/token, that return errors rather than panicking.
|
Package safetoken provides wrappers around methods in go/token, that return errors rather than panicking. |
|
version
Package version manages the gopls version.
|
Package version manages the gopls version. |
|
vulncheck/govulncheck
Package govulncheck contains the JSON output structs for govulncheck.
|
Package govulncheck contains the JSON output structs for govulncheck. |
|
vulncheck/osv
Package osv implements the Go OSV vulnerability format (https://go.dev/security/vuln/database#schema), which is a subset of the OSV shared vulnerability format (https://ossf.github.io/osv-schema), with database and ecosystem-specific meanings and fields.
|
Package osv implements the Go OSV vulnerability format (https://go.dev/security/vuln/database#schema), which is a subset of the OSV shared vulnerability format (https://ossf.github.io/osv-schema), with database and ecosystem-specific meanings and fields. |
|
vulncheck/semver
Package semver provides shared utilities for manipulating Go semantic versions.
|
Package semver provides shared utilities for manipulating Go semantic versions. |
|
vulncheck/vulntest
Package vulntest provides helpers for vulncheck functionality testing.
|
Package vulntest provides helpers for vulncheck functionality testing. |