README
¶
gopls, the Go language server
gopls (pronounced "Go please") is the official Go language server developed
by the Go team. It provides 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.
Editors
To get started with gopls, install an LSP plugin in your editor of choice.
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 golang.org/x/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 the last 2 major Go releases. Per
issue #39146, we attempt to maintain best-effort
support for the last 4 major Go releases, but this support extends only to not
breaking the build and avoiding easily fixable regressions.
In the context of this discussion, gopls "supports" a Go version if it supports
being built with that Go version as well as integrating with the go command
of that Go version.
The following table shows the final gopls version that supports a given Go version. Go releases more recent than any 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 |
Our extended support is enforced via continuous integration with older Go versions. This legacy Go CI may not block releases: test failures may be skipped rather than fixed. Furthermore, if a regression in an older Go version causes irreconcilable CI failures, we may drop support for that Go version in CI if it is 3 or 4 Go versions old.
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 |
|---|---|
|
Command generate creates API (settings, etc) documentation in JSON and Markdown for machine and human consumption.
|
Command generate creates API (settings, etc) documentation in JSON and Markdown for machine and human consumption. |
|
assets
Module
|
|
|
integration
|
|
|
internal
|
|
|
astutil
Package astutil provides various AST utility functions for gopls.
|
Package astutil provides various AST utility functions for gopls. |
|
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. |
|
govulncheck
Package govulncheck provides an experimental govulncheck API.
|
Package govulncheck provides an experimental govulncheck API. |
|
govulncheck/semver
Package semver provides shared utilities for manipulating Go semantic versions.
|
Package semver provides shared utilities for manipulating Go semantic versions. |
|
hooks
Package hooks adds all the standard gopls implementations.
|
Package hooks adds all the standard gopls implementations. |
|
lsp
Package lsp implements LSP for gopls.
|
Package lsp implements LSP for gopls. |
|
lsp/analysis/embeddirective
Package embeddirective defines an Analyzer that validates import for //go:embed directive.
|
Package embeddirective defines an Analyzer that validates import for //go:embed directive. |
|
lsp/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. |
|
lsp/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. |
|
lsp/analysis/infertypeargs
Package infertypeargs defines an analyzer that checks for explicit function arguments that could be inferred.
|
Package infertypeargs defines an analyzer that checks for explicit function arguments that could be inferred. |
|
lsp/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 :=". |
|
lsp/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". |
|
lsp/analysis/simplifycompositelit
Package simplifycompositelit defines an Analyzer that simplifies composite literals.
|
Package simplifycompositelit defines an Analyzer that simplifies composite literals. |
|
lsp/analysis/simplifyrange
Package simplifyrange defines an Analyzer that simplifies range statements.
|
Package simplifyrange defines an Analyzer that simplifies range statements. |
|
lsp/analysis/simplifyslice
Package simplifyslice defines an Analyzer that simplifies slice statements.
|
Package simplifyslice defines an Analyzer that simplifies slice statements. |
|
lsp/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". |
|
lsp/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. |
|
lsp/analysis/unusedvariable
Package unusedvariable defines an analyzer that checks for unused variables.
|
Package unusedvariable defines an analyzer that checks for unused variables. |
|
lsp/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. |
|
lsp/browser
Package browser provides utilities for interacting with users' browsers.
|
Package browser provides utilities for interacting with users' browsers. |
|
lsp/cache
Package cache implements the caching layer for gopls.
|
Package cache implements the caching layer for gopls. |
|
lsp/cmd
Package cmd handles the gopls command line.
|
Package cmd handles the gopls command line. |
|
lsp/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. |
|
lsp/command/commandmeta
Package commandmeta provides metadata about LSP commands, by analyzing the command.Interface type.
|
Package commandmeta provides metadata about LSP commands, by analyzing the command.Interface type. |
|
lsp/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. |
|
lsp/debug
Package debug exports debug information for gopls.
|
Package debug exports debug information for gopls. |
|
lsp/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. |
|
lsp/fake
Package fake provides fake implementations of a text editor, LSP client plugin, and Sandbox environment for use in tests.
|
Package fake provides fake implementations of a text editor, LSP client plugin, and Sandbox environment for use in tests. |
|
lsp/filecache
The filecache package provides a file-based shared durable blob cache.
|
The filecache package provides a file-based shared durable blob cache. |
|
lsp/glob
Package glob implements an LSP-compliant glob pattern matcher for testing.
|
Package glob implements an LSP-compliant glob pattern matcher for testing. |
|
lsp/helper
The helper command generates the declaration of the concrete 'server' type that implements the abstract Server interface defined in protocol/tsserver.go (which is itself generated from the LSP protocol).
|
The helper command generates the declaration of the concrete 'server' type that implements the abstract Server interface defined in protocol/tsserver.go (which is itself generated from the LSP protocol). |
|
lsp/lru
The lru package implements a fixed-size in-memory LRU cache.
|
The lru package implements a fixed-size in-memory LRU cache. |
|
lsp/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. |
|
lsp/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. |
|
lsp/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. |
|
lsp/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. |
|
lsp/regtest
Package regtest provides a framework for writing gopls regression tests.
|
Package regtest provides a framework for writing gopls regression tests. |
|
lsp/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. |
|
lsp/snippet
Package snippet implements the specification for the LSP snippet format.
|
Package snippet implements the specification for the LSP snippet format. |
|
lsp/source
Package source provides core features for use by Go editors and tools.
|
Package source provides core features for use by Go editors and tools. |
|
lsp/source/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. |
|
lsp/source/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. |
|
lsp/source/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. |
|
lsp/source/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. |
|
lsp/template
Package template contains code for dealing with templates
|
Package template contains code for dealing with templates |
|
lsp/tests
Package tests exports functionality to be used across a variety of gopls tests.
|
Package tests exports functionality to be used across a variety of gopls tests. |
|
regtest/bench
The bench package implements benchmarks for various LSP operations.
|
The bench package implements benchmarks for various LSP operations. |
|
span
Package span contains support for representing with positions and ranges in text files.
|
Package span contains support for representing with positions and ranges in text files. |
|
vulncheck
Package vulncheck provides an analysis command that runs vulnerability analysis using data from golang.org/x/vuln/vulncheck.
|
Package vulncheck provides an analysis command that runs vulnerability analysis using data from golang.org/x/vuln/vulncheck. |
|
vulncheck/vulntest
Package vulntest provides helpers for vulncheck functionality testing.
|
Package vulntest provides helpers for vulncheck functionality testing. |