gopls/v0.17.0

This release includes a variety of new features, bug fixes, and performance improvements. It is also the first version of gopls to require the latest released version of the Go toolchain, which should be downloaded transparently during the gopls installation process.

go install golang.org/x/tools/[email protected]

New support policies

With this release, we are narrowing our official support window to align with the Go support policy. This will reduce the considerable costs to us of testing against older Go versions, allowing us to spend more time fixing bugs and adding features that benefit the majority of gopls users who run recent versions of Go.

This narrowing is in two dimensions: build compatibility refers to the versions of the Go toolchain that can be used to build gopls, and go command compatibility refers to the versions of the go command that can be used by gopls to list information about packages and modules in your workspace.

Build compatibility: the most recent major Go version

As described in the v0.16.0 release notes, building the latest version of gopls will now require the latest major version of the Go toolchain. Therefore this release ([email protected]) must be built with Go 1.23.1 or later. Thanks to automatic toolchain upgrades, if your system Go version is at least Go 1.21.0 and you have the GOTOOLCHAIN environment variable set to auto (or unset), the go command will automatically download the new Go toolchain as needed, similar to upgrading a module dependency.

Go command compatibility: the 2 most recent major Go versions

The [email protected] releases will be the final versions of gopls to nominally support integrating with more than the 2 most recent Go releases. In the past, we implied "best effort" support for up to 4 versions, though in practice we did not have resources to fix bugs that were present only with older Go versions. With [email protected], we narrowed this best effort support to 3 versions, primarily because users need at least Go 1.21 to benefit from automatic toolchain upgrades (see above).

Starting with [email protected], we will officially support integrating with only the 2 most recent major versions of the go command. This is consistent with the Go support policy. See golang/go#69321 (or this comment specifically) for details.

We won't prevent gopls from being used with older Go versions (just as we don't disallow integration with arbitrary go/packages drivers), but we won't run integration tests against older Go versions nor fix bugs that are only present when used with old Go versions.

Configuration changes

• The fieldalignment analyzer, previously disabled by default, has been removed: it is redundant with the hover size/offset information displayed by v0.16.0 and its diagnostics were confusing.
• The undeclaredname analyzer has been replaced with an ordinary code action.
• The kind (identifiers) of all of gopls' code actions have changed to use more specific hierarchical names. For example, "Inline call" has changed from refactor.inline to refactor.inline.call. This allows clients to request particular code actions more precisely. The user manual now includes the identifier in the documentation for each code action.
• The experimental allowImplicitNetworkAccess setting is removed, following its deprecation in [email protected]. See golang/go#66861 for details.

New features

Refactoring

This release contains a number of new features related to refactoring. Additionally, it fixes many bugs in existing refactoring operations, primarily related to extract and inline.

These improvements move us toward a longer term goal of offering a more robust and complete set of refactoring tools. We still have much to do, and this effort will continue into 2025.

"Move parameter" refactorings

Gopls now offers code actions to move function and method parameters left or right in the function signature, updating all callers.

moveparam.mp4

Unfortunately, there is no native LSP operation that provides a good user interface for arbitrary "change signature" refactoring. We plan to build such an interface within VS Code. In the short term, we have made it possible to express more complicated parameter transformations by invoking Rename on the func keyword. This user interface is a temporary stop-gap until a better mechanism is available for LSP commands that enable client-side dialogs.

Extract declarations to new file

Gopls now offers a new code action, "Extract declarations to new file" (refactor.extract.toNewFile), which moves selected code sections to a newly created file within the same package. The created filename is chosen based on the name of the first func, type, const, or var declared in the selection. Import declarations are added or removed as needed.

The user can invoke this code action by selecting a function name, or the keywords func, const, var, type, or by placing the caret on them without selecting, or by selecting a whole declaration or multiple declarations.

Extract constant

When the selection is a constant expression, gopls now offers "Extract constant" instead of "Extract variable", and generates a const declaration instead of a local variable.

Also, extraction of a constant or variable now works at top-level, outside of any function.

Generate missing method from function call

