tools.md

Tools

This document describes the tools that power the VS Code Go extension. Each feature is provided by a command-line tool written in Go, so if you experience an issue, it may be due to the underlying tool. Some tools are required for the functionality of the extension, while others are provide optional features.

Some of the features can be provided by multiple tools, and this can be configured through the extension's settings. For more details, see the Documentation, Formatting, and Diagnostics sections below.

NOTE: If you are using the language server, gopls, most of the tools below are not needed.

Installation

Tools will be installed by default when you install the extension. You can also manually install or update all of these tools by running the Go: Install/Update Tools command. If any tools are missing, you will see an Analysis Tools Missing warning in the bottom-right corner of the editor, which will prompt you to install these tools.

VS Code Go will install the tools to your GOPATH by default, but the tools will also be found if they are on your PATH. Read our GOPATH documentation if you wish to learn about storing tools in a separate directory.

Table of Contents

• Go toolchain
• gocode
• gopkgs
• go-outline
• go-symbols
• guru
• gorename
• godoctor
• delve
• gomodifytags
• goplay
• impl
• gotests
• fillstruct
• Documentation
  • gogetdoc
  • godef
  • godoc
• Formatting
  • goreturns
  • goimports
  • gofmt
  • goformat
• Diagnostics
  • gotype-live
  • golint
  • staticcheck
  • golangci-lint
  • revive

Go toolchain

This extension requires you to install the Go toolchain, meaning that you have the go command on your PATH. To do this, follow the Go installation guide.

The build-on-save and vet-on-save features are provided by the go build and go vet commands.

gocode

Code completion is provided by gocode. It is the only tool that runs as a server. This enables it to provide completions faster, since a new process isn't starting per-keystroke.

Different versions of gocode are used depending on your version of Go.

• Go 1.9 and above: mdempsky/gocode
• Go 1.11 and above, with modules enabled: stamblerre/gocode
  • This version of gocode does not have any caching, so if you find it slow, consider using [gopls] instead.

Learn how to troubleshoot gocode.

gopkgs

This tool provides autocompletion for unimported packages.

go-outline

This tool provides the document outline feature, as well as the go to symbol in the current file feature.

go-symbols

This tool provides the go to symbol in workspace feature.

guru

This tool provides the find references and find interface implementations features.

It can also be used to provide the go to definition via the "go.docsTool" setting.

guru does not have support for Go modules, so we recommend using gopls for those features instead.

gorename

This tool provides the rename symbol feature.

gorename does not have support for Go modules, so we recommend using gopls for this feature instead.

godoctor

This tool provides the refactoring features.

It does not have support for Go modules, so we expect that gopls will provide this feature instead (golang/go#37170).

delve

This is the debugger for the Go language. It is used to provide the debugging features of this extension.

goplay

This tool provides support for the Go: Run on Go Playground command.

gomodifytags

This tool provides support for the Go: Add Tags to Struct Fields and Go: Remove Tags From Struct Fields commands.

impl

This tool provides support for the Go: Generate Interface Stubs command.

gotests

This tool provides support for the Go: Generate Unit Tests set of commands.

fillstruct

This tool provides support the Go: Fill struct command.

Documentation

Documentation tools are used for the go to definition, signature help, and quick info on hover. gogetdoc is used by default.

If gogetdoc does not work for you, a combination of the godef and godoc tools can be used. guru can also be used, but only for the go to definition behavior.

Configure this via the "go.docsTool" setting.

Formatting

Formatting tools are used by the formatting and import organization features.

goreturns is used by default. It formats the file according to the industry standard gofmt style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the "go.go.formatTool" setting.

NOTE: goreturns does not have support for Go modules, so we recommend using goimports or gopls instead.

Other format tool options include:

• goimports, which applies the default gofmt style and organizes imports, but without the behavior of filling in default return values
• gofmt only formats the file, without import organization or filling in return values
• goformat is a configurable version of gofmt

Diagnostics

Diagnostic tools are used to surface errors and warnings in your code when you save your file or as you type.

By default, gotype-live, go vet, and golint are used to provide build, vet, and lint errors. gotype-live provides build errors as you type, while go build can be used to show build errors only on save.

NOTE: gotype-live does not work with modules, so if you are using modules, we recommend using gopls instead.

The command used to provide build errors on-save is go build -i -o or go test -i -c -o (for test files). The binary generated by the build is written to a temporary location.

Other lint tools can be used instead of golint by configuring the "go.lintTool" setting. Other options include:

• staticcheck: This tool provides a great deal of useful checks that are not provided by golint. See the full list at staticcheck.io/docs/checks. It is also officially supported by the Go team at Google.
• golangci-lint: This tool combines a number of existing lint tools, including staticcheck, into one interface.
• revive: This tool is an enhancement on top of golint, and it provides additional checks.

You can use the "go.lintFlags" setting to further configure your linter of choice. Most linters can be configured via special configuration files, but you may still need to pass these command-line flags. The configuration documentation for each supported linter is listed here:

• staticcheck
• golangci-lint
• revive

Examples

Enable all golangci-lint linters and only show errors in new code:

"go.lintFlags": ["--enable-all", "--new"]

Configure revive to exclude vendor directories and apply extra configuration with a config.toml file:

"go.lintFlags": [
    "-exclude=vendor/...",
    "-config=${workspaceFolder}/config.toml"
]