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...

gopls/v0.15.0-pre.3

These are release notes for a prerelease version of gopls. v0.15.0 will be released soon, but please try the prerelease if you can!

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

This release introduces "zero config" gopls, which is a set of heuristics allowing gopls to Do The Right Thing when you open a Go file. We believe this addresses the two 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:

In some cases this may cause gopls to do more work, since gopls is now tracking three builds instead of one. However, the scalability redesign we first announced in v0.12 allows us to avoid most of this work by efficient caching in a persistent store.

So, all gopls' navigation, query, analysis, and refactoring features should work equally well in both files. Notably, you'll see compiler diagnostics for the appropriate build in real time, making it much easier to make changes to cross-platform code.

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 gopls/v0.15.0 milestone.
To report a new problem, please file a new issue at https://go.dev/issues/new.

End of support for Go 1.18

This is the last release of gopls that may be built and used with Go 1.18. If built or used with Go 1.18, it will display a message advising the user to upgrade. See supported Go versions for details.

gopls/v0.14.2

This release contains just one change: an upgrade of x/telemetry to pick up support for the "local" telemetry mode (golang/go#63832).

Previously, when the telemetry mode was "off" (the default), counter data would not be uploaded, but would be written to the os.UserConfigDir()/go/telemetry/local directory of the local file system. We heard from a few users that, as a matter of policy within their organization, they need a way to prevent even this local data from being written. With this release, running gotelemetry off will stop gopls from writing this local counter data. Note that the os.UserConfigDir()/go/telemetry/mode file must be written to record the "off" state.

The new default telemetry mode is "local", which behaves the same way as "off" did before. In "local" mode, counter data is written to the local file system, but not uploaded. Local data can be inspected with the gotelemetry view command.

See golang/go#63832 for more details. Thanks again for helping us support transparent telemetry in gopls. As described in the v0.14.0 release notes, we are confident that this data will help us produce a better, faster, more reliable product. In fact this is already happening.