When you attempt to call a method on a type that lacks that method, the compiler will report an error such as “type T has no field or method f”. Gopls now offers a new code action, “Declare missing method of T.f”, where T is the concrete type and f is the undefined method. The stub method's signature is inferred from the context of the call.

missing_method.mp4

Generate a test for a function or method

If the selected chunk of code is part of a function or method declaration F, gopls will offer the "Add test for F" code action, which adds a new test for the selected function in the corresponding _test.go file. The generated test takes into account its signature, including input parameters and results.

Since this feature is implemented by the server (gopls), it is compatible with all LSP-compliant editors. VS Code users may continue to use the client-side Go: Generate Unit Tests For file/function/package command, which runs the gotests tool.

Initial support for "pull" diagnostics

When initialized with the option "pullDiagnostics": true, gopls will advertise support for the textDocument.diagnostic client capability, which allows editors to request diagnostics directly from gopls using a textDocument/diagnostic request, rather than wait for a textDocument/publishDiagnostics notification.

This feature is off by default until the feature set of pull diagnostics is comparable to push diagnostics.

Hover improvements

The textDocument/hover response has slightly tweaked markdown rendering, and includes the following additional information:

• Hovering over a standard library symbol now displays information about the first Go release containing the symbol. For example, hovering over errors.As shows "Added in go1.13".
• Hovering over the package name in a package declaration includes additional package metadata.

Semantic token modifiers for top-level type constructors

The semantic tokens response now includes additional modifiers for the top-level type constructor of each symbol: interface, struct, signature, pointer, array, map, slice, chan, string, number, bool, and invalid. Editors may use this for syntax coloring.

Improved type inference for completion

When completing a call to a generic function, gopls now attempts to infer the expected argument type from surrounding context. For example, in the following scenario, gopls will infer that the argument type should be int, and will sort candidates accordingly.

func f[T any](x T) []T { return []T{x} }

var s []int = f(_)

SignatureHelp for identifiers and values

Now, function signature help can be used on any identifier with a function signature, not just within the parentheses of a function being called.

Jump to assembly definition

A Definition query on a reference to a function jumps to the function's Go func declaration. If the function is implemented in C or assembly, the function has no body. Executing a second Definition query (while already at the Go declaration) will navigate you to the assembly implementation.

yield analyzer

The new yield analyzer detects mistakes using the yield function in a Go 1.23 iterator, such as failure to check its boolean result and break out of a loop.

waitgroup analyzer

The new waitgroup analyzer detects calls to the Add method of sync.WaitGroup t...

gopls/v0.17.0-pre.4

go install golang.org/x/tools/[email protected]

This prerelease of gopls is the release candidate for v0.17.0. Please try it out!
See what's included in the draft release notes.

gopls/v0.16.2

Changes in this release

This release updates the golang.org/x/telemetry dependency to pick up fixes for the following bugs:

• golang/go#68946: unnecessary downloading of the golang.org/x/telemetry/config module
• golang/go#68358: a potential crash on Windows when the telemetry counter file is extended
• golang/go#68311: a potential hanging process if the telemetry file is truncated

