Commands

This document describes the LSP-level commands supported by gopls. They cannot be invoked directly by users, and all the details are subject to change, so nobody should rely on this information.

Add a dependency

Identifier: gopls.add_dependency

Adds a dependency to the go.mod file for a module.

Args:

{
	// The go.mod file URI.
	"URI": string,
	// Additional args to pass to the go command.
	"GoCmdArgs": []string,
	// Whether to add a require directive.
	"AddRequire": bool,
}

Add an import

Identifier: gopls.add_import

Ask the server to add an import path to a given Go file. The method will call applyEdit on the client so that clients don't have to apply the edit themselves.

Args:

{
	// ImportPath is the target import path that should
	// be added to the URI file
	"ImportPath": string,
	// URI is the file that the ImportPath should be
	// added to
	"URI": string,
}

Update the given telemetry counters

Identifier: gopls.add_telemetry_counters

Gopls will prepend “fwd/” to all the counters updated using this command to avoid conflicts with other counters gopls collects.

Args:

{
	// Names and Values must have the same length.
	"Names": []string,
	"Values": []int64,
}

Apply a fix

Identifier: gopls.apply_fix

Applies a fix to a region of source code.

Args:

{
	// The name of the fix to apply.
	//
	// For fixes suggested by analyzers, this is a string constant
	// advertised by the analyzer that matches the Category of
	// the analysis.Diagnostic with a SuggestedFix containing no edits.
	//
	// For fixes suggested by code actions, this is a string agreed
	// upon by the code action and golang.ApplyFix.
	"Fix": string,
	// The file URI for the document to fix.
	"URI": string,
	// The document range to scan for fixes.
	"Range": {
		"start": {
			"line": uint32,
			"character": uint32,
		},
		"end": {
			"line": uint32,
			"character": uint32,
		},
	},
	// Whether to resolve and return the edits.
	"ResolveEdits": bool,
}

Result:

{
	// Holds changes to existing resources.
	"changes": map[golang.org/x/tools/gopls/internal/protocol.DocumentURI][]golang.org/x/tools/gopls/internal/protocol.TextEdit,
	// Depending on the client capability `workspace.workspaceEdit.resourceOperations` document changes
	// are either an array of `TextDocumentEdit`s to express changes to n different text documents
	// where each text document edit addresses a specific version of a text document. Or it can contain
	// above `TextDocumentEdit`s mixed with create, rename and delete file / folder operations.
	//
	// Whether a client supports versioned document edits is expressed via
	// `workspace.workspaceEdit.documentChanges` client capability.
	//
	// If a client neither supports `documentChanges` nor `workspace.workspaceEdit.resourceOperations` then
	// only plain `TextEdit`s using the `changes` property are supported.
	"documentChanges": []{
		"TextDocumentEdit": {
			"textDocument": { ... },
			"edits": { ... },
		},
		"RenameFile": {
			"kind": string,
			"oldUri": string,
			"newUri": string,
			"options": { ... },
			"ResourceOperation": { ... },
		},
	},
	// A map of change annotations that can be referenced in `AnnotatedTextEdit`s or create, rename and
	// delete file / folder operations.
	//
	// Whether clients honor this property depends on the client capability `workspace.changeAnnotationSupport`.
	//
	// @since 3.16.0
	"changeAnnotations": map[string]golang.org/x/tools/gopls/internal/protocol.ChangeAnnotation,
}

Perform a “change signature” refactoring

Identifier: gopls.change_signature

This command is experimental, currently only supporting parameter removal. Its signature will certainly change in the future (pun intended).

Args:

{
	"RemoveParameter": {
		"uri": string,
		"range": {
			"start": { ... },
			"end": { ... },
		},
	},
	// Whether to resolve and return the edits.
	"ResolveEdits": bool,
}

Result:

{
	// Holds changes to existing resources.
	"changes": map[golang.org/x/tools/gopls/internal/protocol.DocumentURI][]golang.org/x/tools/gopls/internal/protocol.TextEdit,
	// Depending on the client capability `workspace.workspaceEdit.resourceOperations` document changes
	// are either an array of `TextDocumentEdit`s to express changes to n different text documents
	// where each text document edit addresses a specific version of a text document. Or it can contain
	// above `TextDocumentEdit`s mixed with create, rename and delete file / folder operations.
	//
	// Whether a client supports versioned document edits is expressed via
	// `workspace.workspaceEdit.documentChanges` client capability.
	//
	// If a client neither supports `documentChanges` nor `workspace.workspaceEdit.resourceOperations` then
	// only plain `TextEdit`s using the `changes` property are supported.
	"documentChanges": []{
		"TextDocumentEdit": {
			"textDocument": { ... },
			"edits": { ... },
		},
		"RenameFile": {
			"kind": string,
			"oldUri": string,
			"newUri": string,
			"options": { ... },
			"ResourceOperation": { ... },
		},
	},
	// A map of change annotations that can be referenced in `AnnotatedTextEdit`s or create, rename and
	// delete file / folder operations.
	//
	// Whether clients honor this property depends on the client capability `workspace.changeAnnotationSupport`.
	//
	// @since 3.16.0
	"changeAnnotations": map[string]golang.org/x/tools/gopls/internal/protocol.ChangeAnnotation,
}

