gopls/v0.17.1

This release fixes two crashes in gopls@v0.17.0:

• golang/go#70889: a crash in completion of type instances inside a type conversion (found via telemetry).
• golang/go#70927: a crash when a test file has a declaration with signature func(*error).

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/gopls@v0.17.0

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 (gopls@v0.17.0) 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 gopls@v0.17.x 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 gopls@v0.17.0, 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 gopls@v0.18.0, 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 gopls@v0.16.0. 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/gopls@v0.17.0-pre.4

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 gopls@v0.17.0 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 gopls@v0.17.0. (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/gopls@v0.16.0

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 gopls@v0.17.0, 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 gopls@v0.17.0.

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/gopls@v0.16.0-pre.1

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 gopls@v0.15.0+:

• 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 gopls@v0.15.0+, 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 gopls@v0.15.0+.

• 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 gopls@v0.15.0 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 gopls@v0.15.0. 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.