Additionally, this release changes the gopls/telemetryprompt/accepted counter to be recorded each time the prompt state is checked (golang/go#68770).

None of these issues were particularly urgent, but we also wanted to make a gopls release to exercise our recently added release automation (golang/go#57643).

Future improvements

Between release automation, opt-in telemetry with crash reporting, the new VS Code prerelease extension, and toolchain upgrades, we're now able to iterate on gopls faster and significantly more safely than we could in the past. Stay tuned for new features in prereleases of [email protected] starting later this month.

gopls/v0.16.1

This release addresses the following gopls issues:

• golang/go#68116, broken links to dependencies in the new integrated doc viewer.
• golang/go#68169, a crash in package name completion.
• golang/go#68213, a crash when hovering over an interface with an empty type set.
• golang/go#68240, additional telemetry instrumentation to help inform decisions for [email protected]. (Note that this is local instrumentation only; a separate proposal will be filed to allow collection of this data from users who have opted in to sharing their telemetry data).

gopls/v0.16.0

This release includes several features and bug fixes, and is the first version of gopls to support Go 1.23. To install it, run:

go install golang.org/x/tools/[email protected]

New support policy; final support for Go 1.19 and Go 1.20

TL;DR: We are narrowing gopls' support window, but this is unlikely to affect you as long as you use at least Go 1.21 to build gopls. This doesn't affect gopls' support for the code you are writing.

This is the last release of gopls that may be built with Go 1.19 or Go 1.20, and also the last to support integrating with go command versions 1.19 and 1.20. If built or used with either of these Go versions, it will display a message advising the user to upgrade.

When using gopls, there are three versions to be aware of:

1. The gopls build go version: the version of Go used to build gopls.
2. The go command version: the version of the go list command executed by gopls to load information about your workspace.
3. 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.

This gopls release, v0.16.0, is the final release to support Go 1.19 and Go 1.20 as the gopls build go version or go command version. There is no change to gopls' support for all language versions--in fact this support has somewhat improved with the addition of the stdversion analyzer (see below).

Starting with [email protected], which will be released after Go 1.23.0 is released in August, gopls will only support the latest version of Go as the gopls build go version. However, thanks to the forward compatibility added to Go 1.21, any necessary toolchain upgrade should be handled automatically for users of Go 1.21 or later, just like any other dependency. Additionally, we are reducing our go command version support window from 4 versions to 3. Note that this means if you have at least Go 1.21 installed on your system, you should still be able to go install and use [email protected].

We have no plans to ever change our language version support: we expect that gopls will always support developing programs that target any Go version.

By focusing on building gopls with the latest Go version, we can significantly reduce our maintenance burden and help improve the stability of future gopls releases. See the newly updated support policy for details. Please comment on golang/go#65917 if you have concerns about this change.

Configuration changes

• The experimental allowImplicitNetworkAccess setting is deprecated (but not yet removed). Please comment on golang/go#66861 if you use this setting and would be impacted by its removal.

New features

Go 1.23 support

This version of gopls is the first to support the new language features of Go 1.23, including range-over-func iterators and support for the godebug directive in go.mod files.

Integrated documentation viewer

Gopls now offers a "Browse documentation" code action that opens a local web page displaying the generated documentation for Go packages and symbols in a form similar to https://pkg.go.dev. The package or symbol is chosen based on the current selection.

Use this feature to preview the marked-up documentation as you prepare API changes, or to read the documentation for locally edited packages, even ones that have not yet been saved. Reload the page after an edit to see updated documentation.

As in pkg.go.dev, the heading for each symbol contains a link to the source code of its declaration. In pkg.go.dev, these links would refer to a source code page on a site such as GitHub or Google Code Search. However, in gopls' internal viewer, clicking on one of these links will cause your editor to navigate to the declaration. (This feature requires that your LSP client honors the showDocument downcall.)

Editor support:

• VS Code: use the "Source action > Browse documentation for func fmt.Println" menu item.
  Note: source links navigate the editor but don't yet raise the window yet.
  Please upvote microsoft/vscode#208093 and microsoft/vscode#207634 (temporarily closed).
• Emacs: requires eglot v1.17. Use M-x go-browse-doc from github.com/dominikh/go-mode.el.

The linksInHover setting now supports a new value, "gopls", that causes documentation links in the the Markdown output of the Hover operation to link to gopls' internal doc viewer.

Browse free symbols

Gopls offers another web-based code action, "Browse free symbols", which displays the free symbols referenced by the selected code.

A symbol is "free" if it is referenced within the selection but declared outside of it. The free symbols that are variables are approximately the set of parameters that would be needed if the block were extracted into its own function.

Even when you don't intend to extract a block into a new function, this information can help you to tell at a glance what names a block of code depends on.

Each dotted path of identifiers (such as file.Name.Pos) is reported as a separate item, so that you can see which parts of a complex type are actually needed.

The free symbols of the body of a function may reveal that only a small part (a single field of a struct, say) of one of the function's parameters is used, allowing you to simplify and generalize the function by choosing a different type for that parameter.

Editor support:

• VS Code: use the Source action > Browse free symbols menu item.
• Emacs: requires eglot v1.17. Use M-x go-browse-freesymbols from github.com/dominikh/go-mode.el.

Browse assembly

Gopls offers a third web-based code action, "Browse assembly for f", which displays an assembly listing of the declaration of the function f enclosing the selected code, plus any nested functions such as function literals or deferred calls.

Gopls invokes the compiler to generate the report; reloading the page updates the report.

The machine architecture is determined by the build configuration that gopls selects for the current file. This is usually the same as your machine's GOARCH unless you are working in a file with go:build tags for a different architecture.

Gopls cannot yet display assembly for generic functions: generic functions are not fully compiled until they are instantiated, but any function declaration enclosing the selection cannot be an instantiated generic function.

Editor support:

• VS Code: use the "Source action > Browse assembly for f" menu item.
• Emacs: requires eglot v1.17. Use M-x go-browse-assembly from github.com/dominikh/go-mode.el.

unusedwrite analyzer

The new unusedwrite analyzer reports assignments, often to fields of structs, that have no effect because, for example, the struct is never used again:

func scheme(host string) string {
	u := &url.URL{
		Host:   host, // "unused write to field Host" (no need to construct a URL)
		Scheme: "https:",
	}
	return u.Scheme
}

This is at best an indication that the code is unnecessarily complex (for instance, some dead code could be removed), but often indicates a bug, as in this example:

type S struct { x int }

func (s S) set(x int) {
	s.x = x // "unused write to field x" (s should be a *S pointer)
}

stdversion analyzer

The new stdversion analyzer warns about the use of too-new standard library symbols based on the version of the go directive in your go.mod file. This improves our support for older language versions (see above), even when gopls is built with a recent Go version.

Consider the go.mod file and Go file below. The declaration of var alias refers to a type, types.Alias, introduced in go1.22, but the file belongs to a module that requires only go1.21, so the analyzer reports a diagnostic:

module example.com
go 1.21

package p

import "go/types"

var alias types.Alias // types.Alias requires go1.22 or later (module is go1.21)

When an individual file is build-tagged for a release of Go other than than module's version, the analyzer will apply appropriate checks for the file's version.

Two more vet analyzers

The framepointer and sigchanyzer analyzers have long been part of go vet's suite, but had been overlooked in previous versions of gopls.

Henceforth, gopls will always include any analyzers run by vet.

Hover shows size/offset info, and struct tags

Hovering over the identifier that declares a type or struct field now displays the size information for the type:

and the offset information for the field:

In addition, it reports the percentage of wasted sp...

gopls/v0.16.0-pre.1

go install golang.org/x/tools/[email protected]

This prerelease of gopls contains several new features and bug fixes, and is the first gopls version to support the new language features in the upcoming Go 1.23 release candidate. See details in the draft release notes.

gopls/v0.15.3

This release fixes the following regressions in [email protected]+:

• golang/go#66490: occasional crashes when the imports cache is refreshed.
• golang/go#66425: spurious import errors in multi-root workspaces that have go.work replace directives.
• golang/go#66636: a crash in analysis when the go.mod contains a patch version and gopls was built with Go 1.20 or earlier.
• golang/go#66677: silent breakage when the go.mod file contains Go 1.22.x, and gopls was built with Go 1.21.x.
• golang/go#66731: a rare crash when diagnostics are erroneously positioned outside the file due to malformed syntax.
• golang/go#66647: a performance regression due to unnecessary reloading following "workspace/didChangeConfiguration" notifications. Under some not-yet-understood conditions, an apparent VS Code bug causes didChangeConfiguration notifications on every keystroke. With the zero-config logic of [email protected]+, any didChangeConfiguration notification causes gopls to re-evaluate (and reload) the set of builds it tracks. With the v0.15.3 release, gopls verifies that configuration actually changed. Special thanks to @gordallott for working with us to track down this bug.

gopls/v0.15.2

This release fixes the following regressions in [email protected]+.

• golang/go#66109: a crash when encountering a test file excluded via build tags, which also contained an invalid import of a main package. This could occur in a tools_test.go file implementing the common pattern for tool dependencies.
• golang/go#66145: spurious import errors in multi-root workspaces. In some scenarios, the new zero-config logic added in [email protected] resulted in inaccurate errors about missing imports. This could occur when module A has a local replace of module B, and A and B are open as a separate workspace folders.
• golang/go#66195: a crash when working on modules with a go directive of the form go a.b.c, when gopls was compiled with Go 1.20 or earlier.
• golang/go#66090: a crash when SignatureHelp is cancelled (found via telemetry)
• golang/go#66250: a crash in references when one of the package files is missing a package declaration (found via telemetry)

These last two crashes are worth highlighting. Both were found via the (off by default) automated crash reporting added in [email protected]. Both were unlikely to get reported via GitHub issues, because they won't happen frequently enough for most LSP clients to notify the user. This is a perfect example of how telemetry can help us deliver a more reliable product than would be possible without automated reporting.

gopls/v0.15.1

This release fixes golang/go#65952, a crash in document highlighting when the cursor is in a return value for a function that has no results, such as the following example:

func f() { // <-- no results
   return 0| // <-- cursor at '|'
}

Thanks very much to @patrickpichler who both reported and fixed this bug!

We're hopeful that once Go 1.23 is released, the opt-in automated crash reporting added in gopls v0.15.0 will increase the likelihood that these types of crashes are caught before they are released.

gopls/v0.15.0

These release notes are mostly identical to the v0.15.0-pre.3 prerelease notes. Thanks to all who tested the prerelease!

go install golang.org/x/tools/[email protected]

This release introduces "zero config" gopls workspaces, which is a set of heuristics allowing gopls to Do The Right Thing when you open a Go file. We believe this addresses two of the largest pain points we hear about from our users: difficulty configuring multi-module repositories, and working on multiple GOOS/GOARCH combinations. However, this is a large change to the way gopls models your workspace, and the dynamic loading/unloading of builds may be surprising in some cases. Your feedback on this new feature is greatly appreciated. See below for more details.

New Features

Simpler workspace configuration and improved build tag support

The headline feature of this release is a rewrite of gopls's logic for associating files with build configurations that enables gopls to give accurate answers when navigating almost any Go source file on your machine.

Most features of gopls rely on type information, which comes not from the file in isolation but depends on the relationship between the file and the other files in its package, and between the package and all its dependencies; this in turn depends on go.mod and go.work files. In effect, gopls needs to decide which go build command--which working directory, package arguments, GOOS, GOARCH, build tags, and so on--would cause each file to be processed by the compiler.

Previous versions of gopls only allowed one build per workspace folder, and users had to be careful to configure the right workspace root and build environment. As a result, users often encountered confusing error messages when they opened the wrong directory, or a file that was tagged for a different operating system or architecture--the dreaded "No packages found" error. This situation was improved by the introduction of go.work files, but still required configuration and a preexisting understanding of the code being edited.

With this release, gopls now allows multiple builds per workspace, and uses heuristics to automatically derive the set of active builds. Gopls will ensure that an active build contains every module with an open file in your workspace, adding new builds and GOOS/GOARCH combinations as needed to cover files that don't match the host operating system or architecture.

For example, suppose we had a repository with three modules: moda, modb, and modc, and a go.work file using modules moda and modb. If we open the files moda/a.go, modb/b.go, moda/a_windows.go, and modc/c.go, gopls will automatically create three builds:

This allows gopls to just work when you open a Go file, but it does come with several caveats:

• This causes gopls to do more work, since it is now tracking three builds instead of one. However, the recent scalability redesign allows much of this work to be avoided through efficient caching.
• For operations invoked from a given file, such as "References" and "Implementations", gopls executes the operation in the default build for that file. For example, finding references to a symbol S from foo_linux.go will return references from the Linux build, and finding references to the same symbol S from foo_windows.go will return references from the Windows build. Gopls searches the default build for the file, but it doesn't search all the other possible builds because it is liable to be too expensive. golang/go#65757 and golang/go#65755 propose improvements to this behavior.
• When selecting a GOOS/GOARCH combination to match a build-constrained file, gopls will choose the first matching combination from this list. In some cases, that may be surprising.
• When working in a GOOS/GOARCH constrained file that does not match your default toolchain, CGO_ENABLED=0 is implicitly set, since a C toolchain for that target is unlikely to be available. This means that gopls will not work in files including import "C". golang/go#65758 may lead to improvements in this behavior.
• Gopls is currently unable to guess build flags that include arbitrary user-defined build constraints. For example, if you are trying to work on a file that is constrained by the build directive //go:build special, gopls will not guess that it needs to create a build with "buildFlags": ["-tags=special"]. golang/go#65089 proposes a heuristic by which gopls could handle this automatically.

Please provide feedback on this behavior by upvoting or commenting the issues mentioned above, or opening a new issue for other improvements you'd like to see.

Preview refactoring edits

Refactoring code actions now support resolving edits. This update enables features like code action previews within VS Code (triggered by Ctrl+Enter).

To take advantage of this new gopls feature, clients must register support via:

{
	"textDocument": {
		"codeAction": {
			"dataSupport": true,
			"resolveSupport": {
				"properties": ["edit"]
			}
		}
	}
}

Analysis & diagnostics

This release includes two new analyzers:

• The nilness analyzer reports mistakes relating to nil pointers. (In previous releases it was off by default because it was too computationally expensive, but it has since been optimized.)

• The unusedparams analyzer reports when a parameter is unused, and offers quick fixes to either rename it to _ or to remove it completely and update all callers. (This analyzer was also previously off by default because it was too imprecise, but it has been rewritten to eliminate nearly all false positives.)

Automated crash reporting (off by default)

The v1.23 release of Go expected in August contains a feature that makes it possible for a Go program to monitor itself for unexpected crashes of any kind. When gopls is built with the latest Go toolchain, it will enable this feature and save crash reports into the local telemetry database.

If you have elected to enable data collection by running this command:

$ go run golang.org/x/telemetry/cmd/gotelemetry@latest on

then these crash reports will be uploaded to https://telemetry.go.dev, helping us identify crashes and quickly fix them.

We respect your privacy. The crash reports contain only stack traces, that is, lists of names of functions from the gopls source code. They do not contain any values derived from your source code or environment.

The v0.14 release of gopls reported limited telemetry data about a handful of sites in the code where we had added explicit assertions. We are grateful to users who enabled telemetry as even this limited data proved tremendously valuable and led to numerous bug fixes.

Housekeeping

Finishing up the redesign work from v0.12, we've made a number of clarifications to the internal structure of the project, including rationalizing the directory layout, breaking dependencies, minimizing and documenting our internal APIs, and converging our tests on a standard form. We believe it is now easier than ever before to contribute features to gopls, and have been heartened by an uptick in contributions from the broader community, including:

• improved postfix completion (golang/go#64178, golang/go#64037, golang/go#59689);
• improved completion of return statements (golang/go#64266);
• a new code action (refactoring) for conversion between raw and interpreted string literals (golang/go#51200);
• updating of doc links when renaming a symbol (golang/go#64495);
• semantic highlighting for go: directives (golang/go#63538)

Bug fixes

In addition to the new features listed above, this release includes numerous minor ones, including:

• The "add missing imports" feature (typically invoked on save) is much less likely to block, a commonly reported source of freezing following a save (golang/go#59216).
• Hovering over a type now displays the set of accessible fields and methods, even though embedded fields (golang/go#61634).
• gopls supports "workspace vendoring" (golang/go#63375).
• Completion now substitutes type arguments in generic snippets when they are known (golang/go#61189).
• Completion now omits type parameters when they can be inferred from the arguments (golang/go#51783).

A major theme for this release is stability: we have fixed a large number of crash bugs.

A full list of all issues fixed can be found in the...