Check for upgrades

Identifier: gopls.check_upgrades

Checks for module upgrades.

Args:

{
	// The go.mod file URI.
	"URI": string,
	// The modules to check.
	"Modules": []string,
}

Cause server to publish diagnostics for the specified files.

Identifier: gopls.diagnose_files

This command is needed by the ‘gopls {check,fix}’ CLI subcommands.

Args:

{
	"Files": []string,
}

View package documentation.

Identifier: gopls.doc

Opens the Go package documentation page for the current package in a browser.

Args:

{
	"uri": string,
	"range": {
		"start": {
			"line": uint32,
			"character": uint32,
		},
		"end": {
			"line": uint32,
			"character": uint32,
		},
	},
}

Run go mod edit -go=version

Identifier: gopls.edit_go_directive

Runs go mod edit -go=version for a module.

Args:

{
	// Any document URI within the relevant module.
	"URI": string,
	// The version to pass to `go mod edit -go`.
	"Version": string,
}

Get known vulncheck result

Identifier: gopls.fetch_vulncheck_result

Fetch the result of latest vulnerability check (govulncheck).

Args:

{
	// The file URI.
	"URI": string,
}

Result:

map[golang.org/x/tools/gopls/internal/protocol.DocumentURI]*golang.org/x/tools/gopls/internal/vulncheck.Result

Toggle gc_details

Identifier: gopls.gc_details

Toggle the calculation of gc annotations.

Args:

string

Run go generate

Identifier: gopls.generate

Runs go generate for a given directory.

Args:

{
	// URI for the directory to generate.
	"Dir": string,
	// Whether to generate recursively (go generate ./...)
	"Recursive": bool,
}

‘go get’ a package

Identifier: gopls.go_get_package

Runs go get to fetch a package.

Args:

{
	// Any document URI within the relevant module.
	"URI": string,
	// The package to go get.
	"Pkg": string,
	"AddRequire": bool,
}

List imports of a file and its package

Identifier: gopls.list_imports

Retrieve a list of imports in the given Go file, and the package it belongs to.

Args:

{
	// The file URI.
	"URI": string,
}

Result:

{
	// Imports is a list of imports in the requested file.
	"Imports": []{
		"Path": string,
		"Name": string,
	},
	// PackageImports is a list of all imports in the requested file's package.
	"PackageImports": []{
		"Path": string,
	},
}

List known packages

Identifier: gopls.list_known_packages

Retrieve a list of packages that are importable from the given URI.

Args:

{
	// The file URI.
	"URI": string,
}

Result:

{
	// Packages is a list of packages relative
	// to the URIArg passed by the command request.
	// In other words, it omits paths that are already
	// imported or cannot be imported due to compiler
	// restrictions.
	"Packages": []string,
}

Prompt user to enable telemetry

Identifier: gopls.maybe_prompt_for_telemetry

Checks for the right conditions, and then prompts the user to ask if they want to enable Go telemetry uploading. If the user responds ‘Yes’, the telemetry mode is set to “on”.

Fetch memory statistics

Identifier: gopls.mem_stats

Call runtime.GC multiple times and return memory statistics as reported by runtime.MemStats.

This command is used for benchmarking, and may change in the future.

Result:

{
	"HeapAlloc": uint64,
	"HeapInUse": uint64,
	"TotalAlloc": uint64,
}

Regenerate cgo

Identifier: gopls.regenerate_cgo

Regenerates cgo definitions.

Args:

{
	// The file URI.
	"URI": string,
}

Remove a dependency

Identifier: gopls.remove_dependency

Removes a dependency from the go.mod file of a module.

Args:

{
	// The go.mod file URI.
	"URI": string,
	// The module path to remove.
	"ModulePath": string,
	// If the module is tidied apart from the one unused diagnostic, we can
	// run `go get module@none`, and then run `go mod tidy`. Otherwise, we
	// must make textual edits.
	"OnlyDiagnostic": bool,
}

Reset go.mod diagnostics

Identifier: gopls.reset_go_mod_diagnostics

Reset diagnostics in the go.mod file of a module.

Args:

{
	"URIArg": {
		"URI": string,
	},
	// Optional: source of the diagnostics to reset.
	// If not set, all resettable go.mod diagnostics will be cleared.
	"DiagnosticSource": string,
}

Run go work [args...], and apply the resulting go.work

