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 let us know
by filing an issue or modifying 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, change to any
directory that is both outside of your GOPATH and outside of a module (a temp
directory is fine), and run:
go install golang.org/x/tools/gopls@latest
Learn more in the advanced installation instructions.
Setting up your workspace
gopls supports both Go module and GOPATH modes, but if you are working with
multiple modules or uncommon project layouts, you will need to specifically
configure your workspace. See the Workspace document 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.
Troubleshooting
If you are having issues with gopls, please follow the steps described in the
troubleshooting guide.
Supported Go versions and build systems
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 |
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.
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 Bazel support is in development (see
bazelbuild/rules_go#512).
You can follow these instructions
to configure your gopls to work with Bazel.
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
|
|
|
govulncheck
Package govulncheck supports the govulncheck command.
|
Package govulncheck supports the govulncheck command. |
|
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/cmd/test
Package cmdtest contains the test suite for the command line behavior of gopls.
|
Package cmdtest contains the test suite for the command line behavior of gopls. |
|
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/helper
Invoke with //go:generate helper/helper -t Server -d protocol/tsserver.go -u lsp -o server_gen.go invoke in internal/lsp
|
Invoke with //go:generate helper/helper -t Server -d protocol/tsserver.go -u lsp -o server_gen.go invoke in internal/lsp |
|
lsp/lsppos
Package lsppos provides utilities for working with LSP positions.
|
Package lsppos provides utilities for working with LSP positions. |
|
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 wire format of the "Language Server Protocol".
|
Package protocol contains the structs that map directly to the wire format 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/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. |
|
robustio
Package robustio wraps I/O functions that are prone to failure on Windows, transparently retrying errors up to an arbitrary timeout.
|
Package robustio wraps I/O functions that are prone to failure on Windows, transparently retrying errors up to an arbitrary timeout. |
|
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. |