Identifier: gopls.run_go_work_command

edits to the current go.work file

Args:

{
	"ViewID": string,
	"InitFirst": bool,
	"Args": []string,
}

Run vulncheck

Identifier: gopls.run_govulncheck

Run vulnerability check (govulncheck).

Args:

{
	// Any document in the directory from which govulncheck will run.
	"URI": string,
	// Package pattern. E.g. "", ".", "./...".
	"Pattern": string,
}

Result:

{
	// Token holds the progress token for LSP workDone reporting of the vulncheck
	// invocation.
	"Token": interface{},
}

Run test(s)

Identifier: gopls.run_tests

Runs go test for a specific set of test or benchmark functions.

Args:

{
	// The test file containing the tests to run.
	"URI": string,
	// Specific test names to run, e.g. TestFoo.
	"Tests": []string,
	// Specific benchmarks to run, e.g. BenchmarkFoo.
	"Benchmarks": []string,
}

Start the gopls debug server

Identifier: gopls.start_debugging

Start the gopls debug server if it isn't running, and return the debug address.

Args:

{
	// Optional: the address (including port) for the debug server to listen on.
	// If not provided, the debug server will bind to "localhost:0", and the
	// full debug URL will be contained in the result.
	//
	// If there is more than one gopls instance along the serving path (i.e. you
	// are using a daemon), each gopls instance will attempt to start debugging.
	// If Addr specifies a port, only the daemon will be able to bind to that
	// port, and each intermediate gopls instance will fail to start debugging.
	// For this reason it is recommended not to specify a port (or equivalently,
	// to specify ":0").
	//
	// If the server was already debugging this field has no effect, and the
	// result will contain the previously configured debug URL(s).
	"Addr": string,
}

Result:

{
	// The URLs to use to access the debug servers, for all gopls instances in
	// the serving path. For the common case of a single gopls instance (i.e. no
	// daemon), this will be exactly one address.
	//
	// In the case of one or more gopls instances forwarding the LSP to a daemon,
	// URLs will contain debug addresses for each server in the serving path, in
	// serving order. The daemon debug address will be the last entry in the
	// slice. If any intermediate gopls instance fails to start debugging, no
	// error will be returned but the debug URL for that server in the URLs slice
	// will be empty.
	"URLs": []string,
}

Start capturing a profile of gopls' execution

Identifier: gopls.start_profile

Start a new pprof profile. Before using the resulting file, profiling must be stopped with a corresponding call to StopProfile.

This command is intended for internal use only, by the gopls benchmark runner.

Args:

struct{}

Result:

struct{}

Stop an ongoing profile

Identifier: gopls.stop_profile

This command is intended for internal use only, by the gopls benchmark runner.

Args:

struct{}

Result:

{
	// File is the profile file name.
	"File": string,
}

Run test(s) (legacy)

Identifier: gopls.test

Runs go test for a specific set of test or benchmark functions.

Args:

string,
[]string,
[]string

Run go mod tidy

Identifier: gopls.tidy

Runs go mod tidy for a module.

Args:

{
	// The file URIs.
	"URIs": []string,
}

Toggle gc_details

Identifier: gopls.toggle_gc_details

Toggle the calculation of gc annotations.

Args:

{
	// The file URI.
	"URI": string,
}

Update go.sum

Identifier: gopls.update_go_sum

Updates the go.sum file for a module.

Args:

{
	// The file URIs.
	"URIs": []string,
}

Upgrade a dependency

Identifier: gopls.upgrade_dependency

Upgrades a dependency in the go.mod file for a module.

Args:

{
	// The go.mod file URI.
	"URI": string,
	// Additional args to pass to the go command.
	"GoCmdArgs": []string,
	// Whether to add a require directive.
	"AddRequire": bool,
}

Run go mod vendor

Identifier: gopls.vendor

Runs go mod vendor for a module.

Args:

{
	// The file URI.
	"URI": string,
}

List current Views on the server.

Identifier: gopls.views

This command is intended for use by gopls tests only.

Result:

[]{
	"ID": string,
	"Type": string,
	"Root": string,
	"Folder": string,
	"EnvOverlay": []string,
}

Fetch workspace statistics

Identifier: gopls.workspace_stats

Query statistics about workspace builds, modules, packages, and files.

This command is intended for internal use only, by the gopls stats command.

Result:

{
	"Files": {
		"Total": int,
		"Largest": int,
		"Errs": int,
	},
	"Views": []{
		"GoCommandVersion": string,
		"AllPackages": {
			"Packages": int,
			"LargestPackage": int,
			"CompiledGoFiles": int,
			"Modules": int,
		},
		"WorkspacePackages": {
			"Packages": int,
			"LargestPackage": int,
			"CompiledGoFiles": int,
			"Modules": int,
		},
		"Diagnostics": int,
	},
}