[release] all: merge master to release for v0.22.0
063b57d src/goLanguageServer.ts: remove prompt when the default is changed
30b8fdb package.json: enable gopls by default
b386aef src/goMain: show welcome page for 0.22.0
8d7dda0 src/goMain: adjust showGoWelcomePage to show for prereleases
d993742 docs/settings: include enum and enum descriptions
f534354 README.md: rewrite assuming gopls is on by default
f99b5fb docs/features.md: add call hierarchy documentation
867b590 src/goTools: update hardcoded gopls latest version
bb6665d docs/features.md: remove default tool description for gopls features
61305d9 src/welcome: re-work the welcome page
0a4362f CHANGELOG.md: v0.21.1 changelog
fbd2fc4 src/goLanguageServer: partial revert of cl/280601
7f56895 src/util.ts: handle inactive languageClient
bc20520 docs: rewrite troubleshooting guide
f0680f9 docs: remove modules.md because it is not relevant with gopls enabled
bcd1314 docs/features.md: add feature gifs for snippets and fill struct
a267fff src/config: fix initConfig and WrappedConfiguration
2163a5a test/integration: increase installation test timeout
5011235 docs/features.md: Add gifs and images for features
4af88f9 docs/images: add gifs and images for features
Change-Id: Ifbf8d58690409b40922d14dd318391b468b756f1
diff --git a/README.md b/README.md
index e54f47e..45ad02a 100644
--- a/README.md
+++ b/README.md
@@ -4,119 +4,105 @@
<!--TODO: We should add a badge for the build status or link to the build dashboard.-->
-This extension provides rich language support for the [Go programming language](https://golang.org/) in VS Code.
+[The VS Code Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) provides rich language support for the [Go programming language](https://golang.org/).
-Take a look at the [Changelog](CHANGELOG.md) to learn about new features.
-
-> 📣 We plan to enable the language server ([`gopls`](docs/gopls.md)) by default in early 2021. The language server
-> provides language features like intellisense, formatting, refactoring, analysis and many more.
+> 📣 We will enable the language server ([`gopls`]) by default in the end of Jan 2021.
> We recommend switching to the language server now (`"go.useLanguageServer": true`) to confirm it works well for you.
> Please [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if you notice bugs or missing features.
-## Overview
+## Quick Start
-* [Getting started](#getting-started)
-* [Support for Go modules](#support-for-go-modules)
-* [Features](#features)
- * [Debugging](#debugging)
-* [Customization](#customization)
- * [Linter](#linter)
- * [GOPATH](#gopath)
-* [Language server](#language-server)
-* [Troubleshooting](docs/troubleshooting.md)
-* [Ask for help](#ask-for-help)
-* [Preview version](#preview-version)
-* [Contributing](#contributing)
+Welcome! 👋🏻<br/>
+Whether you are new to Go or an experienced Go developer, we hope this extension fits your needs and enhances your development experience.
-## Getting started
+- **Step 1.** If you haven't done so already, install [Go](https://golang.org) and the [VS Code Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go).
+ - [Go installation guide](https://golang.org/doc/install). This extension works best with Go 1.14+.
+ - [Manage extensions in VS Code](https://code.visualstudio.com/docs/editor/extension-gallery)
+- **Step 2.** To activate the extension, open any directory or workspace containing Go code. Once activated, the [Go status bar](docs/ui.md) will appear in the bottom left corner of the window and show the recognized Go version.
+- **Step 3.** The extension depends on [a set of extra command-line tools](#tools). If they are missing, the extension will show the "⚠️ Analysis Tools Missing" warning. Click the notification to complete the installation.
-Welcome! Whether you are new to Go or an experienced Go developer, we hope this extension will fit your needs and enhance your development experience.
+<p align="center"><img src="docs/images/installtools.gif" width=75%></img>
+<br/><em>(Install Missing Tools)</em>
+</p>
-### Install Go
+You are ready to Go :-) 🎉🎉🎉
-Before you start coding, make sure that you have already installed Go, as explained in the [Go installation guide](https://golang.org/doc/install).
+Please be sure to learn more about many [features](#features) of this extension as well as how to [customize](#customization) them. Take a look at [Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further guidance.
-If you are unsure whether you have installed Go, open the Command Palette in VS Code (Ctrl+Shift+P) and run the [`Go: Locate Configured Go Tools`](docs/commands.md#go-locate-configured-go-tools) command. If the `GOROOT` output is empty, you are missing a Go installation. For help installing Go, ask a question on the `#newbies` [Gophers Slack] channel.
+If you are new to Go, [this article](https://golang.org/doc/code.html) provides the overview on go code organization and basic `go` commands. The recent [Go open source live video](https://opensourcelive.withgoogle.com/events/go/watch?talk=session3) featured VS Code Go and demonstrated how other Gophers use the features to enhance their Go development workflow.
-### Set up your environment
+## Features
-Read about [Go code organization](https://golang.org/doc/code.html) to learn how to configure your environment. This extension works in both [GOPATH](docs/gopath.md) and [module](docs/modules.md) modes.
-We suggest using modules, as they are the new standard and become default from go 1.16 (to be released in early 2021).
+This extension provides many features, including [IntelliSense](docs/features.md#intellisense), [code navigation](docs/features.md#code-navigation), and [code editing](docs/features.md#code-editing) support. It also shows [diagnostics](docs/features.md#diagnostics) as you work and provides enhanced support for [testing](docs/features.md##run-and-test-in-the-editor) and [debugging](#debugging) your programs. See the [full feature breakdown](docs/features.md) for more details and to learn how to tune the behavior.
-Here are some additional resources for learning about how to set up your Go project:
+<p align=center><img src="docs/images/completion-signature-help.gif" width=75%></img>
+<br/><em>(Code completion and Signature Help)</em>
+</p>
-* [Using Go modules](https://blog.golang.org/using-go-modules)
-* [Modules wiki](https://github.com/golang/go/wiki/Modules)
-* [GOPATH](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
+In addition to integrated editing features, the extension provides several commands for working with Go files. You can access any of these by opening the Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and then typing in the command name. See the [full list of commands](docs/commands.md#detailed-list) provided by the extension.
-**NOTE: If you are using modules, we recommend using the Go [language server](#language-server), which is explained below.**
+<p align=center><img src="docs/images/toggletestfile.gif" width=75%></img>
+<br/><em>(Toggle Test File)</em></p>
+**⚠️ Note**: the default syntax highlighting for Go files is provided by the [TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS Code, not by this extension.
-### Install the extension
+## Tools
-If you haven't already done so, install and open [Visual Studio Code](https://code.visualstudio.com). Navigate to the Extensions pane (Ctrl+Shift+X). Search for "Go" and install this extension (the publisher ID is `golang.Go`).
+The extension uses a few command-line tools developed by the Go community. In particular, `go`, `gopls`, and `dlv` are the main tools that implement build/test, language features, and debugging functionalities of this extension. See [Tools](docs/tools.md) for the full list of tools the extension depends on.
-### Activate the Go extension
+In order to locate the command-line tools, the extension searches `$GOPATH/bin` and directories specified in the `PATH` environment variable (or `Path` in Windows) with which the VS Code process has started. If the tools are not found, the extension will prompt you to install the missing tools and show the "⚠️ Analysis Tools Missing" warning in the bottom right corner. Please install them by responding to the warning notification, or by manually running the `Go: Install/Update Go Tools` command. The extension will run the [`go get`](https://golang.org/cmd/go) command to install them.
-To activate the extension, open any directory or workspace containing Go code.
+## Setting up your workspace
-You should immediately see a prompt in the bottom-right corner of your screen titled `Analysis Tools Missing`. This extension relies on a suite of [command-line tools](docs/tools.md), which must be installed separately. Accept the prompt, or use the [`Go: Install/Update Tools`](docs/commands.md#go-installupdate-tools) command to pick which tools you would like to install.
+[Modules](https://golang.org/ref/mod) are how Go manages the versions and dependencies in the recent versions of Go. Modules replace the old `GOPATH`-based approach to specifying which source files are used in a given build, and they are the default build mode after go1.16. While this extension continues to support both Go modules and `GOPATH`-mode, we highly recommend Go development in module mode. If you are working on existing projects, please consider migrating to modules.
-If you see an error that looks like `command Go: Install/Update Tools not found`, it means that the extension has failed to activate and register its commands. Please uninstall and then reinstall the extension.
-
-When the extension is active, you should see the [Go status bar](docs/ui.md) in the bottom left corner.
-
-### Start coding
-
-You're ready to Go!
-
-Be sure to learn more about the many [features](#features) of this extension, as well as how to [customize](#customization) them. Take a look at [Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further guidance.
-
-## Support for Go modules
-
-[Go modules](https://blog.golang.org/using-go-modules) have added a lot of complexity to the way that most tools and features are built for Go. Some, but not all, [features](docs/features.md) of this extension have been updated to work with Go modules. Some features may also be slower in module mode. The [features documentation](docs/features.md) contains more specific details.
-
-**In general, we recommend using [`gopls`, the official Go language server](https://golang.org/s/gopls), if you are using modules.** Read more [below](#language-server) and in the [`gopls` documentation](docs/gopls.md).
-
-## [Features](docs/features.md)
-
-This extension has a wide range of features, including [Intellisense](docs/features.md#intellisense), [code navigation](docs/features.md#code-navigation), and [code editing](docs/features.md#code-editing) support. It also shows build, vet, and lint [diagnostics](docs/features.md#diagnostics) as you work and provides enhanced support for [testing](docs/features.md##run-and-test-in-the-editor) and [debugging](#debugging) your programs. For more detail, see the [full feature breakdown](docs/features.md).
-
-In addition to integrated editing features, the extension also provides several commands for working with Go files. You can access any of these by opening the Command Palette (Ctrl+Shift+P) and typing in the name of the command. See the [full list of commands](docs/commands.md#detailed-list) provided by the extension.
-
-The majority of the extension's functionality comes from command-line tools. If you're experiencing an issue with a specific feature, you may want to investigate the underlying tool. You can do this by taking a look at the [full list of tools used by this extension](docs/tools.md).
-
-### [Debugging](docs/debugging.md)
-
-Debugging is a major feature offered by this extension. For a comprehensive overview of how to debug your Go programs, please see the [debugging guide](docs/debugging.md).
+Unlike the traditional `GOPATH`-mode, module mode does not require the workspace to be under `GOPATH` nor to use a specific structure. A module is defined by a tree of Go source files with a `go.mod` file in the tree's root directory. Your project may involve one or more modules. If you are working with multiple modules or uncommon project layouts, you will need to specifically configure your workspace, so features like references can work across modules. Please see the [Workspace document](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for information on supported workspace layouts.
## Customization
-This extension needs no configuration; it works out of the box. However, you may wish to modify settings to adjust your experience.
+The extension needs no configuration and should work out of the box. However, you may wish to modify settings to meet your needs. Please see the [Settings documentation](docs/settings.md) for the comprehensive list of extension configuration options.
-Many of the features are configurable to your preference. A few common modifications are mentioned below, but take a look at the [full list of settings](docs/settings.md) for an overview.
+### Choosing a different version of Go
-### [Linter](docs/tools.md#diagnostics)
+The extension chooses the `go` command from the `$PATH` (or `$Path`) environment variable by default. You can configure this extension to choose a different version of Go with one of the following options.
-A commonly customized feature is the linter, which is a tool used to provide coding style feedback and suggestions. By default, this extension uses the official [`golint`].
+ - (Preferred) Adjust your `$PATH` or `$Path` environment variable, and *open VS Code with the adjusted environment* variable, or
+ - Use the Go extension's `"Go: Choose Go Environment"` command that opens a [menu](docs/ui.md) to change the `go` version, or
+ - Use the `"go.alternateTools"` settings and specify the absolute path to the `go` command.
+ ```
+ "go.alternateTools": { "go": "/path/to/go/command" }
+ ```
-However, you are welcome to use more advanced options like [`staticcheck`](https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview), [`golangci-lint`](https://golangci-lint.run/), or [`revive`](https://pkg.go.dev/github.com/mgechev/revive?tab=overview). This can be configured via the [`"go.lintTool"`](docs/settings.md#go.lintTool) setting, and the different options are explained more thoroughly in the [list of diagnostic tools](docs/tools.md#diagnostics).
+**note**: For historical reasons, some users use the `"go.goroot"` settings or the `GOROOT` environment variable to select the Go SDK location. With the recent versions of Go, that's unnecessary in most cases.
-### [GOPATH](docs/gopath.md)
+### Configuring the installation of command-line tools
-Advanced users may want to set different `GOPATH`s for different projects or install the Go tools to a different `GOPATH`. This is possible and explained in the [`GOPATH documentation`](docs/gopath.md).
+`Go: Install/Update Tools` command uses the `go get` command to download and install requested tools. By default, `go get` will install the compiled tools in one of the following directories.
+ - the directory the `$GOBIN` environment variable specifies, or
+ - the `bin` directory under the first `$GOPATH` (or `"go.gopath"`) directory, or
+ - the `$HOME/go/bin` (or `$USERPROFILE/go/bin`) directory.
+
+Some users prefer to choose a different installation location. In that case, use the `"go.toolsGopath"` setting.
-## [Language Server](docs/gopls.md)
+The extension finds the required tools by their names (`go`, `gopls`, `dlv`, ...). Sometimes, users may need to wrap the tools or want the extension to pick an alternate tool. `"go.alternateTools"` provides a way to configure the extension to use different tools.
-In the default mode, the Go extension relies upon a suite of [command-line tools](docs/tools.md). A new alternative is to use a [single language server](https://langserver.org/), which provides language features through the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
+### Using a custom linter
-The Go team at Google has developed [`gopls`](docs/gopls.md), which is the official Go language server. It is currently in an alpha state and under active development.
+A commonly customized feature is the linter, which is a tool used to provide coding style feedback and suggestions.
+This extension supports linters such as `staticcheck`, `golangci-lint`, and `revive`. You can choose one of them using the `"go.lintTool"` setting. For customization of the linter, please consult the tools' documentation.
-[`gopls`] is recommended for projects that use Go modules.
+If you are using `staticcheck`, you can enable it via the `gopls` settings block by setting
+```
+ "gopls": {
+ "ui.diagnostic.staticcheck": true
+ }
+```
-To opt-in to the language server, set [`"go.useLanguageServer"`](docs/settings.md#go.useLanguageServer) to `true` in your settings. You should then be prompted to install [`gopls`]. If you are not prompted, you can install `gopls` manually by running the [`Go: Install/Update Tools`](docs/commands.md#go-installupdate-tools) command and selecting `gopls`.
+<!-- TODO: maybe have tips.md or settings.md to discuss more customization and setting tips (e.g. activating signature help after completion, disabling snippets to reduce the interference with gopls' suggestions, setting proxies, etc.) -->
-For more information, see the [`gopls` documentation](docs/gopls.md).
+### Working on the Go standard library and the Go tools
+
+When you need to work on the Go project (https://go.googlesource.com/go), please follow the instruction in the [Standard Library Development](docs/stdlib.md) to adjust your settings.
## Ask for help
@@ -140,6 +126,6 @@
[MIT](LICENSE)
-[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
[Gophers Slack]: https://gophers.slack.com/
[`gopls`]: https://golang.org/s/gopls
+[`go`]: https://golang.org/cmd/go
diff --git a/docs/commands.md b/docs/commands.md
index 03ae8a4..7777fab 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,6 +1,6 @@
# Commands
-In addition to integrated editing features, this extension offers a number of commands, which can be executed manually through the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (Ctrl+Shift+P).
+In addition to integrated editing features, this extension offers a number of commands, which can be executed manually through the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (Ctrl+Shift+P on Linux/Windows or Cmd+Shift+P on Mac OS).
Some of these commands are also available in the VS Code context menu (right-click). To control which of these commands show up in the editor context menu, update the [`"go.editorContextMenuCommands"`](settings.md#go.editorContextMenuCommands) setting.
diff --git a/docs/debugging.md b/docs/debugging.md
index e41eda1..65c64e3 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -112,7 +112,7 @@
buildFlags | Build flags to pass to the Go compiler. This corresponds to `dlv`'s `--build-flags` flag.
dlvFlags | Extra flags passed to `dlv`. See `dlv help` for the full list of supported flags. This is useful when users need to pass less commonly used or new flags such as `--only-same-user`, `--check-go-version`. Note that some flags such as `--log-output`, `--log`, `--init`, `--api-version` already have corresponding properties in the debug configuration, and flags such as `--listen` and `--headless` are used internally. If they are specified in `dlvFlags`, they may be ignored or cause an error.
remotePath | If remote debugging (`mode`: `remote`), this should be the absolute path to the package being debugged on the remote machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant. Becomes the first mapping in substitutePath.
-substitutePath | An array of mappings from an absolute local path to an absolute remote path that is used by the debuggee. The debug adapter will replace the local path with the remote path in all of the calls. The mappings are applied in order, and the first matching mapping is used. This can be used to map files that have moved since the program was built, different remote paths, and symlinked files or directories. This is intended to be equivalent to the [substitute-path]((https://github.com/go-delve/delve/tree/master/Documentation/cli#config)(https://github.com/go-delve/delve/tree/master/Documentation/cli#config)) configuration, and will eventually configure substitute-path in Delve directly.
+substitutePath | An array of mappings from an absolute local path to an absolute remote path that is used by the debuggee. The debug adapter will replace the local path with the remote path in all of the calls. The mappings are applied in order, and the first matching mapping is used. This can be used to map files that have moved since the program was built, different remote paths, and symlinked files or directories. This is intended to be equivalent to the [substitute-path](https://github.com/go-delve/delve/tree/master/Documentation/cli#config) configuration, and will eventually configure substitute-path in Delve directly.
cwd | The working directory to be used in running the program. If remote debugging (`mode`: `remote`), this should be the absolute path to the working directory being debugged on the local machine. See the section on [Remote Debugging](#remote-debugging) for further details. [golang/vscode-go#45](https://github.com/golang/vscode-go/issues/45) is also relevant.
processId | This is the process ID of the executable you want to debug. Applicable only when using the `attach` request in `local` mode.
diff --git a/docs/features.md b/docs/features.md
index 8c54edc..7007ce7 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -2,10 +2,6 @@
This document describes the features supported by this extension.
-If you are using the Go language server, `gopls`, please the [gopls documentation](gopls.md) instead. (You can check if you are using `gopls` by opening your VS Code settings and checking if [`"go.useLanguageServer"`](settings.md#go.useLanguageServer) is `true`.)
-
-If you are using Go modules **without** the language server, some of the features listed below will not be available.
-
## Table of Contents
* [IntelliSense](#intellisense)
@@ -46,79 +42,106 @@
### Code completion
-Completion results appear for symbols as you type. You can trigger this manually with the Ctrl+Space shortcut. This feature is provided by the [`gocode`](tools.md#gocode) tool.
+Completion results appear for symbols as you type. You can trigger this manually with the Ctrl+Space shortcut.
-Autocompletion is also supported for packages you have not yet imported into your program. This feature is provided by the [`gopkgs`](tools.md#gopkgs) tool.
+Autocompletion is also supported for packages you have not yet imported into your program.
+
+<div style="text-align: center;"><img src="images/completion-signature-help.gif" alt="Code completion and signature help" style="width: 75%"> </div>
### Signature help
-Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
-
+Information about the signature of a function pops up as you type in its parameters.
### Quick info on hover
-Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
+Documentation appears when you hover over a symbol.
## [Code Navigation](https://code.visualstudio.com/docs/editor/editingevolved)
### Go to definition
-Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#documentation) tool, but it can also be provided by a combination of [`godef`](tools.md#documentation) and [`godoc`](tools.md#documentation) (configured via the [`"go.docsTool"`](settings.md#go.docsTool) setting).
+Jump to or peek a symbol's declaration.
+
+<div style="text-align: center;"><img src="images/gotodefinition.gif" alt="Go to definition using the context menu" style="width: 75%"> </div>
### Find references
-Find or go to the references of a symbol. This feature is provided the [`guru`](tools.md#guru) tool.
+Find or go to the references of a symbol.
This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
+<div style="text-align: center;"><img src="images/findallreferences.gif" alt="Find references using the context menu" style="width: 75%"> </div>
+
### Find interface implementations
-Find the concrete types that implement a given interface. This feature is provided by the [`guru`](tools.md#guru) tool.
+Find the concrete types that implement a given interface.
This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
+<div style="text-align: center;"><img src="images/implementations.gif" alt="Go to implementations for Server that implements http.Handler and then finds all implementations of http.Handler in the workspace" style="width: 75%"> </div>
+
### [Go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)
Search for symbols in your file or workspace by opening the Command Palette (Ctrl+Shift+P) and typing `@` for symbols in the current file or `#` for symbols in the entire workspace.
-This feature is provided by the [`go-outline`](tools.md#go-outline) and [`go-symbols`](tools.md#go-symbols) tools.
+<div style="text-align: center;"><img src="images/workspace-symbols.gif" alt="Use Workspace Symbols to locate Hello in the workspace" style="width: 75%"> </div>
+
+### Call hierarchy
+
+Show all calls from or to a function.
+
+<div style="text-align: center;"><img src="images/callhierarchy.gif" alt="Show call hierarchy and investigate callers of a function" style="width: 75%"> </div>
### Document outline
See all the symbols in the current file in the VS Code's [Outline view](https://code.visualstudio.com/docs/getstarted/userinterface#_outline-view).
-This feature is provided by the [`go-outline`](tools.md#go-outline) tool.
+<div style="text-align: center;"><img src="images/outline.png" alt="Outline of a Go file" style="width: 75%"> </div>
### Toggle between code and tests
Quickly toggle between a file and its corresponding test file by using the [`Go: Toggle Test File`](commands.md#go-toggle-test-file) command.
+<div style="text-align: center;"><img src="images/toggletestfile.gif" alt="Toggle between reverse.go and reverse_test.go" style="width: 75%"> </div>
+
## Code Editing
### [Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets)
Predefined snippets for quick coding. These snippets will appear as completion suggestions when you type. Users can also define their own custom snippets (see [Snippets in Visual Studio Code](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets)).
+<div style="text-align: center;"><img src="images/snippets-tys.gif" alt="Use the struct type snippet" style="width: 75%"> </div>
+
### Format and organize imports
-Format code and organize imports, either manually or on save. The code is formatted by the [`gofmt`](tools.md#formatting) tool, which is the standard for Go code. Imports are added automatically to your file via the [`goimports`](tools.md#formatting) tool, which is also an industry standard. By default, this extension also uses the [`goreturns`](tools.md#formatting) tool, which automatically fills in default return values for functions.
+Format code and organize imports, either manually or on save.
-The behavior of the formatter can be configured via the [`"go.formatTool"`](settings.md#go.formatTool) tool setting. The [troubleshooting guide](troubleshooting.md#formatting) gives more details and explains how to [disable formatting](troubleshooting.md#disable-formatting) entirely.
+The [troubleshooting guide](troubleshooting.md#formatting) gives more details and explains how to [disable formatting](troubleshooting.md#disable-formatting) entirely.
#### Add import
Manually add a new import to your file through the [`Go: Add Import`](commands.md#go-add-import) command. Available packages are offered from your `GOPATH` and module cache.
+<div style="text-align: center;"><img src="images/addimport.gif" alt="Add byte import to Go file" style="width: 75%"> </div>
+
+
### [Rename symbol](https://code.visualstudio.com/docs/editor/refactoring#_rename-symbol)
-Rename all occurrences of a symbol in your workspace. This feature is provided by the [`gorename`](tools.md#gorename) tool.
+Rename all occurrences of a symbol in your workspace.
**Note**: For undo after rename to work on Windows, you need to have `diff` tool on your `PATH`.
This feature is not available if you are using Go modules **without** [`gopls`](gopls.md), the Go language server.
+<div style="text-align: center;"><img src="images/rename.gif" alt="Rename an exported variable in Go workspace" style="width: 75%"> </div>
+
+
### Refactor
-Extract a piece of code to a local variable or to its own function using the [`Go: Extract to variable`](commands.md#go-extract-to-variable) and [`Go: Extract to function`](commands.md#go-extract-to-function) commands. These features are provided by the [`godoctor`](tools.md#godoctor) tool. These features do not work with Go modules, but they will be supported by [`gopls`] in the future (see [golang/go#37170](https://github.com/golang/go/issues/37170)).
+Extract a piece of code to a local variable or to its own function using the [`Go: Extract to variable`](commands.md#go-extract-to-variable) and [`Go: Extract to function`](commands.md#go-extract-to-function) commands.
+
+For known issues with this feature see [golang/go#37170](https://github.com/golang/go/issues/37170).
+
+<div style="text-align: center;"><img src="images/extract-variable.gif" alt="Extract to variable followed by a rename" style="width: 75%"> </div>
## Code Generation
@@ -126,17 +149,25 @@
Use the [`Go: Add Tags to Struct Fields`](commands.md#go-add-tags-to-struct-fields) command to automatically generate or remove [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. This feature is provided by the [`gomodifytags`](tools.md#gomodifytags) tool.
+<div style="text-align: center;"><img src="images/addtagstostructfields.gif" alt="Add tags to struct fields" style="width: 75%"> </div>
+
### Generate interface implementation
Use the [`Go: Generate Interface Stubs`](commands.md#go-generate-interface-stubs) command to automatically generate method stubs for a given interface. This feature is provided by the [`impl`](tools.md#impl) tool.
+<div style="text-align: center;"><img src="images/generateinterfaceimplementation.gif" alt="Generate functions to implement an interface" style="width: 75%"> </div>
+
### Generate unit tests
Easily generate unit tests for your project by running one of the [`Go: Generate Unit Tests for ...`](commands.md#go-generate-unit-tests-for-file) commands. This can be done at a function, file, or package level. This feature is provided by the [`gotests`](tools.md#gotests) tool.
+<div style="text-align: center;"><img src="images/generateunittestsforfunction.gif" alt="Generate unit tests for a function" style="width: 75%"> </div>
+
### Fill struct literals
-Use the [`Go: Fill struct`](commands.md#fill-struct) command to automatically fill a struct literal with its default values. This command is provided by the [`fillstruct`](tools.md#fillstruct).
+Use the [`Go: Fill struct`](commands.md#fill-struct) command to automatically fill a struct literal with its default values.
+
+<div style="text-align: center;"><img src="images/fillstructliterals.gif" alt="Fill struct literals" style="width: 75%"> </div>
## Diagnostics
@@ -178,7 +209,7 @@
### Code Coverage
-Show code coverage in the editor, either after running a test or on-demand. This can be done via the commands: [`Go: Apply Cover Profile`](commands.md#go-apply-cover-profile) and [`Go: Toggle Test Coverage in Current Package`](commands.go-toggle-test-coverage-in-current-package).
+Show code coverage in the editor, either after running a test or on-demand. This can be done via the commands: [`Go: Apply Cover Profile`](commands.md#go-apply-cover-profile) and [`Go: Toggle Test Coverage in Current Package`](commands.md#go-toggle-test-coverage-in-current-package).
## [Debugging](debugging.md)
diff --git a/docs/gopath.md b/docs/gopath.md
index 60c6346..23caa69 100644
--- a/docs/gopath.md
+++ b/docs/gopath.md
@@ -1,8 +1,14 @@
# `GOPATH`
-The `GOPATH` environment variable is a fundamental part of writing Go code **without** [Go modules]. It specifies the location of your workspace, and it defaults to `$HOME/go`. A `GOPATH` directory contains `src`, `bin`, and `pkg` directories. Your code is typically located in the `$GOPATH/src` directory.
+The `GOPATH` environment variable is a fundamental part of writing Go code
+**without** [Go modules]. It specifies the location of your workspace, and it
+defaults to `$HOME/go`. A `GOPATH` directory contains `src`, `bin`, and `pkg`
+directories. Your code is typically located in the `$GOPATH/src` directory.
-If you are not familiar with Go and `GOPATH`, please first read about [writing Go code with `GOPATH`](https://golang.org/doc/gopath_code.html#GOPATH).
+If you are not familiar with Go and `GOPATH`, please first read about [writing
+Go code with `GOPATH`](https://golang.org/doc/gopath_code.html#GOPATH).
+
+**If you are just starting out with Go, we recommend [using Go modules](https://blog.golang.org/using-go-modules) instead of GOPATH.**
## Overview
@@ -21,7 +27,7 @@
## Setting `GOPATH`
-If you have chosen not to use [Go modules], you will need to configure your `GOPATH`. Modules have largely eliminated the need for a `GOPATH`, so if you're interested in using them, taking a look at the [modules documentation](modules.md) for the VS Code Go extension.
+If you have chosen not to use [Go modules], you will need to configure your `GOPATH`.
Setting `GOPATH` is typically as simple as setting the environment variable once in your system's configuration. Take a look at the [Setting `GOPATH` Wiki](https://github.com/golang/go/wiki/SettingGOPATH) if you're unsure how to do this.
diff --git a/docs/gopls.md b/docs/gopls.md
deleted file mode 100644
index fbea475..0000000
--- a/docs/gopls.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# [`gopls`], the Go language server
-
-[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It was developed in response to the release of [Go modules], and it is the recommended approach when working with [Go modules] in VS Code. [`gopls`] is not enabled by default yet and users have to opt in by changing from [their settings](#enable-the-language-server). We plan to switch the default and enable it by default early 2021.
-
-[`gopls`] has its own [documentation pages](https://github.com/golang/tools/tree/master/gopls/doc), and they should be treated as the source of truth for how to use [`gopls` in VS Code](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md).
-
-## Overview
-
-* [Background](#background)
-* [Enable the language server](#enable-the-language-server)
- * [Automatic updates](#automatic-updates)
-* [Configuration](#configuration)
- * [Ignored settings](#ignored-settings)
-* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
-* [Additional resources](#additional-resources)
-
-## Background
-
-This extension functions by shelling out to a number of command-line tools. This introduces complexity, as each feature is provided by a different tool. Language servers enable all editors to support all programming languages without these individualized tools. They also provide speed improvements, as they can cache and reuse results.
-
-[`gopls`] is the official Go language server. Using [`gopls`] will enable the VS Code Go extension to provide high-quality Go support as the language evolves.
-
-To learn more about the context behind [`gopls`], you can watch the [Go pls, stop breaking my editor](https://www.youtube.com/watch?v=EFJfdWzBHwE) talk at GopherCon 2019.
-
-## Enable the language server
-
-To start using the language server, set [`"go.useLanguageServer": true`](settings.md#go.useLanguageServer) in your VS Code Go settings.
-
-You should see a prompt to install `gopls`. If you do not see a prompt, please run the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command and select `gopls`.
-
-### Automatic updates
-
-The `gopls` team releases new versions of `gopls` approximately once a month ([release notes](https://github.com/golang/go/issues/33030)). The Go extension will automatically detect that a new version has been released, and a pop-up will appear prompting you to update.
-
-If you would like to opt-out of these updates, set [`"go.useGoProxyToCheckForToolUpdates"`](settings.md#go.useGoProxyToCheckForToolUpdates) to `false`.
-
-## Configuration
-
-There are a number of VS Code Go settings for controlling the language server.
-
-* [`"go.toolsEnvVars"`](settings.md#go.toolsEnvVars) is used when launching `gopls` for the workspace.
-* [`"go.buildFlags"`](settings.md#go.buildFlags) and [`"go.buildTags"`](settings.md#go.buildTags) are propagated to `gopls`.
-* [`"go.languageServerExperimentalFeatures"`](settings.md#go.languageServerExperimentalFeatures) allows you to disable certain features.
- * `"diagnostics": false` disables diagnostic warnings from `gopls`. You might want to disable these if you don't like the diagnostics changing as you type.
- * `"documentLink": false` is deprecated by `"gopls": { "importShortcut": false }` setting. It was originally meant to disable document links. The reason to disable these is explained in [golang/go#39065](https://github.com/golang/go/issues/39065): the Ctrl+Click shortcut for clicking on a link collides with the Ctrl+Click shortcut for go-to-definition.
-* [`"go.languageServerFlags"`](settings.md#go.languageServerFlags) allows you to pass flags to the `gopls` process.
- * The `-rpc.trace` flag enables verbose debug logging.
-* [`"gopls"`](settings.md#gopls) allows to fine-tune gopls behavior or override the settings propagated from the extension settings (e.g. `"go.buildFlags"`, `"go.toolsEnvVars"`) as shown in the [`gopls` VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md). The sets of settings recognized by the extension and the gopls may differ if you use an old version or a pre-release version of `gopls`. In that case, the source of truth is in [the documentation](https://github.com/golang/tools/tree/master/gopls/doc/settings.md) in the `gopls` project.
-
-### Ignored settings
-
-Some of the extension's settings are irrelevant when `gopls` is enabled. For example, the extension no longer uses `gocode` or `guru`, so the corresponding settings are no longer applicable. We are trying to document that in the settings' description and the [settings documentation](settings.md). When you find incompelete documentation, please file an issue or send a PR!
-
-## Additional resources
-
-If you encounter an issue while using [`gopls`], take a look at these resources:
-
-* [VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md)
-* [Known issues](https://github.com/golang/tools/blob/master/gopls/doc/status.md#known-issues)
-* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
-* [`gopls` issue tracker](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
-
-If you are unable to resolve your issue, please ask for help. Make sure to mention that you are using `gopls`. Here's how to ask for guidance:
-
-* [File a VS Code Go issue](https://github.com/golang/vscode-go/issues/new/choose). If it is a bug in `gopls`, we will transfer your issue to the [`gopls` issue tracker](https://github.com/golang/go/issues).
-* [File a `gopls` issue](https://github.com/golang/go/issues/new) directly.
-* Ask a question in the `#gopls` channel on [Gophers Slack].
-* Ask a question in the `#vscode` channel on [Gophers Slack].
-
-[Go modules]: https://blog.golang.org/using-go-modules
-[`gopls`]: https://golang.org/s/gopls
-[Gophers Slack]: https:/gophers.slack.com/
diff --git a/docs/images/addimport.gif b/docs/images/addimport.gif
new file mode 100644
index 0000000..facb79c
--- /dev/null
+++ b/docs/images/addimport.gif
Binary files differ
diff --git a/docs/images/addtagstostructfields.gif b/docs/images/addtagstostructfields.gif
new file mode 100644
index 0000000..b8efb03
--- /dev/null
+++ b/docs/images/addtagstostructfields.gif
Binary files differ
diff --git a/docs/images/callhierarchy.gif b/docs/images/callhierarchy.gif
new file mode 100644
index 0000000..86a1cd2
--- /dev/null
+++ b/docs/images/callhierarchy.gif
Binary files differ
diff --git a/docs/images/completion-signature-help.gif b/docs/images/completion-signature-help.gif
new file mode 100644
index 0000000..f3b4b93
--- /dev/null
+++ b/docs/images/completion-signature-help.gif
Binary files differ
diff --git a/docs/images/extract-variable.gif b/docs/images/extract-variable.gif
new file mode 100644
index 0000000..189f8f9
--- /dev/null
+++ b/docs/images/extract-variable.gif
Binary files differ
diff --git a/docs/images/fillstructliterals.gif b/docs/images/fillstructliterals.gif
new file mode 100644
index 0000000..9ea7fc2
--- /dev/null
+++ b/docs/images/fillstructliterals.gif
Binary files differ
diff --git a/docs/images/findallreferences.gif b/docs/images/findallreferences.gif
new file mode 100644
index 0000000..21def35
--- /dev/null
+++ b/docs/images/findallreferences.gif
Binary files differ
diff --git a/docs/images/generateinterfaceimplementation.gif b/docs/images/generateinterfaceimplementation.gif
new file mode 100644
index 0000000..e8e8dd1
--- /dev/null
+++ b/docs/images/generateinterfaceimplementation.gif
Binary files differ
diff --git a/docs/images/generateunittestsforfunction.gif b/docs/images/generateunittestsforfunction.gif
new file mode 100644
index 0000000..ba0a518
--- /dev/null
+++ b/docs/images/generateunittestsforfunction.gif
Binary files differ
diff --git a/docs/images/gotodefinition.gif b/docs/images/gotodefinition.gif
new file mode 100644
index 0000000..048b85f
--- /dev/null
+++ b/docs/images/gotodefinition.gif
Binary files differ
diff --git a/docs/images/implementations.gif b/docs/images/implementations.gif
new file mode 100644
index 0000000..ed4aa60
--- /dev/null
+++ b/docs/images/implementations.gif
Binary files differ
diff --git a/docs/images/installtools.gif b/docs/images/installtools.gif
new file mode 100644
index 0000000..2a6b49a
--- /dev/null
+++ b/docs/images/installtools.gif
Binary files differ
diff --git a/docs/images/outline.png b/docs/images/outline.png
new file mode 100644
index 0000000..feeb0fe
--- /dev/null
+++ b/docs/images/outline.png
Binary files differ
diff --git a/docs/images/peekdefinition.gif b/docs/images/peekdefinition.gif
new file mode 100644
index 0000000..8102247
--- /dev/null
+++ b/docs/images/peekdefinition.gif
Binary files differ
diff --git a/docs/images/rename.gif b/docs/images/rename.gif
new file mode 100644
index 0000000..eddbd0f
--- /dev/null
+++ b/docs/images/rename.gif
Binary files differ
diff --git a/docs/images/snippets-tys.gif b/docs/images/snippets-tys.gif
new file mode 100644
index 0000000..e67b1a9
--- /dev/null
+++ b/docs/images/snippets-tys.gif
Binary files differ
diff --git a/docs/images/toggletestfile.gif b/docs/images/toggletestfile.gif
new file mode 100644
index 0000000..55cbd76
--- /dev/null
+++ b/docs/images/toggletestfile.gif
Binary files differ
diff --git a/docs/images/upgradedeps.png b/docs/images/upgradedeps.png
new file mode 100644
index 0000000..ce12067
--- /dev/null
+++ b/docs/images/upgradedeps.png
Binary files differ
diff --git a/docs/images/workspace-symbols.gif b/docs/images/workspace-symbols.gif
new file mode 100644
index 0000000..18995f9
--- /dev/null
+++ b/docs/images/workspace-symbols.gif
Binary files differ
diff --git a/docs/modules.md b/docs/modules.md
deleted file mode 100644
index 899bb6b..0000000
--- a/docs/modules.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Modules
-
-This extension mostly supports [Go modules]. However, certain features have not been ported to work with modules. The reason for this is that the Go team is developing a language server, [`gopls`](gopls.md). This provides a comprehensive solution for [Go modules] support in all editors.
-
-However, as described in the [language server documentation](gopls.md), `gopls` is still in an alpha state, so it is **not yet** the default in VS Code Go. We understand that many users will not want to use alpha software, so this document describes how this extension works with [Go modules], **without the language server**.
-
-To learn how to use the language server with modules in VS Code, read our [`gopls` documentation](gopls.md).
-
-## Overview
-
-* [Missing features](#missing-features)
- * [Formatting](#formatting)
- * [References and rename](#references-and-rename)
-* [Performance](#performance)
-
-## Missing features
-
-As mentioned above, not all Go tools have been ported to work with modules. **Many tools will never be ported, as they are being replaced by [`gopls`](gopls.md).** [golang/go#24661](https://golang.org/issues/24661) contains up-to-date information about modules support in various Go tools.
-
-### Formatting
-
-The default [formatting](features.md#format-and-organize-imports) tool, [`goreturns`](tools.md#formatting), has not been ported to work with modules. As a result, you will need to change your [`"go.formatTool"`](settings.md#go.formatTool) setting for [formatting and import organization support](features.md#format-and-organize-imports). We recommend changing the value to `"goimports"` instead. Other options are also available, and you can read about them in the [format tools documentation](tools.md#formatting).
-
-### [References](features.md#find-references) and [rename](features.md#rename-symbol)
-
-The tools that provide these two features, [`guru`](tools.md#guru) and [`gorename`](tools.md#gorename), have not been updated for Go modules. Instead, they will be replaced by [`gopls`](gopls.md).
-
-## Performance
-
-[Go modules] introduced additional complexity to Go tooling. As a result, the performance of a number of tools is worse with modules enabled. Hopefully, you will not notice this too frequently.
-
-One case in which you may notice this is autocompletion. The best solution to this is to switch to [`gopls`](gopls.md), which makes use of an in-memory cache to provide results quickly.
-
-[Go modules]: https://blog.golang.org/using-go-modules
diff --git a/docs/nightly.md b/docs/nightly.md
index c18fe59..c6ddde8 100644
--- a/docs/nightly.md
+++ b/docs/nightly.md
@@ -2,7 +2,7 @@
This master branch of this extension is built and published nightly through the [Go Nightly]. If you're interested in testing new features and bug fixes, you may be interested in switching to the [Go Nightly] extension. Also, if you file an issue, we may suggest trying out the fix in [Go Nightly].
-[Go Nightly] is the **preview** version of the Go extension, so it may be broken or unstable at times. The [Changelog](nightly/CHANGELOG.md) and [README](nightly/README.md) for [Go Nightly] can be found in the [docs/nightly](nightly/) directory.
+[Go Nightly] is the **preview** version of the Go extension, so it may be broken or unstable at times.
## Installation
diff --git a/docs/settings.md b/docs/settings.md
index d99bc74..1efe15d 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -28,514 +28,427 @@
### `go.addTags`
Tags and options configured here will be used by the Add Tags command to add tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, json tags are added.
-
| Properties | Description |
| --- | --- |
-| `options` | Comma separated tag=options pairs to be used by Go: Add Tags command |
-| `promptForTags` | If true, Go: Add Tags command will prompt the user to provide tags, options, transform values instead of using the configured values |
-| `tags` | Comma separated tags to be used by Go: Add Tags command |
-| `template` | Custom format used by Go: Add Tags command for the tag value to be applied |
-| `transform` | Transformation rule used by Go: Add Tags command to add tags |
-| | |
+| `options` | Comma separated tag=options pairs to be used by Go: Add Tags command <br/> Default: `"json=omitempty"` |
+| `promptForTags` | If true, Go: Add Tags command will prompt the user to provide tags, options, transform values instead of using the configured values <br/> Default: `false` |
+| `tags` | Comma separated tags to be used by Go: Add Tags command <br/> Default: `"json"` |
+| `template` | Custom format used by Go: Add Tags command for the tag value to be applied <br/> Default: `""` |
+| `transform` | Transformation rule used by Go: Add Tags command to add tags <br/> Allowed Options: `snakecase`, `camelcase`, `lispcase`, `pascalcase`, `keep` <br/> Default: `"snakecase"` |
-
-Default:{<br/>
- `"options": "json=omitempty"`,<br/>
- `"promptForTags": false`,<br/>
- `"tags": "json"`,<br/>
- `"template": ""`,<br/>
- `"transform": "snakecase"`,<br/>
- }
-
-
+Default:
+```
+{
+ "options" : "json=omitempty",
+ "promptForTags" : false,
+ "tags" : "json",
+ "template" : "",
+ "transform" : "snakecase",
+}
+```
### `go.alternateTools`
Alternate tools or alternate paths for the same tools used by the Go extension. Provide either absolute path or the name of the binary in GOPATH/bin, GOROOT/bin or PATH. Useful when you want to use wrapper script for the Go tools or versioned tools from https://gopkg.in. When specified as a workspace setting, the setting is used only when the workspace is marked trusted with "Go: Toggle Workspace Trust Flag".
-
| Properties | Description |
| --- | --- |
-| `go` | Alternate tool to use instead of the go binary or alternate path to use for the go binary. |
-| `go-outline` | Alternate tool to use instead of the go-outline binary or alternate path to use for the go-outline binary. |
-| `gocode` | Alternate tool to use instead of the gocode binary or alternate path to use for the gocode binary. |
-| `gopkgs` | Alternate tool to use instead of the gopkgs binary or alternate path to use for the gopkgs binary. |
-| `gopls` | Alternate tool to use instead of the gopls binary or alternate path to use for the gopls binary. |
-| `guru` | Alternate tool to use instead of the guru binary or alternate path to use for the guru binary. |
-| | |
-
-
-
+| `go` | Alternate tool to use instead of the go binary or alternate path to use for the go binary. <br/> Default: `"go"` |
+| `go-outline` | Alternate tool to use instead of the go-outline binary or alternate path to use for the go-outline binary. <br/> Default: `"go-outline"` |
+| `gocode` | Alternate tool to use instead of the gocode binary or alternate path to use for the gocode binary. <br/> Default: `"gocode"` |
+| `gopkgs` | Alternate tool to use instead of the gopkgs binary or alternate path to use for the gopkgs binary. <br/> Default: `"gopkgs"` |
+| `gopls` | Alternate tool to use instead of the gopls binary or alternate path to use for the gopls binary. <br/> Default: `"gopls"` |
+| `guru` | Alternate tool to use instead of the guru binary or alternate path to use for the guru binary. <br/> Default: `"guru"` |
### `go.autocompleteUnimportedPackages`
Include unimported packages in auto-complete suggestions. Not applicable when using the language server.
Default: `false`
-
### `go.buildFlags`
Flags to `go build`/`go test` used during build-on-save or running tests. (e.g. ["-ldflags='-s'"]) This is propagated to the language server if `gopls.build.buildFlags` is not specified.
-
### `go.buildOnSave`
-Compiles code on file save using 'go build' or 'go test -c'. Options are 'workspace', 'package', or 'off'. Not applicable when using the language server's diagnostics is used. See 'go.languageServerExperimentalFeatures.diagnostics' setting.
+Compiles code on file save using 'go build' or 'go test -c'. Options are 'workspace', 'package', or 'off'. Not applicable when using the language server's diagnostics is used. See 'go.languageServerExperimentalFeatures.diagnostics' setting.<br/>
+Allowed Options: `package`, `workspace`, `off`
-Allowed Values:`[package workspace off]`
-
-Default: `package`
-
+Default: `"package"`
### `go.buildTags`
The Go build tags to use for all commands, that support a `-tags '...'` argument. When running tests, go.testTags will be used instead if it was set. This is propagated to the language server if `gopls.build.buildFlags` is not specified.
-Default: ``
-
+Default: `""`
### `go.coverMode`
-When generating code coverage, the value for -covermode. 'default' is the default value chosen by the 'go test' command.
+When generating code coverage, the value for -covermode. 'default' is the default value chosen by the 'go test' command.<br/>
+Allowed Options: `default`, `set`, `count`, `atomic`
-Allowed Values:`[default set count atomic]`
-
-Default: `default`
-
+Default: `"default"`
### `go.coverOnSave`
If true, runs 'go test -coverprofile' on save and shows test coverage.
Default: `false`
-
### `go.coverOnSingleTest`
If true, shows test coverage when Go: Test Function at cursor command is run.
Default: `false`
-
### `go.coverOnSingleTestFile`
If true, shows test coverage when Go: Test Single File command is run.
Default: `false`
-
### `go.coverOnTestPackage`
If true, shows test coverage when Go: Test Package command is run.
Default: `true`
-
### `go.coverShowCounts`
When generating code coverage, should counts be shown as --374--
Default: `false`
-
### `go.coverageDecorator`
This option lets you choose the way to display code coverage. Choose either to highlight the complete line or to show a decorator in the gutter. You can customize the colors and borders for the former and the style for the latter.
-
| Properties | Description |
| --- | --- |
| `coveredBorderColor` | Color to use for the border of covered code. |
-| `coveredGutterStyle` | Gutter style to indicate covered code. |
+| `coveredGutterStyle` | Gutter style to indicate covered code. <br/> Allowed Options: `blockblue`, `blockred`, `blockgreen`, `blockyellow`, `slashred`, `slashgreen`, `slashblue`, `slashyellow`, `verticalred`, `verticalgreen`, `verticalblue`, `verticalyellow` |
| `coveredHighlightColor` | Color in the rgba format to use to highlight covered code. |
-| `type` | |
+| `type` | <br/> <br/> Allowed Options: `highlight`, `gutter` |
| `uncoveredBorderColor` | Color to use for the border of uncovered code. |
-| `uncoveredGutterStyle` | Gutter style to indicate covered code. |
+| `uncoveredGutterStyle` | Gutter style to indicate covered code. <br/> Allowed Options: `blockblue`, `blockred`, `blockgreen`, `blockyellow`, `slashred`, `slashgreen`, `slashblue`, `slashyellow`, `verticalred`, `verticalgreen`, `verticalblue`, `verticalyellow` |
| `uncoveredHighlightColor` | Color in the rgba format to use to highlight uncovered code. |
-| | |
-
-Default:{<br/>
- `"coveredBorderColor": "rgba(64,128,128,0.5)"`,<br/>
- `"coveredGutterStyle": "blockblue"`,<br/>
- `"coveredHighlightColor": "rgba(64,128,128,0.5)"`,<br/>
- `"type": "highlight"`,<br/>
- `"uncoveredBorderColor": "rgba(128,64,64,0.25)"`,<br/>
- `"uncoveredGutterStyle": "slashyellow"`,<br/>
- `"uncoveredHighlightColor": "rgba(128,64,64,0.25)"`,<br/>
- }
-
-
+Default:
+```
+{
+ "coveredBorderColor" : "rgba(64,128,128,0.5)",
+ "coveredGutterStyle" : "blockblue",
+ "coveredHighlightColor" : "rgba(64,128,128,0.5)",
+ "type" : "highlight",
+ "uncoveredBorderColor" : "rgba(128,64,64,0.25)",
+ "uncoveredGutterStyle" : "slashyellow",
+ "uncoveredHighlightColor" : "rgba(128,64,64,0.25)",
+}
+```
### `go.coverageOptions`
-Use these options to control whether only covered or only uncovered code or both should be highlighted after running test coverage
+Use these options to control whether only covered or only uncovered code or both should be highlighted after running test coverage<br/>
+Allowed Options: `showCoveredCodeOnly`, `showUncoveredCodeOnly`, `showBothCoveredAndUncoveredCode`
-Allowed Values:`[showCoveredCodeOnly showUncoveredCodeOnly showBothCoveredAndUncoveredCode]`
-
-Default: `showBothCoveredAndUncoveredCode`
-
+Default: `"showBothCoveredAndUncoveredCode"`
### `go.delveConfig`
Delve settings that applies to all debugging sessions. Debug configuration in the launch.json file will override these values.
-
| Properties | Description |
| --- | --- |
-| `apiVersion` | Delve Api Version to use. Default value is 2. |
-| `dlvLoadConfig` | LoadConfig describes to delve, how to load values from target's memory |
-| `showGlobalVariables` | Boolean value to indicate whether global package variables should be shown in the variables pane or not. |
-| | |
+| `apiVersion` | Delve Api Version to use. Default value is 2. <br/> Allowed Options: `1`, `2` <br/> Default: `2` |
+| `dlvLoadConfig` | LoadConfig describes to delve, how to load values from target's memory <br/> Default: ``` { <pre>"followPointers" : true,<br/>"maxArrayValues" : 64,<br/>"maxStringLen" : 64,<br/>"maxStructFields" : -1,<br/>"maxVariableRecurse" : 1,</pre>} ``` |
+| `showGlobalVariables` | Boolean value to indicate whether global package variables should be shown in the variables pane or not. <br/> Default: `false` |
-
-Default:{<br/>
- `"apiVersion": 2`,<br/>
- `"dlvLoadConfig": map[followPointers:true maxArrayValues:64 maxStringLen:64 maxStructFields:-1 maxVariableRecurse:1]`,<br/>
- `"showGlobalVariables": false`,<br/>
- }
-
-
+Default:
+```
+{
+ "apiVersion" : 2,
+ "dlvLoadConfig" : {
+ "followPointers" : true,
+ "maxArrayValues" : 64,
+ "maxStringLen" : 64,
+ "maxStructFields" : -1,
+ "maxVariableRecurse" : 1,
+ },
+ "showGlobalVariables" : false,
+}
+```
### `go.docsTool`
-Pick 'godoc' or 'gogetdoc' to get documentation. Not applicable when using the language server.
+Pick 'godoc' or 'gogetdoc' to get documentation. Not applicable when using the language server.<br/>
+Allowed Options: `godoc`, `gogetdoc`, `guru`
-Allowed Values:`[godoc gogetdoc guru]`
-
-Default: `godoc`
-
+Default: `"godoc"`
### `go.editorContextMenuCommands`
Experimental Feature: Enable/Disable entries from the context menu in the editor.
-
| Properties | Description |
| --- | --- |
-| `addImport` | If true, adds command to import a package to the editor context menu |
-| `addTags` | If true, adds command to add configured tags from struct fields to the editor context menu |
-| `benchmarkAtCursor` | If true, adds command to benchmark the test under the cursor to the editor context menu |
-| `debugTestAtCursor` | If true, adds command to debug the test under the cursor to the editor context menu |
-| `fillStruct` | If true, adds command to fill struct literal with default values to the editor context menu |
-| `generateTestForFile` | If true, adds command to generate unit tests for current file to the editor context menu |
-| `generateTestForFunction` | If true, adds command to generate unit tests for function under the cursor to the editor context menu |
-| `generateTestForPackage` | If true, adds command to generate unit tests for currnt package to the editor context menu |
-| `playground` | If true, adds command to upload the current file or selection to the Go Playground |
-| `removeTags` | If true, adds command to remove configured tags from struct fields to the editor context menu |
-| `testAtCursor` | If true, adds command to run the test under the cursor to the editor context menu |
-| `testCoverage` | If true, adds command to run test coverage to the editor context menu |
-| `testFile` | If true, adds command to run all tests in the current file to the editor context menu |
-| `testPackage` | If true, adds command to run all tests in the current package to the editor context menu |
-| `toggleTestFile` | If true, adds command to toggle between a Go file and its test file to the editor context menu |
-| | |
+| `addImport` | If true, adds command to import a package to the editor context menu <br/> Default: `true` |
+| `addTags` | If true, adds command to add configured tags from struct fields to the editor context menu <br/> Default: `true` |
+| `benchmarkAtCursor` | If true, adds command to benchmark the test under the cursor to the editor context menu <br/> Default: `true` |
+| `debugTestAtCursor` | If true, adds command to debug the test under the cursor to the editor context menu <br/> Default: `true` |
+| `fillStruct` | If true, adds command to fill struct literal with default values to the editor context menu <br/> Default: `true` |
+| `generateTestForFile` | If true, adds command to generate unit tests for current file to the editor context menu <br/> Default: `true` |
+| `generateTestForFunction` | If true, adds command to generate unit tests for function under the cursor to the editor context menu <br/> Default: `true` |
+| `generateTestForPackage` | If true, adds command to generate unit tests for currnt package to the editor context menu <br/> Default: `true` |
+| `playground` | If true, adds command to upload the current file or selection to the Go Playground <br/> Default: `true` |
+| `removeTags` | If true, adds command to remove configured tags from struct fields to the editor context menu <br/> Default: `true` |
+| `testAtCursor` | If true, adds command to run the test under the cursor to the editor context menu <br/> Default: `true` |
+| `testCoverage` | If true, adds command to run test coverage to the editor context menu <br/> Default: `true` |
+| `testFile` | If true, adds command to run all tests in the current file to the editor context menu <br/> Default: `true` |
+| `testPackage` | If true, adds command to run all tests in the current package to the editor context menu <br/> Default: `true` |
+| `toggleTestFile` | If true, adds command to toggle between a Go file and its test file to the editor context menu <br/> Default: `true` |
-
-Default:{<br/>
- `"addImport": true`,<br/>
- `"addTags": true`,<br/>
- `"benchmarkAtCursor": false`,<br/>
- `"debugTestAtCursor": true`,<br/>
- `"fillStruct": false`,<br/>
- `"generateTestForFile": false`,<br/>
- `"generateTestForFunction": true`,<br/>
- `"generateTestForPackage": false`,<br/>
- `"playground": true`,<br/>
- `"removeTags": false`,<br/>
- `"testAtCursor": true`,<br/>
- `"testCoverage": true`,<br/>
- `"testFile": false`,<br/>
- `"testPackage": false`,<br/>
- `"toggleTestFile": true`,<br/>
- }
-
-
+Default:
+```
+{
+ "addImport" : true,
+ "addTags" : true,
+ "benchmarkAtCursor" : false,
+ "debugTestAtCursor" : true,
+ "fillStruct" : false,
+ "generateTestForFile" : false,
+ "generateTestForFunction" : true,
+ "generateTestForPackage" : false,
+ "playground" : true,
+ "removeTags" : false,
+ "testAtCursor" : true,
+ "testCoverage" : true,
+ "testFile" : false,
+ "testPackage" : false,
+ "toggleTestFile" : true,
+}
+```
### `go.enableCodeLens`
Feature level setting to enable/disable code lens for references and run/debug tests
-
| Properties | Description |
| --- | --- |
-| `references` | If true, enables the references code lens. Uses guru. Recalculates when there is change to the document followed by scrolling. Unnecessary when using the language server; use the call graph feature instead. |
-| `runtest` | If true, enables code lens for running and debugging tests |
-| | |
+| `references` | If true, enables the references code lens. Uses guru. Recalculates when there is change to the document followed by scrolling. Unnecessary when using the language server; use the call graph feature instead. <br/> Default: `false` |
+| `runtest` | If true, enables code lens for running and debugging tests <br/> Default: `true` |
-
-Default:{<br/>
- `"references": false`,<br/>
- `"runtest": true`,<br/>
- }
-
-
+Default:
+```
+{
+ "references" : false,
+ "runtest" : true,
+}
+```
### `go.formatFlags`
Flags to pass to format tool (e.g. ["-s"]). Not applicable when using the language server.
-
### `go.formatTool`
-Not applicable when using the language server. Choosing 'goimports', 'goreturns', or 'gofumports' will add missing imports and remove unused imports.
+Not applicable when using the language server. Choosing 'goimports', 'goreturns', or 'gofumports' will add missing imports and remove unused imports.<br/>
+Allowed Options: `gofmt`, `goimports`, `goreturns`, `goformat`, `gofumpt`, `gofumports`
-Allowed Values:`[gofmt goimports goreturns goformat gofumpt gofumports]`
-
-Default: `goreturns`
-
+Default: `"goreturns"`
### `go.generateTestsFlags`
Additional command line flags to pass to `gotests` for generating tests.
-
### `go.gocodeAutoBuild`
Enable gocode's autobuild feature. Not applicable when using the language server.
Default: `false`
-
### `go.gocodeFlags`
Additional flags to pass to gocode. Not applicable when using the language server.
Default: `[-builtin -ignore-case -unimported-packages]`
-
### `go.gocodePackageLookupMode`
-Used to determine the Go package lookup rules for completions by gocode. Only applies when using nsf/gocode. Latest versions of the Go extension uses mdempsky/gocode by default. Not applicable when using the language server.
+Used to determine the Go package lookup rules for completions by gocode. Only applies when using nsf/gocode. Latest versions of the Go extension uses mdempsky/gocode by default. Not applicable when using the language server.<br/>
+Allowed Options: `go`, `gb`, `bzl`
-Allowed Values:`[go gb bzl]`
-
-Default: `go`
-
+Default: `"go"`
### `go.gopath`
Specify GOPATH here to override the one that is set as environment variable. The inferred GOPATH from workspace root overrides this, if go.inferGopath is set to true. When specified as a workspace setting, the setting is used only when the workspace is marked trusted with "Go: Toggle Workspace Trust Flag".
-
-efault: `<nil>`
-
### `go.goroot`
Specifies the GOROOT to use when no environment variable is set. When specified as a workspace setting, the setting is used only when the workspace is marked trusted with "Go: Toggle Workspace Trust Flag".
-
-efault: `<nil>`
-
### `go.gotoSymbol.ignoreFolders`
Folder names (not paths) to ignore while using Go to Symbol in Workspace feature. Not applicable when using the language server.
-
### `go.gotoSymbol.includeGoroot`
If false, the standard library located at $GOROOT will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.
Default: `false`
-
### `go.gotoSymbol.includeImports`
If false, the import statements will be excluded while using the Go to Symbol in File feature. Not applicable when using the language server.
Default: `false`
-
### `go.inferGopath`
Infer GOPATH from the workspace root. This is ignored when using Go Modules. When specified as a workspace setting, the setting is used only when the workspace is marked trusted with "Go: Toggle Workspace Trust Flag".
Default: `false`
-
### `go.installDependenciesWhenBuilding`
If true, then `-i` flag will be passed to `go build` everytime the code is compiled. Since Go 1.10, setting this may be unnecessary unless you are in GOPATH mode and do not use the language server.
Default: `false`
-
### `go.languageServerExperimentalFeatures`
Temporary flag to enable/disable diagnostics from the language server. This setting will be deprecated soon. Please see and response to [Issue 50](https://github.com/golang/vscode-go/issues/50).
-
| Properties | Description |
| --- | --- |
-| `diagnostics` | If true, the language server will provide build, vet errors and the extension will ignore the `buildOnSave`, `vetOnSave` settings. |
-| | |
+| `diagnostics` | If true, the language server will provide build, vet errors and the extension will ignore the `buildOnSave`, `vetOnSave` settings. <br/> Default: `true` |
-
-Default:{<br/>
- `"diagnostics": true`,<br/>
- }
-
-
+Default:
+```
+{
+ "diagnostics" : true,
+}
+```
### `go.languageServerFlags`
Flags like -rpc.trace and -logfile to be used while running the language server.
-
### `go.lintFlags`
Flags to pass to Lint tool (e.g. ["-min_confidence=.8"])
-
### `go.lintOnSave`
-Lints code on file save using the configured Lint tool. Options are 'file', 'package', 'workspace' or 'off'.
+Lints code on file save using the configured Lint tool. Options are 'file', 'package', 'workspace' or 'off'.<br/>
+Allowed Options: `file`, `package`, `workspace`, `off`
-Allowed Values:`[file package workspace off]`
-
-Default: `package`
-
+Default: `"package"`
### `go.lintTool`
-Specifies Lint tool name.
+Specifies Lint tool name.<br/>
+Allowed Options: `golint`, `golangci-lint`, `revive`, `staticcheck`
-Allowed Values:`[golint golangci-lint revive staticcheck]`
-
-Default: `golint`
-
+Default: `"golint"`
### `go.liveErrors`
Use gotype on the file currently being edited and report any semantic or syntactic errors found after configured delay. Not applicable when using the language server.
-
| Properties | Description |
| --- | --- |
-| `delay` | The number of milliseconds to delay before execution. Resets with each keystroke. |
-| `enabled` | If true, runs gotype on the file currently being edited and reports any semantic or syntactic errors found. Disabled when the language server is enabled. |
-| | |
+| `delay` | The number of milliseconds to delay before execution. Resets with each keystroke. <br/> Default: `500` |
+| `enabled` | If true, runs gotype on the file currently being edited and reports any semantic or syntactic errors found. Disabled when the language server is enabled. <br/> Default: `false` |
-
-Default:{<br/>
- `"delay": 500`,<br/>
- `"enabled": false`,<br/>
- }
-
-
+Default:
+```
+{
+ "delay" : 500,
+ "enabled" : false,
+}
+```
### `go.logging.level`
-The logging level the extension logs at, defaults to 'error'
+The logging level the extension logs at, defaults to 'error'<br/>
+Allowed Options: `off`, `error`, `info`, `verbose`
-Allowed Values:`[off error info verbose]`
-
-Default: `error`
-
+Default: `"error"`
### `go.overwriteGoplsMiddleware (deprecated)`
This option is deprecated.
This option provides a set of flags which determine if vscode-go should intercept certain commands from gopls. These flags assume the `gopls` settings, which enable codelens from gopls, are also present.
-
| Properties | Description |
| --- | --- |
| `codelens` | |
| `default` | |
-| | |
-
-
-
### `go.playground`
The flags configured here will be passed through to command `goplay`
-
| Properties | Description |
| --- | --- |
-| `openbrowser` | Whether to open the created Go Playground in the default browser |
-| `run` | Whether to run the created Go Playground after creation |
-| `share` | Whether to make the created Go Playground shareable |
-| | |
+| `openbrowser` | Whether to open the created Go Playground in the default browser <br/> Default: `true` |
+| `run` | Whether to run the created Go Playground after creation <br/> Default: `true` |
+| `share` | Whether to make the created Go Playground shareable <br/> Default: `true` |
-
-Default:{<br/>
- `"openbrowser": true`,<br/>
- `"run": true`,<br/>
- `"share": true`,<br/>
- }
-
-
+Default:
+```
+{
+ "openbrowser" : true,
+ "run" : true,
+ "share" : true,
+}
+```
### `go.removeTags`
Tags and options configured here will be used by the Remove Tags command to remove tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, all tags and options will be removed.
-
| Properties | Description |
| --- | --- |
-| `options` | Comma separated tag=options pairs to be used by Go: Remove Tags command |
-| `promptForTags` | If true, Go: Remove Tags command will prompt the user to provide tags and options instead of using the configured values |
-| `tags` | Comma separated tags to be used by Go: Remove Tags command |
-| | |
+| `options` | Comma separated tag=options pairs to be used by Go: Remove Tags command <br/> Default: `"json=omitempty"` |
+| `promptForTags` | If true, Go: Remove Tags command will prompt the user to provide tags and options instead of using the configured values <br/> Default: `false` |
+| `tags` | Comma separated tags to be used by Go: Remove Tags command <br/> Default: `"json"` |
-
-Default:{<br/>
- `"options": ""`,<br/>
- `"promptForTags": false`,<br/>
- `"tags": ""`,<br/>
- }
-
-
+Default:
+```
+{
+ "options" : "",
+ "promptForTags" : false,
+ "tags" : "",
+}
+```
### `go.testEnvFile`
Absolute path to a file containing environment variables definitions. File contents should be of the form key=value.
-
-Default: `<nil>`
-
### `go.testEnvVars`
Environment variables that will be passed to the process that runs the Go tests
-
### `go.testFlags`
Flags to pass to `go test`. If null, then buildFlags will be used. This is not propagated to the language server.
-
-efault: `<nil>`
-
### `go.testOnSave`
Run 'go test' on save for current package. It is not advised to set this to `true` when you have Auto Save enabled.
Default: `false`
-
### `go.testTags`
The Go build tags to use for when running tests. If null, then buildTags will be used.
-
-efault: `<nil>`
-
### `go.testTimeout`
Specifies the timeout for go test in ParseDuration format.
-Default: `30s`
-
+Default: `"30s"`
### `go.toolsEnvVars`
Environment variables that will be passed to the tools that run the Go tools (e.g. CGO_CFLAGS)
-
### `go.toolsGopath`
Location to install the Go tools that the extension depends on if you don't want them in your GOPATH. When specified as a workspace setting, the setting is used only when the workspace is marked trusted with "Go: Toggle Workspace Trust Flag".
-
-efault: `<nil>`
-
### `go.toolsManagement.checkForUpdates`
-Specify whether to prompt about new versions of Go and the Go tools (currently, only `gopls`) the extension depends on
+Specify whether to prompt about new versions of Go and the Go tools (currently, only `gopls`) the extension depends on<br/>
+Allowed Options:
-Allowed Values:`[proxy local off]`
+* `proxy`: keeps notified of new releases by checking the Go module proxy (GOPROXY)
+* `local`: checks only the minimum tools versions required by the extension
+* `off`: completely disables version check (not recommended)
-Default: `proxy`
+Default: `"proxy"`
### `go.trace.server`
-Trace the communication between VS Code and the Go language server.
+Trace the communication between VS Code and the Go language server.<br/>
+Allowed Options: `off`, `messages`, `verbose`
-Allowed Values:`[off messages verbose]`
-
-Default: `off`
-
+Default: `"off"`
### `go.useCodeSnippetsOnFunctionSuggest`
Complete functions with their parameter signature, including the variable type. Not propagated to the language server.
Default: `false`
-
### `go.useCodeSnippetsOnFunctionSuggestWithoutType`
Complete functions with their parameter signature, excluding the variable types. Use `gopls.usePlaceholders` when using the language server.
Default: `false`
-
### `go.useGoProxyToCheckForToolUpdates (deprecated)`
Use `go.toolsManagement.checkForUpdates` instead.
When enabled, the extension automatically checks the Go proxy if there are updates available for Go and the Go tools (at present, only gopls) it depends on and prompts the user accordingly
Default: `true`
-
### `go.useLanguageServer`
Use the Go language server "gopls" from Google for powering language features like code navigation, completion, refactoring, formatting & diagnostics.
-Default: `false`
-
+Default: `true`
### `go.vetFlags`
Flags to pass to `go tool vet` (e.g. ["-all", "-shadow"])
-
### `go.vetOnSave`
-Vets code on file save using 'go tool vet'. Not applicable when using the language server's diagnostics is used. See 'go.languageServerExperimentalFeatures.diagnostics' setting.
+Vets code on file save using 'go tool vet'. Not applicable when using the language server's diagnostics is used. See 'go.languageServerExperimentalFeatures.diagnostics' setting.<br/>
+Allowed Options: `package`, `workspace`, `off`
-Allowed Values:`[package workspace off]`
-
-Default: `package`
-
+Default: `"package"`
### `gopls`
Customize `gopls` behavior by specifying the gopls' settings in this section. For example,
@@ -552,17 +465,22 @@
Configure the default Go language server ('gopls'). In most cases, configuring this section is unnecessary. See [the documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md) for all available settings.
### `build.allowImplicitNetworkAccess`
+
(Experimental) allowImplicitNetworkAccess disables GOPROXY=off, allowing implicit module
downloads rather than requiring user action. This option will eventually
be removed.
+
Default: `false`
### `build.allowModfileModifications`
+
(Experimental) allowModfileModifications disables -mod=readonly, allowing imports from
out-of-scope modules. This option will eventually be removed.
+
Default: `false`
### `build.buildFlags`
+
buildFlags is the set of flags passed on to the build system when invoked.
It is applied to queries like `go list`, which is used when discovering files.
The most common use is to set `-tags`.
@@ -570,6 +488,7 @@
If unspecified, values of `go.buildFlags, go.buildTags` will be propagated.
### `build.directoryFilters`
+
directoryFilters can be used to exclude unwanted directories from the
workspace. By default, all directories are included. Filters are an
operator, `+` to include and `-` to exclude, followed by a path prefix
@@ -583,9 +502,11 @@
Include only project_a, but not node_modules inside it: `-`, `+project_a`, `-project_a/node_modules`
### `build.env`
+
env adds environment variables to external commands run by `gopls`, most notably `go list`.
### `build.expandWorkspaceToModule`
+
(Experimental) expandWorkspaceToModule instructs `gopls` to adjust the scope of the
workspace to find the best available module root. `gopls` first looks for
a go.mod file in any parent directory of the workspace folder, expanding
@@ -593,8 +514,10 @@
found, gopls will check if there is exactly one child directory containing
a go.mod file, narrowing the scope to that directory if it exists.
+
Default: `true`
### `build.experimentalPackageCacheKey`
+
(Experimental) experimentalPackageCacheKey controls whether to use a coarser cache key
for package type information to increase cache hits. This setting removes
the user's environment, build flags, and working directory from the cache
@@ -603,24 +526,32 @@
by an experiment because caching behavior is subtle and difficult to
comprehensively test.
+
Default: `true`
### `build.experimentalWorkspaceModule`
+
(Experimental) experimentalWorkspaceModule opts a user into the experimental support
for multi-module workspaces.
+
Default: `false`
### `formatting.gofumpt`
+
gofumpt indicates if we should run gofumpt formatting.
+
Default: `false`
### `formatting.local`
+
local is the equivalent of the `goimports -local` flag, which puts
imports beginning with this string after third-party packages. It should
be the prefix of the import path whose imports should be grouped
separately.
-Default: ``
+
+Default: `""`
### `ui.codelenses`
+
codelenses overrides the enabled/disabled state of code lenses. See the
"Code Lenses" section of the
[Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md)
@@ -639,25 +570,42 @@
}
```
+| Properties | Description |
+| --- | --- |
+| `gc_details` | gc_details controls calculation of gc annotations. <br/> <br/> Default: `false` |
+| `generate` | generate runs `go generate` for a given directory. <br/> <br/> Default: `true` |
+| `regenerate_cgo` | regenerate_cgo regenerates cgo definitions. <br/> <br/> Default: `true` |
+| `test` | test runs `go test` for a specific test function. <br/> <br/> Default: `false` |
+| `tidy` | tidy runs `go mod tidy` for a module. <br/> <br/> Default: `true` |
+| `upgrade_dependency` | upgrade_dependency upgrades a dependency. <br/> <br/> Default: `true` |
+| `vendor` | vendor runs `go mod vendor` for a module. <br/> <br/> Default: `true` |
### `ui.completion.completionBudget`
+
(For Debugging) completionBudget is the soft latency goal for completion requests. Most
requests finish in a couple milliseconds, but in some cases deep
completions can take much longer. As we use up our budget we
dynamically reduce the search scope to ensure we return timely
results. Zero means unlimited.
-Default: `100ms`
+
+Default: `"100ms"`
### `ui.completion.matcher`
+
(Advanced) matcher sets the algorithm that is used when calculating completion
candidates.
+<br/>
+Allowed Options: `CaseInsensitive`, `CaseSensitive`, `Fuzzy`
-Default: `Fuzzy`
+Default: `"Fuzzy"`
### `ui.completion.usePlaceholders`
+
placeholders enables placeholders for function parameters or struct
fields in completion responses.
+
Default: `false`
### `ui.diagnostic.analyses`
+
analyses specify analyses that the user would like to enable or disable.
A map of the names of analysis passes that should be enabled/disabled.
A full list of analyzers that gopls uses can be found
@@ -674,11 +622,60 @@
...
```
+| Properties | Description |
+| --- | --- |
+| `asmdecl` | report mismatches between assembly files and Go declarations <br/> Default: `true` |
+| `assign` | check for useless assignments <br/> This checker reports assignments of the form x = x or a[i] = a[i]. These are almost always useless, and even when they aren't they are usually a mistake. <br/> Default: `true` |
+| `atomic` | check for common mistakes using the sync/atomic package <br/> The atomic checker looks for assignment statements of the form: <br/> <pre>x = atomic.AddUint64(&x, 1)</pre><br/> which are not atomic. <br/> Default: `true` |
+| `atomicalign` | check for non-64-bits-aligned arguments to sync/atomic functions <br/> Default: `true` |
+| `bools` | check for common mistakes involving boolean operators <br/> Default: `true` |
+| `buildtag` | check that +build tags are well-formed and correctly located <br/> Default: `true` |
+| `cgocall` | detect some violations of the cgo pointer passing rules <br/> Check for invalid cgo pointer passing. This looks for code that uses cgo to call C code passing values whose types are almost always invalid according to the cgo pointer sharing rules. Specifically, it warns about attempts to pass a Go chan, map, func, or slice to C, either directly, or via a pointer, array, or struct. <br/> Default: `true` |
+| `composites` | check for unkeyed composite literals <br/> This analyzer reports a diagnostic for composite literals of struct types imported from another package that do not use the field-keyed syntax. Such literals are fragile because the addition of a new field (even if unexported) to the struct will cause compilation to fail. <br/> As an example, <br/> <pre>err = &net.DNSConfigError{err}</pre><br/> should be replaced by: <br/> <pre>err = &net.DNSConfigError{Err: err}</pre><br/> <br/> Default: `true` |
+| `copylocks` | check for locks erroneously passed by value <br/> Inadvertently copying a value containing a lock, such as sync.Mutex or sync.WaitGroup, may cause both copies to malfunction. Generally such values should be referred to through a pointer. <br/> Default: `true` |
+| `deepequalerrors` | check for calls of reflect.DeepEqual on error values <br/> The deepequalerrors checker looks for calls of the form: <br/> reflect.DeepEqual(err1, err2) <br/> where err1 and err2 are errors. Using reflect.DeepEqual to compare errors is discouraged. <br/> Default: `true` |
+| `errorsas` | report passing non-pointer or non-error values to errors.As <br/> The errorsas analysis reports calls to errors.As where the type of the second argument is not a pointer to a type implementing error. <br/> Default: `true` |
+| `fieldalignment` | find structs that would take less memory if their fields were sorted <br/> This analyzer find structs that can be rearranged to take less memory, and provides a suggested edit with the optimal order. <br/> <br/> Default: `false` |
+| `fillreturns` | suggested fixes for "wrong number of return values (want %d, got %d)" <br/> This checker provides suggested fixes for type errors of the type "wrong number of return values (want %d, got %d)". For example: <pre>func m() (int, string, *bool, error) {<br/> return<br/>}</pre>will turn into <pre>func m() (int, string, *bool, error) {<br/> return 0, "", nil, nil<br/>}</pre><br/> This functionality is similar to https://github.com/sqs/goreturns. <br/> <br/> Default: `true` |
+| `fillstruct` | note incomplete struct initializations <br/> This analyzer provides diagnostics for any struct literals that do not have any fields initialized. Because the suggested fix for this analysis is expensive to compute, callers should compute it separately, using the SuggestedFix function below. <br/> <br/> Default: `true` |
+| `httpresponse` | check for mistakes using HTTP responses <br/> A common mistake when using the net/http package is to defer a function call to close the http.Response Body before checking the error that determines whether the response is valid: <br/> <pre>resp, err := http.Head(url)<br/>defer resp.Body.Close()<br/>if err != nil {<br/> log.Fatal(err)<br/>}<br/>// (defer statement belongs here)</pre><br/> This checker helps uncover latent nil dereference bugs by reporting a diagnostic for such mistakes. <br/> Default: `true` |
+| `ifaceassert` | detect impossible interface-to-interface type assertions <br/> This checker flags type assertions v.(T) and corresponding type-switch cases in which the static type V of v is an interface that cannot possibly implement the target interface T. This occurs when V and T contain methods with the same name but different signatures. Example: <br/> <pre>var v interface {<br/> Read()<br/>}<br/>_ = v.(io.Reader)</pre><br/> The Read method in v has a different signature than the Read method in io.Reader, so this assertion cannot succeed. <br/> <br/> Default: `true` |
+| `loopclosure` | check references to loop variables from within nested functions <br/> This analyzer checks for references to loop variables from within a function literal inside the loop body. It checks only instances where the function literal is called in a defer or go statement that is the last statement in the loop body, as otherwise we would need whole program analysis. <br/> For example: <br/> <pre>for i, v := range s {<br/> go func() {<br/> println(i, v) // not what you might expect<br/> }()<br/>}</pre><br/> See: https://golang.org/doc/go_faq.html#closures_and_goroutines <br/> Default: `true` |
+| `lostcancel` | check cancel func returned by context.WithCancel is called <br/> The cancellation function returned by context.WithCancel, WithTimeout, and WithDeadline must be called or the new context will remain live until its parent context is cancelled. (The background context is never cancelled.) <br/> Default: `true` |
+| `nilfunc` | check for useless comparisons between functions and nil <br/> A useless comparison is one like f == nil as opposed to f() == nil. <br/> Default: `true` |
+| `nonewvars` | suggested fixes for "no new vars on left side of :=" <br/> This checker provides suggested fixes for type errors of the type "no new vars on left side of :=". For example: <pre>z := 1<br/>z := 2</pre>will turn into <pre>z := 1<br/>z = 2</pre><br/> <br/> Default: `true` |
+| `noresultvalues` | suggested fixes for "no result values expected" <br/> This checker provides suggested fixes for type errors of the type "no result values expected". For example: <pre>func z() { return nil }</pre>will turn into <pre>func z() { return }</pre><br/> <br/> Default: `true` |
+| `printf` | check consistency of Printf format strings and arguments <br/> The check applies to known functions (for example, those in package fmt) as well as any detected wrappers of known functions. <br/> A function that wants to avail itself of printf checking but is not found by this analyzer's heuristics (for example, due to use of dynamic calls) can insert a bogus call: <br/> <pre>if false {<br/> _ = fmt.Sprintf(format, args...) // enable printf checking<br/>}</pre><br/> The -funcs flag specifies a comma-separated list of names of additional known formatting functions or methods. If the name contains a period, it must denote a specific function using one of the following forms: <br/> <pre>dir/pkg.Function<br/>dir/pkg.Type.Method<br/>(*dir/pkg.Type).Method</pre><br/> Otherwise the name is interpreted as a case-insensitive unqualified identifier such as "errorf". Either way, if a listed name ends in f, the function is assumed to be Printf-like, taking a format string before the argument list. Otherwise it is assumed to be Print-like, taking a list of arguments with no format string. <br/> <br/> Default: `true` |
+| `shadow` | check for possible unintended shadowing of variables <br/> This analyzer check for shadowed variables. A shadowed variable is a variable declared in an inner scope with the same name and type as a variable in an outer scope, and where the outer variable is mentioned after the inner one is declared. <br/> (This definition can be refined; the module generates too many false positives and is not yet enabled by default.) <br/> For example: <br/> <pre>func BadRead(f *os.File, buf []byte) error {<br/> var err error<br/> for {<br/> n, err := f.Read(buf) // shadows the function variable 'err'<br/> if err != nil {<br/> break // causes return of wrong value<br/> }<br/> foo(buf)<br/> }<br/> return err<br/>}</pre><br/> <br/> Default: `false` |
+| `shift` | check for shifts that equal or exceed the width of the integer <br/> Default: `true` |
+| `simplifycompositelit` | check for composite literal simplifications <br/> An array, slice, or map composite literal of the form: <pre>[]T{T{}, T{}}</pre>will be simplified to: <pre>[]T{{}, {}}</pre><br/> This is one of the simplifications that "gofmt -s" applies. <br/> Default: `true` |
+| `simplifyrange` | check for range statement simplifications <br/> A range of the form: <pre>for x, _ = range v {...}</pre>will be simplified to: <pre>for x = range v {...}</pre><br/> A range of the form: <pre>for _ = range v {...}</pre>will be simplified to: <pre>for range v {...}</pre><br/> This is one of the simplifications that "gofmt -s" applies. <br/> Default: `true` |
+| `simplifyslice` | check for slice simplifications <br/> A slice expression of the form: <pre>s[a:len(s)]</pre>will be simplified to: <pre>s[a:]</pre><br/> This is one of the simplifications that "gofmt -s" applies. <br/> Default: `true` |
+| `sortslice` | check the argument type of sort.Slice <br/> sort.Slice requires an argument of a slice type. Check that the interface{} value passed to sort.Slice is actually a slice. <br/> Default: `true` |
+| `stdmethods` | check signature of methods of well-known interfaces <br/> Sometimes a type may be intended to satisfy an interface but may fail to do so because of a mistake in its method signature. For example, the result of this WriteTo method should be (int64, error), not error, to satisfy io.WriterTo: <br/> <pre>type myWriterTo struct{...}</pre> func (myWriterTo) WriteTo(w io.Writer) error { ... } <br/> This check ensures that each method whose name matches one of several well-known interface methods from the standard library has the correct signature for that interface. <br/> Checked method names include: <pre>Format GobEncode GobDecode MarshalJSON MarshalXML<br/>Peek ReadByte ReadFrom ReadRune Scan Seek<br/>UnmarshalJSON UnreadByte UnreadRune WriteByte<br/>WriteTo</pre><br/> <br/> Default: `true` |
+| `stringintconv` | check for string(int) conversions <br/> This checker flags conversions of the form string(x) where x is an integer (but not byte or rune) type. Such conversions are discouraged because they return the UTF-8 representation of the Unicode code point x, and not a decimal string representation of x as one might expect. Furthermore, if x denotes an invalid code point, the conversion cannot be statically rejected. <br/> For conversions that intend on using the code point, consider replacing them with string(rune(x)). Otherwise, strconv.Itoa and its equivalents return the string representation of the value in the desired base. <br/> <br/> Default: `true` |
+| `structtag` | check that struct field tags conform to reflect.StructTag.Get <br/> Also report certain struct tags (json, xml) used with unexported fields. <br/> Default: `true` |
+| `testinggoroutine` | report calls to (*testing.T).Fatal from goroutines started by a test. <br/> Functions that abruptly terminate a test, such as the Fatal, Fatalf, FailNow, and Skip{,f,Now} methods of *testing.T, must be called from the test goroutine itself. This checker detects calls to these functions that occur within a goroutine started by the test. For example: <br/> func TestFoo(t *testing.T) { go func() { t.Fatal("oops") // error: (*T).Fatal called from non-test goroutine }() } <br/> <br/> Default: `true` |
+| `tests` | check for common mistaken usages of tests and examples <br/> The tests checker walks Test, Benchmark and Example functions checking malformed names, wrong signatures and examples documenting non-existent identifiers. <br/> Please see the documentation for package testing in golang.org/pkg/testing for the conventions that are enforced for Tests, Benchmarks, and Examples. <br/> Default: `true` |
+| `undeclaredname` | suggested fixes for "undeclared name: <>" <br/> This checker provides suggested fixes for type errors of the type "undeclared name: <>". It will insert a new statement: "<> := ". <br/> Default: `true` |
+| `unmarshal` | report passing non-pointer or non-interface values to unmarshal <br/> The unmarshal analysis reports calls to functions such as json.Unmarshal in which the argument type is not a pointer or an interface. <br/> Default: `true` |
+| `unreachable` | check for unreachable code <br/> The unreachable analyzer finds statements that execution can never reach because they are preceded by an return statement, a call to panic, an infinite loop, or similar constructs. <br/> Default: `true` |
+| `unsafeptr` | check for invalid conversions of uintptr to unsafe.Pointer <br/> The unsafeptr analyzer reports likely incorrect uses of unsafe.Pointer to convert integers to pointers. A conversion from uintptr to unsafe.Pointer is invalid if it implies that there is a uintptr-typed word in memory that holds a pointer value, because that word will be invisible to stack copying and to the garbage collector. <br/> Default: `true` |
+| `unusedparams` | check for unused parameters of functions <br/> The unusedparams analyzer checks functions to see if there are any parameters that are not being used. <br/> To reduce false positives it ignores: - methods - parameters that do not have a name or are underscored - functions in test files - functions with empty bodies or those with just a return stmt <br/> Default: `false` |
+| `unusedresult` | check for unused results of calls to some functions <br/> Some functions like fmt.Errorf return a result and have no side effects, so it is always a mistake to discard the result. This analyzer reports calls to certain functions in which the result of the call is ignored. <br/> The set of functions may be controlled using flags. <br/> Default: `true` |
### `ui.diagnostic.annotations`
+
(Experimental) annotations specifies the various kinds of optimization diagnostics
that should be reported by the gc_details command.
+| Properties | Description |
+| --- | --- |
+| `bounds` | `"bounds"` controls bounds checking diagnostics. <br/> <br/> Default: `true` |
+| `escape` | `"escape"` controls diagnostics about escape choices. <br/> <br/> Default: `true` |
+| `inline` | `"inline"` controls diagnostics about inlining choices. <br/> <br/> Default: `true` |
+| `nil` | `"nil"` controls nil checks. <br/> <br/> Default: `true` |
### `ui.diagnostic.experimentalDiagnosticsDelay`
+
(Experimental) experimentalDiagnosticsDelay controls the amount of time that gopls waits
after the most recent file modification before computing deep diagnostics.
Simple diagnostics (parsing and type-checking) are always run immediately
@@ -686,17 +683,33 @@
This option must be set to a valid duration string, for example `"250ms"`.
-Default: `250ms`
+
+Default: `"250ms"`
### `ui.diagnostic.staticcheck`
+
(Experimental) staticcheck enables additional analyses from staticcheck.io.
+
Default: `false`
### `ui.documentation.hoverKind`
+
hoverKind controls the information that appears in the hover text.
SingleLine and Structured are intended for use only by authors of editor plugins.
+<br/>
+Allowed Options:
-Default: `FullDocumentation`
+* `FullDocumentation`
+* `NoDocumentation`
+* `SingleLine`
+* `Structured`: `"Structured"` is an experimental setting that returns a structured hover format.
+This format separates the signature from the documentation, so that the client
+can do more manipulation of these fields.<br/>This should only be used by clients that support this behavior.
+* `SynopsisDocumentation`
+
+
+Default: `"FullDocumentation"`
### `ui.documentation.linkTarget`
+
linkTarget controls where documentation links go.
It might be one of:
@@ -705,21 +718,31 @@
If company chooses to use its own `godoc.org`, its address can be used as well.
-Default: `pkg.go.dev`
+
+Default: `"pkg.go.dev"`
### `ui.documentation.linksInHover`
+
linksInHover toggles the presence of links to documentation in hover.
+
Default: `true`
### `ui.navigation.importShortcut`
+
importShortcut specifies whether import statements should link to
documentation or go to definitions.
+<br/>
+Allowed Options: `Both`, `Definition`, `Link`
-Default: `Both`
+Default: `"Both"`
### `ui.navigation.symbolMatcher`
-(Advanced) symbolMatcher sets the algorithm that is used when finding workspace symbols.
-Default: `Fuzzy`
+(Advanced) symbolMatcher sets the algorithm that is used when finding workspace symbols.
+<br/>
+Allowed Options: `CaseInsensitive`, `CaseSensitive`, `Fuzzy`
+
+Default: `"Fuzzy"`
### `ui.navigation.symbolStyle`
+
(Advanced) symbolStyle controls how symbols are qualified in symbol responses.
Example Usage:
@@ -731,15 +754,31 @@
...
}
```
+<br/>
+Allowed Options:
-Default: `Dynamic`
+* `Dynamic`: `"Dynamic"` uses whichever qualifier results in the highest scoring
+match for the given symbol query. Here a "qualifier" is any "/" or "."
+delimited suffix of the fully qualified symbol. i.e. "to/pkg.Foo.Field" or
+just "Foo.Field".
+* `Full`: `"Full"` is fully qualified symbols, i.e.
+"path/to/pkg.Foo.Field".
+* `Package`: `"Package"` is package qualified symbols i.e.
+"pkg.Foo.Field".
+
+
+Default: `"Dynamic"`
### `ui.semanticTokens`
+
(Experimental) semanticTokens controls whether the LSP server will send
semantic tokens to the client.
+
Default: `false`
### `verboseOutput`
+
(For Debugging) verboseOutput enables additional debug logging.
+
Default: `false`
diff --git a/docs/testing.md b/docs/testing.md
index 2a8abf2..0a72ed1 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -37,7 +37,9 @@
This is the workflow triggered for every PR and commit made to our mirror repository on GitHub, [github.com/golang/vscode-go](https://github.com/golang/vscode-go). We use this CI system to run tests on platforms that GCB does not yet support. This workflow is not triggered by CLs sent via Gerrit yet.
-[`.github/workflows/ci.yml`](../.github/workflows/ci.yml) defines the GitHub Actions-based CI workflow.
+[`.github/workflows/test-long.yml`](../.github/workflows/test-long.yml) and
+[`.github/workflows/test-smoke.yml`](../.github/workflows/test-smoke.yml)
+define the GitHub Actions-based CI workflow.
### [Nightly Release](nightly.md)
diff --git a/docs/tools.md b/docs/tools.md
index 8a620aa..e19647b 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,102 +1,48 @@
# 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](#documentation), [Formatting](#formatting), and [Diagnostics](#diagnostics) sections below.
-
-**NOTE: If you are using the language server, [`gopls`], most of the tools below are not needed.**
-
-## Installation
+This document describes the tools that power the VS Code Go extension.
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`](commands.md#go-installupdate-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](gopath.md#install-tools-to-a-separate-gobin) if you wish to learn about storing tools in a separate directory.
+VS Code Go will install the tools to your `$GOPATH/bin` by default.
-## Table of Contents
-
-* [Go toolchain](#go-toolchain)
-* [`gocode`](#gocode)
-* [`gopkgs`](#gopkgs)
-* [`go-outline`](#go-outline)
-* [`go-symbols`](#go-symbols)
-* [`guru`](#guru)
-* [`gorename`](#gorename)
-* [`godoctor`](#godoctor)
-* [`delve`](#delve)
-* [`gomodifytags`](#gomodifytags)
-* [`goplay`](#goplay)
-* [`impl`](#impl)
-* [`gotests`](#gotests)
-* [`fillstruct`](#fillstruct)
-* [Documentation](#documentation)
- * [`gogetdoc`]
- * [`godef`]
- * [`godoc`]
-* [Formatting](#formatting)
- * [`goreturns`]
- * [`goimports`]
- * [`gofmt`]
- * [`goformat`]
-* [Diagnostics](#diagnostics)
- * [`gotype-live`]
- * [`golint`]
- * [`staticcheck`]
- * [`golangci-lint`]
- * [`revive`]
-
-### Go toolchain
-
+### [`go`]
This extension requires you to install the Go toolchain, meaning that you have the `go` command on your [`PATH`](https://en.wikipedia.org/wiki/PATH_(variable)). To do this, follow [the Go installation guide](https://golang.org/doc/install).
-The [build-on-save](features.md#build-errors) and [vet-on-save](features.md#vet-errors) features are provided by the `go build` and `go vet` commands.
+The extension runs the [`go`] command to debug and test your go program. By default, this extension assumes that Go is already installed in your system and the `go` command can be found from the `PATH` (or `Path` in some Windows) environment variable.
-### `gocode`
+This extension works best with the [latest versions of Go](https://golang.org/doc/devel/release.html#policy) but some of the features may continue to work with older versions of Go. The Go release policy states that the two newer major releases are officially supported.
-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.
+The extension checks for the availability of the new Go release by periodically checking the [official Go distribution site](https://golang.org/dl) and notifies you of the new version.
-Different versions of `gocode` are used depending on your version of Go.
+### [`gopls`]
+[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It is the default backend for most of this extension's IntelliSense, code navigation, code editing, and diagnostics features. When the extension starts, it spawns a `gopls` instance in server mode for each VS Code project.
-* Go 1.9 and above: [mdempsky/gocode](https://github.com/mdempsky/gocode)
-* Go 1.11 and above, with modules enabled: [stamblerre/gocode](https://github.com/stamblerre/gocode)
- * This version of `gocode` does not have any caching, so if you find it slow, consider using [gopls] instead.
+`gopls` uses the `go` command to analyze your code. The extension automatically propagates necessary settings such as `"go.buildFlags"`, `"go.buildTags"`, `"go.toolsEnvVars"` and the path to the right `go` command to `gopls`. No extra settings should be necessary, but when you need to adjust `gopls`'s behavior further (e.g., enable more advanced analysis features), please see [all the settings for `gopls`](https://github.com/golang/vscode-go/blob/master/docs/settings.md#settings-for-gopls).
-Learn how to [troubleshoot `gocode`](troubleshooting.md#autocompletion).
+If you encounter issues with `gopls`, please read the [troubleshooting guide](troubleshooting.md#collect-gopls-information). If you want to run the extension without the language server, you can disable it by setting `"go.useLanguageServer": false`.
+
+`gopls` officially supports the four newer major versions of Go. If you are using a very old version of Go, or you explicitly disable the language server, the extension will automatically fall back to the legacy mode. The legacy mode uses old tools instead of `gopls`. Unfortunately many of them are no longer actively maintained and many features the extension provides will not be available.
+You can tell whether the extension is using `gopls`, by checking whether the high voltage icon (⚡) is present in the [Go status bar](docs/ui.md).
+
+`gopls` is under active development, and updating it is important to get new features. The extension periodically checks the [module proxy](https://golang.org/cmd/go/#hdr-Module_proxy_protocol) to detect a new version has been released. When a newer version is available, a pop-up will appear, prompting you to update. If you would like to opt out of this automated update check, set `"go.toolsManagement.checkForUpdates"` to `false`.
+For more information about `gopls`, please visit its [documentation](https://golang.org/s/gopls).
+
+<!-- TODO: link to gopls troubleshooting guide -->
+
+### [`dlv`](https://github.com/go-delve/delve)
+This extension uses Delve for its debug/test functionalities. The extension currently ships with a thin Debug Adapter that implements the [Debug Adapter protocol](https://microsoft.github.io/debug-adapter-protocol/) and connects VS Code and `dlv`.
+
+For a comprehensive overview of how to debug your Go programs, please see the [debugging guide](docs/debugging.md).
+
### [`gopkgs`](https://pkg.go.dev/github.com/uudashr/gopkgs?tab=overview)
-This tool provides autocompletion for unimported packages.
+This tool provides autocompletion for unimported packages. Replacement of `gopkgs` with [`gopls`] is a work-in-progress. <!--TODO: reference to the issue-->
### [`go-outline`](https://pkg.go.dev/github.com/ramya-rao-a/go-outline?tab=overview)
-This tool provides the [document outline](features.md#document-outline) feature, as well as the [go to symbol](features.md#go-to-symbol) in the current file feature.
-
-### [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview)
-
-This tool provides the [go to symbol](features.md#go-to-symbol) in workspace feature.
-
-### [`guru`](https://pkg.go.dev/golang.org/x/tools/cmd/guru?tab=doc)
-
-This tool provides the [find references](features.md#find-references) and [find interface implementations](features.md#find-interface-implementations) features.
-
-It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](settings.md#go.docsTool) setting.
-
-`guru` does not have support for Go modules, so we recommend using [`gopls`] for those features instead.
-
-### [`gorename`](https://pkg.go.dev/golang.org/x/tools/cmd/gorename?tab=doc)
-
-This tool provides the [rename symbol](features.md#rename-symbol) feature.
-
-`gorename` does not have support for Go modules, so we recommend using [`gopls`] for this feature instead.
-
-### [`godoctor`](https://github.com/godoctor/godoctor)
-
-This tool provides the [refactoring](features.md#refactor) features.
-
-It does not have support for Go modules, so we expect that [`gopls`] will provide this feature instead ([golang/go#37170](https://github.com/golang/go/issues/37170)).
-
-### [`delve`](https://pkg.go.dev/github.com/go-delve/delve?tab=overview)
-
-This is the debugger for the Go language. It is used to provide the [debugging](debugging.md) features of this extension.
+This tool provides the information needed to compute the various test code lenses. It will be replaced with [`gopls`]. <!--TODO: reference to the issue-->
### [`goplay`](https://pkg.go.dev/github.com/haya14busa/goplay?tab=overview)
@@ -114,47 +60,13 @@
This tool provides support for the [`Go: Generate Unit Tests`](features.md#generate-unit-tests) set of commands.
-### [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct)
+### [`golint`]
-This tool provides support the [`Go: Fill struct`](features.md#fill-struct-literals) command.
+This is the default lint tool. Other lint tools can be used by configuring the [`"go.lintTool"`](settings.md#go.lintTool) setting. Other options include:
-### Documentation
-
-Documentation tools are used for the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#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`](#guru) can also be used, but only for the [go to definition](features.md#go-to-definition) behavior.
-
-Configure this via the [`"go.docsTool"`](settings.md#go.docsTool) setting.
-
-### Formatting
-
-Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) 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"`](settings.md#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](features.md#build-errors), [vet](features.md#vet-errors), and [lint](features.md#lint-errors) 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"`](settings.md#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](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
-* [`golangci-lint`]: This tool combines a number of existing lint tools, including [staticcheck](#staticcheck), into one interface.
-* [`revive`]: This tool is an enhancement on top of [`golint`], and it provides additional checks.
+ * [`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](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
+ * [`golangci-lint`]: This tool combines a number of existing lint tools, including [staticcheck](#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"`](settings.md#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:
@@ -179,6 +91,40 @@
]
```
+### Misc tools used in the legacy mode
+
+When `gopls` cannot be used, the extension falls back to the legacy mode. Be aware that many of these tools may be incompatible with the recent versions of Go or do not work in Modules mode.
+
+* [`go-outline`](https://pkg.go.dev/github.com/ramya-rao-a/go-outline?tab=overview):
+In the legacy mode, this tool provides the `[document outline](features.md#document-outline) feature` and the [go to symbol](features.md#go-to-symbol) in the current file feature.
+
+* `gocode`: code completion in the legacy mode is provided by `gocode`. Different versions of `gocode` are used depending on your version of Go.
+ * Go 1.9 and above: [mdempsky/gocode](https://github.com/mdempsky/gocode)
+ * Go 1.11 and above, with modules enabled: [stamblerre/gocode](https://github.com/stamblerre/gocode), named `gocode-gomod` internally.
+
+* [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview): provides the [go to symbol](features.md#go-to-symbol) in workspace feature.
+
+* [`guru`](https://pkg.go.dev/golang.org/x/tools/cmd/guru?tab=doc): provides the [find references](features.md#find-references) and [find interface implementations](features.md#find-interface-implementations) features.
+It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](settings.md#go.docsTool) setting. `guru` does not support Go modules.
+
+* [`gorename`](https://pkg.go.dev/golang.org/x/tools/cmd/gorename?tab=doc): provides the [rename symbol](features.md#rename-symbol) feature. `gorename` does not have support for Go modules
+
+* [`godoctor`](https://github.com/godoctor/godoctor): provides the [refactoring](features.md#refactor) features. It does not support Go modules, and we expect that [`gopls`] will provide this feature instead ([golang/go#37170](https://github.com/golang/go/issues/37170)).
+
+* [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct): provides support the [`Go: Fill struct`](features.md#fill-struct-literals) command.
+
+* [`gogetdoc`], [`godef`], [`godoc`]: these are documentation tools used for the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) in the legacy mode. [`guru`](#guru) can also be used, but only for the [go to definition](features.md#go-to-definition) behavior. Configure this via the [`"go.docsTool"`](settings.md#go.docsTool) setting.
+
+* [`goreturns`], [`gofmt`], [`goimports`]: Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) features. [`goreturns`] is used by default in the legacy mode. 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"`](settings.md#formatTool) setting. Note that [`goreturns`] does not have support for Go modules.
+
+ * [`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 tools: By default, [`gotype-live`], [`go vet`], and [`golint`] are used to provide [build](features.md#build-errors), [vet](features.md#vet-errors), and [lint](features.md#lint-errors) errors. [`gotype-live`] provides build errors as you type, while `go build` can be used to show build errors only on save. [`gotype-live`] does not work with modules.
+
+
+
[`gogetdoc`]: https://pkg.go.dev/github.com/zmb3/gogetdoc?tab=overview
[`godef`]: https://pkg.go.dev/github.com/rogpeppe/godef?tab=doc
[`godoc`]: https://pkg.go.dev/golang.org/x/tools/godoc?tab=doc
@@ -191,5 +137,7 @@
[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
[`golangci-lint`]: https://golangci-lint.run/
[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
-[`gopls`]: gopls.md
[`go vet`]: https://golang.org/cmd/vet/
+[`gopls`]: https://golang.org/s/gopls
+[`go`]: https://golang.org/cmd/go
+
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 3b111af..d4824e2 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,241 +1,69 @@
# Troubleshooting
-Read this document when you encounter a problem with this extension. It can provide guidance, but many cases are not covered here.
+If you suspect that the Go extension is not working correctly, please follow the troubleshooting steps below.
-If you are unable to resolve the problem after following the advice on this page, please take a look at the current [open issues](https://github.com/golang/vscode-go/issues) to see if your issue has already been reported. If not, please do not hesitate to [ask for help](#ask-for-help).
+**NOTE: [Debugging](debugging.md#troubleshooting) has its own troubleshooting documentation.**
-**NOTE: [Debugging](debugging.md#troubleshooting) and [`gopls`](gopls.md) also have their own troubleshooting documentation.**
+## Make sure your project compiles
-## Overview
+Verify that your project is in good shape by working with it at the command line. Running a command like `go build ./...` in the workspace directory will compile everything. For modules, `go mod tidy` is another good check, though it may modify your `go.mod`.
-* [Check known issues](#check-known-issues)
-* [Check your setup](#check-your-setup)
- * [Environment variables](#environment-variables)
-* [Update tools](#update-tools)
- * [If tools fail to install or update](#if-tools-fail-to-install-or-update)
-* [Look for error messages](#look-for-error-messages)
-* [Investigate](#investigate)
- * [Debugging](debugging.md#troubleshooting)
- * [Language server](gopls.md)
- * [Autocompletion](#autocompletion)
- * [Formatting](#formatting)
- * [Diagnostics](#diagnostics)
-* [Known Issues](#known-issues)
-* [Ask for help](#ask-for-help)
+## Look for serious errors and diagnostics
-### Check [known issues](#known-issues)
+Check that there aren't any diagnostics that indicate a problem with your workspace. First, check the bottom-center of the VS Code window for any errors. After that, check the package declaration of the any Go files you're working in, and your `go.mod` file. Problems in the workspace configuration can cause many different symptoms. See the [`gopls` workspace setup instructions](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for help.
-A [list of known issues](#known-issues) is available at the bottom of this page. Take a look and see if you've encountered one of these.
+## Check your extension setup
-### Check your setup
+Run the [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools) command. The output is split into sections.
-First, make sure you understand the difference between [`GOPATH`](gopath.md) and [module](modules.md) modes and know which mode you are using. Run `go version` and `go env` in the [integrated terminal] to check that your environment is configured as you expect.
+In the first indented section, check that at least `gopkgs`, `go-outline`, `dlv`, and `gopls` are installed -- they're necessary for the extension's basic functionality. The other tools [provide optional features](tools.md) and are less important unless you need those features. You can install tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
-This extension supports a few meta-commands that can be used for investigation. Try running [`Go: Locate Configured Go Tools`](commands.md#go-locate-configured-go-tools). The output should look like:
+Then, look at the `Workspace Folder` section(s) for the environment in use. Verify that `GOROOT` is set to a valid Go installation; if not, follow the [getting started guide](../README.md#install-go). If `GOPATH` is unset, or surprising, read more about [setting up your `GOPATH`](gopath.md#setting-gopath). Also, `GOMOD` should usually point to your project's `go.mod` file if you're in module mode. (More complicated workspace setups may have a blank `GOMOD`. See the `gopls` [workspace documentation](https://github.com/golang/tools/blob/master/gopls/doc/workspace.md) for more on valid workspace setups.) To change the workspace environment, use settings such as [`go.gopath`](settings.md#go.gopath) and [`go.toolsEnvVars`](settings.md#go.toolsEnvVars).
-```bash
-Checking configured tools....
-GOBIN: undefined
-toolsGopath:
-gopath: /path/to/gopath
-GOROOT: /path/to/go
-PATH: /path/to/:/another/path:/some/path
+Finally, take a look at your settings in the JSON form (`Preferences: Open Settings (JSON)`). This is an easier way to quickly see what non-default configurations you have. Consider [reading about](settings.md) any settings you don't understand, or just commenting them out.
- gocode: /path/to/gocode installed
- gopkgs: /path/to/bin/gopkgs installed
- go-outline: /path/to/bin/go-outline installed
- go-symbols: /path/to/bin/go-symbols installed
- guru: /path/to/bin/guru installed
- gorename: /path/to/bin/gorename installed
- gotests: /path/to/bin/gotests installed
- gomodifytags: /path/to/bin/gomodifytags installed
- impl: /path/to/bin/impl installed
- fillstruct: /path/to/bin/fillstruct installed
- goplay: /path/to/bin/goplay installed
- godoctor: /path/to/bin/godoctor installed
- dlv: /path/to/bin/dlv installed
- gocode-gomod: /path/to/bin/gocode-gomod installed
- godef: /path/to/bin/godef installed
- goreturns: /path/to/bin/goreturns installed
- golint: /path/to/bin/golint installed
- gopls: /path/to/bin/gopls installed
-```
+## Update tools
-If your `GOPATH` or `GOROOT` is undefined, that may indicate a problem. Read more about [setting up your `GOPATH`](gopath.md#setting-gopath). A missing `GOROOT` means that you haven't installed Go correctly. This topic is covered in the [getting started guide](../README.md#install-go).
+It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
-If one of the tools (`gocode`, `gopkgs`, etc.) is not installed, this may also indicate a problem. Take a look at the [list of tools](tools.md) required by this extension. If the missing tool provides the feature you're looking for, that might be the issue. You can install or update tools by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
+## Restart `gopls`
-Finally, take a look at your settings in the JSON form (Ctrl+Shift+P -> Preferences: Open Settings (JSON)). This is an easier way to quickly grasp what non-default configurations you have.
+Many of the extension's features are provided by [`gopls`](https://golang.org/s/gopls), the official language server for Go. `gopls` has no persistent state, so restarting it will fix transient problems. This is good and bad: good, because you can keep working, and bad, because you won't be able to debug the issue until it recurs. You can restart `gopls` using the `Go: Restart Language Server` command.
-Common culprits include:
+## Ask for help
-* [`go.inferGopath`](settings.md#go.inferGopath)
-* [`go.toolsGopath`](settings.md#go.toolsGopath)
-* [`go.alternateTools`](settings.md#go.alternateTools)
-* [`go.useLanguageServer`](settings.md#go.useLanguageServer)
+After you've done the basic steps above, it's a good time to ask for help. Gophers Slack has a channel for [#vscode](https://gophers.slack.com/archives/C2B4L99RS) that can help debug further. If you're confident the problem is with `gopls`, you can go to [#gopls](https://gophers.slack.com/archives/CJZH85XCZ). Invites are [available to everyone](https://invite.slack.golangbridge.org). Come prepared with a short description of the issue, and try to be available to answer questions for a while afterward.
-Read up on those settings, as well as all of the other [available settings](settings.md).
+## Collect extension logs
-If you are using the language server, please see the language server's [troubleshooting guide](gopls.md).
-
-#### Environment variables
-
-Note that extensions run in a separate process from the [integrated terminal] and the rest of the VS Code window. Therefore, environment variables set specifically in the [integrated terminal] are not visible to the extensions.
-
-Instead, set the environment variables in your terminal before you launch VS Code. Or, set environment variables globally in your configuration (in a `.bash_profile`, for example). You can also set environment variables for only the Go extension by adding them to [`go.toolsEnvVars`](settings.md#go.toolsEnvVars). Other settings are available to override specific variables, like your `GOPATH`, which can be set through the [`go.gopath`](settings.md#go.gopath) setting as well.
-
-### Look for error messages
-
-Start off by opening the Output pane (Ctrl+Shift+U). On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
+Start off by opening the `View` -> `Output` pane. On the right side, open the drop-down titled "Tasks". Any item that starts with "Go" is related to this extension. Browse through these output channels and make note of any error messages.
You can also look directly in the logs of the Extension Host by selecting `Log (Extension Host)`. These may contain a lot of unrelated information, but they may prove useful. If you are trying to get the logs for a specific operation, like go to definition, clear the logs (Clear Output button on the right side), and perform the operation.
Errors may also be logged to the Developer Tools console. These errors may be more difficult to parse, but you can take a look at them by running the `Developer: Toggle Developer Tools` command from the Command Palette (Ctrl+Shift+P).
-### Update tools
+## Collect `gopls` information
-It's possible that you are using an outdated version of a tool, so the bug you are encountering may have already been fixed. You can update all tools at once by running the [`Go: Install/Update Tools`](commands.md#go-installupdate-tools) command.
+The gopls log can be found by navigating to `View` -> `Output`. There will be a drop-down menu titled `Tasks` in the top-right corner. Select the `gopls (server)` item, which will contain the `gopls` logs.
-If you would prefer to update only a single tool, you can use the same command, but pick the correct tool. To learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
-
-### If tools fail to install or update
-
-It's possible that the tool installation or update will itself fail. Error messages should be printed in the output, which will hopefully guide you.
-
-Try cleaning your module cache (`go clean -modcache`) and installing once again.
-
-If you are using Go 1.10 or below, something may have gone wrong with the repository that contains the tool on your machine. Try deleting the directory that contains the tool and installing again. The directory will be in your `$GOPATH/src/`. The name of the directory will be the name of the repository in which the tool is hosted; it's usually something like `github.com/stamblerre/gocode`. Note that, if you have configured the [`go.toolsGopath`](settings.md#go.toolsGopath), you should look in that directory.
-
-If that doesn't work, there may be a problem with the tool itself. Check if there are any issues filed in the tool's repository. If not, please file an issue in that repository and let us know by [filing an issue](https:/github.com/golang/vscode-go/issues/new/choose) in the VS Code Go repository as well.
-
-## Investigate
-
-Issues in certain parts of the extension, specifically [debugging](debugging.md#troubleshooting) and the [language server](gopls.md), are described in more depth on other pages. Please take a look at those specific guides.
-
-Other issues may be caused by other command-line tools. As mentioned above, to learn which tool corresponds to the broken feature, read the [Features](features.md) and [Tools](tools.md) documentation pages. [Features](features.md) describes functionality in detail and lists which tool provides that functionality, while [Tools](tools.md) is the reverse, describing each tool and then listing which features it provides.
-
-Once you've identified the correct tool, make sure it works for you on the command-line. Read the documentation and usage guide for the tool and try running it manually. Most tools may require you to provide a line and column number or byte offset in a file.
-
-If the tool works correctly on the command-line, then the issue is in this extension. In that case, please [file an issue].
-
-If the tool does not work correctly on the command-line, that means there is an issue in the tool. In that case, please file an issue in the GitHub repository of the tool itself.
-
-### Autocompletion
-
-Autocompletion is one of the most complicated features. Troubleshooting it can be tricky, but doable.
-
-The following only applies if you are **not** using the language server. If you are, see [the `gopls` troubleshooting guide](gopls.md).
-
-The tool that provides autocompletion is called [`gocode`](tools.md#gocode), so try checking error logs and updating [`gocode`](tools.md#gocode). If you are using [Go modules], the binary on your machine will be called `gocode-gomod`, not `gocode`, as the extension uses a different version of `gocode` for modules.
-
-Next, make sure that the package you are trying to complete has been built at least once. You can do this by either running [`Go: Build Current Package`](commands.md#go-build-current-package) or by running `go install` on the command-line. If you have enabled [`go.buildOnSave`](settings.md#go.buildOnSave) or [`go.gocodeAutobuild`](settings.md#go.gocodeAutobuild), this should happen automatically.
-
-If you have noticed that your autocompletion results are not missing, but simply out-of date, check the value of your [`"go.buildOnSave"`](settings.md#buildOnSave) setting. If it is `"off"`, then you may not get fresh results your dependencies. You can rebuild your dependencies manually by running `go install`.
-
-If that doesn't work, try running `gocode close` on the command-line. If you are using [Go modules], run `gocode-gomod close`.
-
-Finally, try exiting VS Code Go and running:
-
-```bash
-gocode close
-gocode -s -debug
-```
-
-This will start a `gocode` debug server, which will print output as you trigger completions. Reopen VS Code and try to complete. You can trigger completion manually using Ctrl+Space. Make note of the debug output. If you can determine the issue from the output, you can correct it yourself. Otherwise, please [file an issue] and include this output in your report, if you are able to do so.
-
-### Formatting
-
-By default, this extension formats your code and organizes your imports on file save. New imports will be added and unused imports will be removed automatically. This is [standard Go style](https://golang.org/cmd/gofmt/). Learn more about the different [formatting tools](tools.md#formatting) to get a better understanding.
-
-If necessary, it is possible to disable the formatting behaviors. You will still be able to trigger formatting manually (right-click, Format Document).
-
-#### Disable formatting
-
-If you are **NOT using the language server** (`"go.useLanguageServer": false`, which is the default):
-
-* Format on save, but **do not** organize imports on save:
-
- ```json5
- "go.formatTool": "gofmt"
- ```
-
-* Do not format or organize imports on save:
-
- ```json5
- "[go]": {
- "editor.formatOnSave": false
- }
- ```
-
-If you **are using the language server** (`"go.useLanguageServer": true`):
-
-* Format on save, but **do not** organize imports on save:
-
- ```json5
- "[go]": {
- "editor.codeActionsOnSave": {
- "source.organizeImports": false
- }
- }
- ```
-
-* Do not format or organize imports on save:
-
- ```json5
- "[go]": {
- "editor.formatOnSave": false,
- "editor.codeActionsOnSave": {
- "source.organizeImports": false
- }
- }
- ```
-
-Learn more in the [language server documentation](gopls.md).
-
-#### Use spaces instead of tabs
-
-The default Go formatting tools use tabs over spaces, and this have become an industry standard for Go. Read more about [Effective Go](https://golang.org/doc/effective_go.html#formatting). The only way to switch from tabs to spaces is by also disabling formatting.
-
-#### Change tab size
-
-The default tab size in VS Code is 4. You can change this only for Go files by adding the following to your settings.
+To increase the level of detail in your logs, add the following to your settings:
```json5
-"[go]": {
- "editor.tabSize": 8
-}
+"go.languageServerFlags": [
+ "-rpc.trace"
+]
```
-### Diagnostics
+## File an issue
-This extension provides a number of [diagnostic features](features.md#diagnostics) to improve your code quality and alert you to build errors. These will appear as red or yellow squiggly underlines, and they will also appear in the Problems pane at the bottom of the screen. Learn more about the different [diagnostic tools](tools.md#diagnostics) to understand which ones you are using.
+We can't diagnose a problem from just a description. When filing an issue, please include as much as possible of the following information:
-#### Build errors
+1. Your Go version: `go -version`
+1. Your `gopls` version: `gopls -v version`
+1. Your vscode version: `code -v`
+1. Your Go extension version: `Extensions: Show Installed Extensions`
+1. Your Go environment: `go env` in the workspace folder
+1. Relevant VS Code settings: run `Preferences: Open Settings (JSON)` and include anything in a `[go]` block, and anything that starts with `go.` or `gopls.`
+1. Extension and `gopls` logs as seems appropriate for the bug.
-Any errors marked by red squiggles are build errors. These indicate that your code will not compile. If you think these errors are incorrect, try checking on the command-line by running `go build` or `go test`.
-
-If the build commands succeed, try copying the exact command used by VS Code Go. You can find it by navigating to the output pane (Ctrl+Shift+P -> `View: Toggle Output`). Choose the `Go` output channel from the Tasks drop-down in the top-right corner. This will show the exact command VS Code ran. Copy and run it.
-
-If you see the same errors, you may have misconfigured your project. Learn more about how to do this correctly in [set up your environment](../README.md#set-up-your-environment).
-
-If the command runs fine on the command-line, it's possible you've misconfigured something in your VS Code Go environment, such as your [`GOPATH`](gopath.md). Review [check your set-up](#check-your-set-up), and if the issue still persists, please [file an issue].
-
-## Ask for help
-
-It's possible that after following these steps, you still will not have found a solution to your problem. In this case, please ask for help!
-
-Reach out to the VS Code Go maintainers by:
-
-* [Filing an issue](https://github.com/golang/vscode-go/issues/new/choose)
-* Asking a question on the `#vscode` channel of the [Gophers Slack]
-
-## Known Issues
-
-**I keep seeing a "Running save participants..." pop-up when I save my file.**
-
-Take a look at the suggestions on [Microsoft/vscode-go#3179](https://github.com/microsoft/vscode-go/issues/3179#issue-600430641). If you still cannot resolve the problem, please [file an issue].
-
-[Gophers Slack]: https://gophers.slack.com/
-[file an issue]: https://github.com/golang/vscode-go/issues/new/choose
-[Go modules]: https://blog.golang.org/using-go-modules
-[integrated terminal]: https://code.visualstudio.com/docs/editor/integrated-terminal
+Once you've collected that information, [file your issue](https://github.com/golang/vscode-go/issues/new/choose).
\ No newline at end of file
diff --git a/docs/ui.md b/docs/ui.md
index 1287234..16f51cc 100644
--- a/docs/ui.md
+++ b/docs/ui.md
@@ -29,7 +29,7 @@
### Language Server Status
-`gopls` is the official Go [language server](https://langserver.org/) developed by the Go team. It was developed in response to the release of [Go modules](docs/modules.md), and it is the recommended approach when working with [Go modules](docs/modules.md) in VS Code.
+`gopls` is the official Go [language server](https://langserver.org/) developed by the Go team. It was developed in response to the release of [Go modules](docs/modules.md), and it is the recommended approach when working with Go modules in VS Code.
When `gopls` is enabled, :zap: is displayed next to the Go version in the status bar and the `gopls` version is displayed in the menu.
diff --git a/media/announce.png b/media/announce.png
new file mode 100644
index 0000000..60c45d0
--- /dev/null
+++ b/media/announce.png
Binary files differ
diff --git a/media/welcome.css b/media/welcome.css
index 857d9ed..d866448 100644
--- a/media/welcome.css
+++ b/media/welcome.css
@@ -3,25 +3,91 @@
* Licensed under the MIT License. See LICENSE in the project root for license information.
*--------------------------------------------------------*/
-.header {
+.Content {
+ max-width: 60rem;
+ font-size: 1rem;
+ line-height: 1.5rem;
+ margin: auto;
+}
+
+.Header {
align-items: center;
display: flex;
+ border-bottom: 0.0625rem solid #ccc;
+ margin-bottom: 2rem;
+ padding-bottom: 1.25rem;
+}
+.Header-logo {
+ width: 12rem;
+ margin-right: 3rem;
+}
+.Header-title {
+ font-size: 1.75rem;
}
-.logo {
- width: 4rem;
+.Announcement {
+ display: flex;
+ flex-direction: row;
+ align-items: center;
+ font-style: italic;
+ padding: 1rem;
+}
+.Announcement-image {
+ height: 2rem;
+ flex: 0;
+ margin-right: 1.5rem;
}
-.title {
- padding-left: 1rem;
-}
-
-.subtitle {
- align-items: baseline;
+.Cards {
display: flex;
+ flex-direction: column;
+ flex-wrap: wrap;
+}
+.Card {
+ max-width: 40rem;
+ flex: 1;
+}
+.Card-inner {
+ display: flex;
+ flex: 1;
+ flex-direction: column;
+ padding: 0rem;
+}
+.Card-title {
+ font-size: 1.5rem;
+ font-weight: 500;
+}
+.Card-content {
+ margin: 0;
}
-.release-notes {
- padding-left: 1rem;
+a:link,
+a:visited {
+ text-decoration: none;
+}
+.Command:hover,
+a:hover {
+ text-decoration: underline;
}
+@media (min-width: 40rem) {
+ .Header-links {
+ list-style: none;
+ padding: 0;
+ }
+ .Header-links li {
+ float: left;
+ }
+ .Header-links li:not(:first-child):before {
+ content: "|";
+ color: #ccc;
+ padding: 0 1rem;
+ }
+ .Cards {
+ flex-direction: row;
+ justify-content: space-between;
+ }
+ .Card:not(:last-child) {
+ margin-right: 4rem;
+ }
+}
diff --git a/media/welcome.js b/media/welcome.js
index 8457bbe..54bd2be 100644
--- a/media/welcome.js
+++ b/media/welcome.js
@@ -8,15 +8,13 @@
(function () {
const vscode = acquireVsCodeApi();
- function showReleaseNotes() {
- vscode.postMessage({
- command: 'showReleaseNotes',
- });
- }
-
- document.querySelector(".release-notes").addEventListener('click', () => {
- showReleaseNotes();
- });
-
+ const commands = document.querySelectorAll('.Command');
+ for (let i = 0; i < commands.length; i++) {
+ const elem = commands[i];
+ const msg = JSON.parse(JSON.stringify(elem.dataset));
+ elem.addEventListener('click', () => {
+ vscode.postMessage(msg);
+ })
+ }
}());
diff --git a/package.json b/package.json
index 2328d79..7fac640 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "go",
"displayName": "Go",
- "version": "0.21.1",
+ "version": "0.22.0",
"publisher": "golang",
"description": "Rich Go language support for Visual Studio Code",
"author": {
@@ -1245,7 +1245,7 @@
},
"go.useLanguageServer": {
"type": "boolean",
- "default": false,
+ "default": true,
"description": "Use the Go language server \"gopls\" from Google for powering language features like code navigation, completion, refactoring, formatting & diagnostics."
},
"go.languageServerFlags": {
diff --git a/src/goLanguageServer.ts b/src/goLanguageServer.ts
index 2351925..67dbd33 100644
--- a/src/goLanguageServer.ts
+++ b/src/goLanguageServer.ts
@@ -1546,69 +1546,11 @@
return { failureReason: 'unrecognized crash pattern' };
}
-export async function promptForLanguageServerDefaultChange(cfg: vscode.WorkspaceConfiguration) {
- const useLanguageServer = cfg.inspect<boolean>('useLanguageServer');
- if (!languageServerUsingDefault(cfg)) {
- if (!cfg['useLanguageServer']) { // ask users who explicitly disabled.
- promptForLanguageServerOptOutSurvey();
- }
- return; // user already explicitly set the field.
- }
-
- const promptedForLSDefaultChangeKey = `promptedForLSDefaultChange`;
- if (getFromGlobalState(promptedForLSDefaultChangeKey, false)) {
- return;
- }
-
- const selected = await vscode.window.showInformationMessage(
- `"go.useLanguageServer" is enabled by default. If you need to disable it, please configure in the settings.`,
- 'Open Settings', 'OK');
- switch (selected) {
- case 'Open Settings':
- vscode.commands.executeCommand('workbench.action.openSettings', 'go.useLanguageServer');
- default:
- }
- updateGlobalState(promptedForLSDefaultChangeKey, true);
-}
-
function languageServerUsingDefault(cfg: vscode.WorkspaceConfiguration): boolean {
const useLanguageServer = cfg.inspect<boolean>('useLanguageServer');
return useLanguageServer.globalValue === undefined && useLanguageServer.workspaceValue === undefined;
}
-// Prompt users who disabled the language server and ask to file an issue.
-async function promptForLanguageServerOptOutSurvey() {
- const promptedForLSOptOutSurveyKey = `promptedForLSOptOutSurvey`;
- const value = getSurveyConfig(promptedForLSOptOutSurveyKey); // We use only 'prompt' and 'lastDatePrompted' fields.
-
- if (value?.prompt === false ||
- (value?.lastDatePrompted && daysBetween(value.lastDatePrompted, new Date()) < 90)) {
- return;
- }
-
- value.lastDatePrompted = new Date();
-
- const selected = await vscode.window.showInformationMessage(
- `Looks like you've disabled the language server. Would you be willing to file an issue and tell us why you had to disable it?`,
- 'Yes', 'Not now', 'Never');
- switch (selected) {
- case 'Yes':
- const title = 'gopls: automated issue report (opt out)';
- const body = `
-Please tell us why you had to disable the language server.
-
-`;
- const url = `https://github.com/golang/vscode-go/issues/new?title=${title}&labels=upstream-tools&body=${body}`;
- await vscode.env.openExternal(vscode.Uri.parse(url));
- break;
- case 'Never':
- value.prompt = false;
- break;
- default:
- }
- updateGlobalState(promptedForLSOptOutSurveyKey, JSON.stringify(value));
-}
-
interface ExtensionInfo {
version?: string; // Extension version
appName: string; // The application name of the editor, like 'VS Code'
diff --git a/src/goMain.ts b/src/goMain.ts
index 940d2d1..9710a3b 100644
--- a/src/goMain.ts
+++ b/src/goMain.ts
@@ -35,7 +35,6 @@
import {
isInPreviewMode,
languageServerIsRunning,
- promptForLanguageServerDefaultChange,
resetSurveyConfig,
showServerOutputChannel,
showSurveyConfig,
@@ -107,8 +106,6 @@
}
if (isInPreviewMode()) {
- promptForLanguageServerDefaultChange(cfg);
-
// For Nightly extension users, show a message directing them to forums
// to give feedback.
setTimeout(showGoNightlyWelcomeMessage, 10 * timeMinute);
@@ -581,7 +578,7 @@
function showGoWelcomePage(ctx: vscode.ExtensionContext) {
// Update this list of versions when there is a new version where we want to
// show the welcome page on update.
- const showVersions: string[] = [];
+ const showVersions: string[] = ['0.22.0'];
let goExtensionVersionKey = 'go.extensionVersion';
if (isInPreviewMode()) {
@@ -592,12 +589,22 @@
const goExtensionVersion = goExtension.packageJSON.version;
const savedGoExtensionVersion = getFromGlobalState(goExtensionVersionKey, '0.0.0');
- if (semver.gt(semver.coerce(goExtensionVersion), semver.coerce(savedGoExtensionVersion))) {
- updateGlobalState(goExtensionVersionKey, goExtensionVersion);
- if (showVersions.includes(goExtensionVersion)) {
- WelcomePanel.createOrShow(ctx.extensionUri);
- }
+ if (shouldShowGoWelcomePage(showVersions, goExtensionVersion, savedGoExtensionVersion)) {
+ WelcomePanel.createOrShow(ctx.extensionUri);
}
+ if (goExtensionVersion !== savedGoExtensionVersion) {
+ updateGlobalState(goExtensionVersionKey, goExtensionVersion);
+ }
+}
+
+export function shouldShowGoWelcomePage(showVersions: string[], newVersion: string, oldVersion: string): boolean {
+ if (newVersion === oldVersion) {
+ return false;
+ }
+ const coercedNew = semver.coerce(newVersion);
+ const coercedOld = semver.coerce(oldVersion);
+ // Both semver.coerce(0.22.0) and semver.coerce(0.22.0-rc.1) will be 0.22.0.
+ return semver.gte(coercedNew, coercedOld) && showVersions.includes(coercedNew.toString());
}
async function showGoNightlyWelcomeMessage() {
diff --git a/src/goTools.ts b/src/goTools.ts
index a4e4d97..34305b1 100644
--- a/src/goTools.ts
+++ b/src/goTools.ts
@@ -374,10 +374,10 @@
isImportant: true,
description: 'Language Server from Google',
minimumGoVersion: semver.coerce('1.12'),
- latestVersion: semver.coerce('0.5.1'),
- latestVersionTimestamp: moment('2020-09-30', 'YYYY-MM-DD'),
- latestPrereleaseVersion: semver.coerce('0.5.1'),
- latestPrereleaseVersionTimestamp: moment('2020-09-30', 'YYYY-MM-DD'),
+ latestVersion: semver.coerce('0.6.4'),
+ latestVersionTimestamp: moment('2021-01-19', 'YYYY-MM-DD'),
+ latestPrereleaseVersion: semver.coerce('0.6.4'),
+ latestPrereleaseVersionTimestamp: moment('2021-01-19', 'YYYY-MM-DD'),
},
'dlv': {
name: 'dlv',
diff --git a/src/welcome.ts b/src/welcome.ts
index 7b6fe8d..d41ac26 100644
--- a/src/welcome.ts
+++ b/src/welcome.ts
@@ -7,13 +7,14 @@
// https://github.com/microsoft/vscode-extension-samples/tree/master/webview-sample
import vscode = require('vscode');
+import { extensionId } from './const';
export class WelcomePanel {
public static currentPanel: WelcomePanel | undefined;
public static readonly viewType = 'welcomeGo';
- public static createOrShow(extensionUri: vscode.Uri) {
+ public static createOrShow(extensionUri: vscode.Uri, ) {
const column = vscode.window.activeTextEditor
? vscode.window.activeTextEditor.viewColumn
: undefined;
@@ -27,7 +28,7 @@
// Otherwise, create a new panel.
const panel = vscode.window.createWebviewPanel(
WelcomePanel.viewType,
- 'Go - Welcome',
+ 'Go for VS Code',
column || vscode.ViewColumn.One,
{
// Enable javascript in the webview
@@ -71,10 +72,13 @@
case 'alert':
vscode.window.showErrorMessage(message.text);
return;
- case 'showReleaseNotes':
- const uri = vscode.Uri.joinPath(this.extensionUri, 'CHANGELOG.md');
+ case 'openDocument':
+ const uri = vscode.Uri.joinPath(this.extensionUri, message.document);
vscode.commands.executeCommand('markdown.showPreviewToSide', uri);
return;
+ case 'openSetting':
+ vscode.commands.executeCommand('workbench.action.openSettings', message.setting);
+ return;
}
},
null,
@@ -106,73 +110,88 @@
const scriptPathOnDisk = vscode.Uri.joinPath(this.dataroot, 'welcome.js');
const stylePath = vscode.Uri.joinPath(this.dataroot, 'welcome.css');
const gopherPath = vscode.Uri.joinPath(this.dataroot, 'go-logo-blue.png');
+ const announcePath = vscode.Uri.joinPath(this.dataroot, 'announce.png');
+ const goExtension = vscode.extensions.getExtension(extensionId)!;
+ const goExtensionVersion = goExtension.packageJSON.version;
// Uri to load styles and images into webview
const scriptURI = webview.asWebviewUri(scriptPathOnDisk);
const stylesURI = webview.asWebviewUri(stylePath);
const gopherURI = webview.asWebviewUri(gopherPath);
+ const announceURI = webview.asWebviewUri(announcePath);
// Use a nonce to only allow specific scripts to be run
const nonce = getNonce();
+
return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
-
<!--
Use a content security policy to only allow loading images from https or from our extension directory,
and only allow scripts that have a specific nonce.
-->
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${webview.cspSource}; img-src ${webview.cspSource} https:; script-src 'nonce-${nonce}';">
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
-
<link href="${stylesURI}" rel="stylesheet">
-
- <title>Go - Welcome</title>
+ <title>Go for VS Code</title>
</head>
<body>
- <div class="header">
- <img src="${gopherURI}" alt="logo" class="logo"/>
- <h1 class="title">Go - Welcome</h1>
+ <main class="Content">
+ <div class="Header">
+ <img src="${gopherURI}" alt="Go Logo" class="Header-logo"/>
+ <div class="Header-details">
+ <h1 class="Header-title">Go for VS Code v${goExtensionVersion}</h1>
+ <p>The official Go extension for Visual Studio Code, providing rich language support for Go projects.</p>
+ <ul class="Header-links">
+ <!--
+ Here and elsewhere, we must use a fake anchor for command buttons, to get styling
+ consistent with links. We can't fake this using CSS, as it conflicts with theming.
+ -->
+ <li><a href="#" class="Command" data-command="openDocument" data-document="CHANGELOG.md">Release notes</a></li>
+ <li><a href="https://github.com/golang/vscode-go">GitHub</a></li>
+ <li><a href="https://gophers.slack.com/messages/vscode/">Slack</a></li>
+ </ul>
+ </div>
</div>
- <div class="subtitle">
- <p>Rich Go language support for Visual Studio Code</p>
- <!-- linking to a document does not actually work, but is used here to give it the appearance
- of a link -->
- <a class="release-notes" href="#">Release Notes</a>
+ <div class="Announcement">
+ <img src="${announceURI}" alt="announce" class="Announcement-image" />
+ <p>
+ Heads up! Gopls, the official Go language server, is now enabled in VS Code by default.
+ Gopls replaces several legacy tools to provide IDE features while editing Go code.
+ See <a href="https://github.com/golang/vscode-go/issues/1037">issue 1037</a> for more
+ information.
+ </p>
</div>
- <div>
- <h2>Latest Updates</h2>
- <p>📣 Announcement: We plan to enable the language server, gopls, by default early in 2021. (<a href="https://github.com/golang/vscode-go/issues/1037">Issue 1037</a>)</p>
- <p>Please test and provide us your feedback on the #vscode-dev <a href="https://gophers.slack.com/">Gophers Slack</a> channel.</p>
+ <div class="Cards">
+ <div class="Card">
+ <div class="Card-inner">
+ <p class="Card-title">Getting started</p>
+ <p class="Card-content">Learn about the Go extension in our
+ <a href="https://github.com/golang/vscode-go/blob/master/README.md">README</a>.
+ </p>
+ </div>
+ </div>
+
+ <div class="Card">
+ <div class="Card-inner">
+ <p class="Card-title">Learning Go</p>
+ <p class="Card-content">If you're new to the Go programming language,
+ <a href="https://learn.go.dev">learn.go.dev</a> is a great place to get started.</a>
+ </p>
+ </div>
+ </div>
+
+ <div class="Card">
+ <div class="Card-inner">
+ <p class="Card-title">Troubleshooting</p>
+ <p class="Card-content">Experiencing problems? Start with our
+ <a href="https://github.com/golang/vscode-go/blob/master/docs/troubleshooting.md">troubleshooting guide</a>. </p> </div>
+ </div>
</div>
-
- <div>
- <h2>External Resources</h2>
-
- <h3>Documentation</h3>
- <ul>
- <li>Details about the <a href="https://github.com/golang/vscode-go#features">features</a> provided by extension</li>
- <li>Configure the extension with <a href="https://github.com/golang/vscode-go/blob/master/docs/settings.md">settings</a></li>
- <li>Full list of the <a href="https://github.com/golang/vscode-go/blob/master/docs/commands.md#detailed-list">commands</a> provided by the Go extension</li>
- <li><a href="https://github.com/golang/vscode-go/blob/master/docs/debugging.md">Debugging</a></li>
- </ul>
-
- <h3>Go Tutorials</h3>
- <ul>
- <!-- TODO: link a tutorial for setting up and using Go Modules in vscode -->
- <li>Learn about <a href="https://blog.golang.org/using-go-modules">Go Modules</a></li>
- <li>Find tutorials for using Go at <a href="https://learn.go.dev/">learn.go.dev</a></li>
- <li>Get started with <a href="https://github.com/golang/vscode-go/blob/master/docs/debugging.md#set-up">debugging</a> in vscode with the Go extension</li>
- </ul>
-
- <h3>Outstanding Issues</h3>
-
- All of the issues can be found on the <a href="https://github.com/golang/vscode-go/issues">issue tracker</a>. For issues that will be addressed in the next release, check out the <a href="https://github.com/golang/vscode-go/milestones">milestone</a> page.
- <div>
+ </main>
<script nonce="${nonce}" src="${scriptURI}"></script>
</body>
diff --git a/test/integration/welcome.test.ts b/test/integration/welcome.test.ts
new file mode 100644
index 0000000..a3856a1
--- /dev/null
+++ b/test/integration/welcome.test.ts
@@ -0,0 +1,59 @@
+/*---------------------------------------------------------
+ * Copyright 2020 The Go Authors. All rights reserved.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ *--------------------------------------------------------*/
+
+import * as assert from 'assert';
+import { shouldShowGoWelcomePage } from '../../src/goMain';
+
+suite('WelcomePanel Tests', () => {
+ // 0:showVersions, 1:newVersion, 2:oldVersion, 3:expected
+ type testCase = [string[], string, string, boolean];
+ const testCases: testCase[] = [
+ [[], '0.22.0', '0.0.0', false],
+ [[], '0.22.0', '0.21.0', false],
+ [[], '0.22.0', '0.22.0-rc.1', false],
+ [[], '0.22.0', '0.22.0', false],
+ [[], '0.22.0', '0.23.0', false],
+
+ [['0.22.0'], '0.22.0', '0.0.0', true],
+ [['0.22.0'], '0.22.0', '0.21.0-rc.1', true],
+ [['0.22.0'], '0.22.0', '0.21.0', true],
+ [['0.22.0'], '0.22.0', '0.22.0-rc.1', true],
+ [['0.22.0'], '0.22.0', '0.22.0', false],
+ [['0.22.0'], '0.22.0', '0.22.1', false],
+ [['0.22.0'], '0.22.0', '0.23.0', false],
+ [['0.22.0'], '0.22.0', '1.0.0', false],
+ [['0.22.0'], '0.22.0', '2021.1.100', false],
+
+ [['0.22.0'], '0.22.0-rc.2', '0.0.0', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.21.0-rc.1', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.21.0', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.22.0-rc.1', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.22.0-rc.2', false],
+ [['0.22.0'], '0.22.0-rc.2', '0.22.0-rc.3', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.22.0', true],
+ [['0.22.0'], '0.22.0-rc.2', '0.22.1', false],
+ [['0.22.0'], '0.22.0-rc.2', '0.23.0', false],
+ [['0.22.0'], '0.22.0-rc.2', '1.0.0', false],
+ [['0.22.0'], '0.22.0-rc.2', '2021.1.100', false],
+
+ [['0.22.0'], '0.22.1', '0.0.0', false],
+ [['0.22.0'], '0.22.1', '0.21.0-rc.1', false],
+ [['0.22.0'], '0.22.1', '0.21.0', false],
+ [['0.22.0'], '0.22.1', '0.22.0-rc.1', false],
+ [['0.22.0'], '0.22.1', '0.22.0', false],
+ [['0.22.0'], '0.22.1', '0.23.0', false],
+ [['0.22.0'], '0.22.1', '1.0.0', false],
+ [['0.22.0'], '0.22.1', '2021.1.100', false],
+ ];
+ testCases.forEach((c: testCase) => {
+ const [showVersions, newVersion, oldVersion, expected] = c;
+
+ test(`shouldShowGoWelcomePage(${JSON.stringify(showVersions)}, ${newVersion}, ${oldVersion})`, () => {
+ assert.strictEqual(
+ shouldShowGoWelcomePage(showVersions, newVersion, oldVersion), expected);
+ });
+ });
+
+});
diff --git a/tools/generate.go b/tools/generate.go
index 4897522..acaada5 100644
--- a/tools/generate.go
+++ b/tools/generate.go
@@ -50,11 +50,11 @@
MarkdownDeprecationMessage string `json:"markdownDeprecationMessage,omitempty"`
DeprecationMessage string `json:"deprecationMessage,omitempty"`
Type interface{} `json:"type,omitempty"`
- Enum []string `json:"enum,omitempty"`
+ Enum []interface{} `json:"enum,omitempty"`
+ EnumDescriptions []string `json:"enumDescriptions,omitempty"`
+ MarkdownEnumDescriptions []string `json:"markdownEnumDescriptions,omitempty"`
}
-const indent = " "
-
func main() {
flag.Parse()
@@ -109,9 +109,9 @@
os.Exit(1) // causes CI to break.
}
}
- var b bytes.Buffer
+ b := &bytes.Buffer{}
for i, c := range pkgJSON.Contributes.Commands {
- b.WriteString(fmt.Sprintf("### `%s`\n\n%s", c.Title, c.Description))
+ fmt.Fprintf(b, "### `%s`\n\n%s", c.Title, c.Description)
if i != len(pkgJSON.Contributes.Commands)-1 {
b.WriteString("\n\n")
}
@@ -135,90 +135,118 @@
return properties[i].name < properties[j].name
})
- for i, p := range properties {
+ for _, p := range properties {
if p.name == "gopls" {
desc := "Customize `gopls` behavior by specifying the gopls' settings in this section. " +
"For example, \n```\n\"gopls\" : {\n\t\"build.directoryFilters\": [\"-node_modules\"]\n\t...\n}\n```\n" +
"This section is directly read by `gopls`. See the [`gopls` section](#settings-for-gopls) section " +
"for the full list of `gopls` settings."
- b.WriteString(fmt.Sprintf("### `%s`\n\n%s", p.name, desc))
+ fmt.Fprintf(b, "### `%s`\n\n%s", p.name, desc)
b.WriteString("\n\n")
continue
}
- desc := p.Description
- if p.MarkdownDescription != "" {
- desc = p.MarkdownDescription
- }
- deprecation := p.DeprecationMessage
- if p.MarkdownDeprecationMessage != "" {
- deprecation = p.MarkdownDeprecationMessage
- }
-
- name := p.name
- if deprecation != "" {
- name += " (deprecated)"
- desc = deprecation + "\n" + desc
- }
-
- b.WriteString(fmt.Sprintf("### `%s`\n\n%s", name, desc))
-
- if p.Enum != nil {
- b.WriteString(fmt.Sprintf("\n\nAllowed Values:`%v`", p.Enum))
- }
- switch p.Type {
- case "object":
- writeSettingsObjectProperties(&b, p.Properties)
-
- x, ok := p.Default.(map[string]interface{})
- // do nothing if it is nil
- if ok && len(x) > 0 {
- keys := []string{}
- for k := range x {
- keys = append(keys, k)
- }
- sort.Strings(keys)
- b.WriteString("\nDefault:{<br/>\n")
- for _, k := range keys {
- v := x[k]
- output := fmt.Sprintf("%v", v)
- if str, ok := v.(string); ok {
- output = fmt.Sprintf("%q", str)
- }
- // if v is an empty string, nothing gets printed
- // if v is a map/object, it is printed on one line
- // this could be improved at the cost of more code
- b.WriteString(fmt.Sprintf("%s`\"%s\": %s`,<br/>\n", indent, k, output))
- }
- b.WriteString(" }\n")
- }
-
- case "boolean", "string", "number":
- b.WriteString(fmt.Sprintf("\n\nDefault: `%v`", p.Default))
- case "array":
- x := p.Default.([]interface{})
- if len(x) > 0 {
- b.WriteString(fmt.Sprintf("\n\nDefault: `%v`", p.Default))
- }
- default:
- if _, ok := p.Type.([]interface{}); ok {
- b.WriteString(fmt.Sprintf("\n\nefault: `%v`", p.Default))
- break
- }
- log.Fatalf("implement default when p.Type is %q in %#v %T", p.Type, p, p.Default)
- }
- if i != len(properties)-1 {
- b.WriteString("\n\n")
- }
+ writeProperty(b, "###", p)
+ b.WriteString("\n")
}
// Write gopls section.
b.WriteString("## Settings for `gopls`\n\n")
- writeGoplsSettingsSection(&b, goplsProperty)
+ writeGoplsSettingsSection(b, goplsProperty)
rewrite(filepath.Join(dir, "docs", "settings.md"), b.Bytes())
}
+func writeProperty(b *bytes.Buffer, heading string, p Property) {
+ desc := p.Description
+ if p.MarkdownDescription != "" {
+ desc = p.MarkdownDescription
+ }
+ deprecation := p.DeprecationMessage
+ if p.MarkdownDeprecationMessage != "" {
+ deprecation = p.MarkdownDeprecationMessage
+ }
+
+ name := p.name
+ if deprecation != "" {
+ name += " (deprecated)"
+ desc = deprecation + "\n" + desc
+ }
+
+ fmt.Fprintf(b, "%s `%s`\n\n%s", heading, name, desc)
+
+ if enums := enumDescriptionsSnippet(p); enums != "" {
+ fmt.Fprintf(b, "<br/>\n%s", enums)
+ }
+
+ if p.Type == "object" {
+ writeSettingsObjectProperties(b, p.Properties)
+ }
+
+ if defaults := defaultDescriptionSnippet(p); defaults != "" {
+ b.WriteString("\n\n")
+ if p.Type == "object" {
+ fmt.Fprintf(b, "Default:\n```\n%v\n```", defaults)
+ } else {
+ fmt.Fprintf(b, "Default: `%v`", defaults)
+ }
+ }
+}
+
+func defaultDescriptionSnippet(p Property) string {
+ if p.Default == nil {
+ return ""
+ }
+ b := &bytes.Buffer{}
+ switch p.Type {
+ case "object":
+ x, ok := p.Default.(map[string]interface{})
+ // do nothing if it is nil
+ if ok && len(x) > 0 {
+ writeMapObject(b, "", x)
+ }
+ case "string":
+ fmt.Fprintf(b, "%q", p.Default)
+ case "boolean", "number":
+ fmt.Fprintf(b, "%v", p.Default)
+ case "array":
+ if x, ok := p.Default.([]interface{}); ok && len(x) > 0 {
+ fmt.Fprintf(b, "%v", p.Default)
+ }
+ default:
+ if _, ok := p.Type.([]interface{}); ok {
+ fmt.Fprintf(b, "%v", p.Default)
+ break
+ }
+ log.Fatalf("implement default when p.Type is %q in %#v %T", p.Type, p, p.Default)
+ }
+ return b.String()
+}
+
+func writeMapObject(b *bytes.Buffer, indent string, obj map[string]interface{}) {
+ keys := []string{}
+ for k := range obj {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ fmt.Fprintf(b, "%v{\n", indent)
+ for _, k := range keys {
+ fmt.Fprintf(b, "%v%q :\t", indent+"\t", k)
+
+ v := obj[k]
+ switch v := v.(type) {
+ case string:
+ fmt.Fprintf(b, "%q", v)
+ case map[string]interface{}:
+ writeMapObject(b, indent+"\t", v)
+ default:
+ fmt.Fprintf(b, "%v", v)
+ }
+ fmt.Fprint(b, ",\n")
+ }
+ fmt.Fprintf(b, "%v}", indent)
+}
+
func writeGoplsSettingsSection(b *bytes.Buffer, goplsProperty Property) {
desc := goplsProperty.MarkdownDescription
b.WriteString(desc)
@@ -232,71 +260,57 @@
sort.Strings(names)
for _, name := range names {
- p, ok := properties[name].(map[string]interface{})
+ pdata, ok := properties[name].(map[string]interface{})
if !ok {
- b.WriteString(fmt.Sprintf("### `%s`\n", name))
+ fmt.Fprintf(b, "### `%s`\n", name)
continue
}
-
- desc := ""
- if d := p["description"]; d != nil {
- desc = fmt.Sprintf("%v", d)
- }
- if d := p["markdownDescription"]; d != nil {
- desc = fmt.Sprintf("%v", d)
- }
- deprecation := ""
- if d := p["deprecationMessage"]; d != nil {
- deprecation = fmt.Sprintf("%v", d)
- }
- if d := p["markdownDeprecationMessage"]; d != nil {
- deprecation = fmt.Sprintf("%v", d)
- }
- if deprecation != "" {
- name += " (deprecated)"
- desc = deprecation + "\n" + desc
- }
- b.WriteString(fmt.Sprintf("### `%s`\n%s", name, desc))
-
- switch p["type"] {
- case "object":
- x, ok := p["default"].(map[string]interface{})
- // do nothing if it is nil
- if ok && len(x) > 0 {
- keys := []string{}
- for k := range x {
- keys = append(keys, k)
- }
- sort.Strings(keys)
- b.WriteString(fmt.Sprintf("\nDefault:{<br/>\n"))
- for _, k := range keys {
- v := x[k]
- output := fmt.Sprintf("%v", v)
- if str, ok := v.(string); ok {
- output = fmt.Sprintf("%q", str)
- }
- // if v is an empty string, nothing gets printed
- // if v is a map/object, it is printed on one line
- // this could be improved at the cost of more code
- b.WriteString(fmt.Sprintf("%s`\"%s\": %s`,<br/>\n", indent, k, output))
- }
- b.WriteString(" }\n")
- }
-
- case "boolean", "string", "number":
- b.WriteString(fmt.Sprintf("\nDefault: `%v`", p["default"]))
- case "array":
- x, ok := p["default"].([]interface{})
- if ok && len(x) > 0 {
- b.WriteString(fmt.Sprintf("\nDefault: `%v`", p["default"]))
- }
- default:
- b.WriteString(fmt.Sprintf("\nefault: `%v`", p["default"]))
- }
+ p := mapToProperty(name, pdata)
+ writeProperty(b, "###", p)
b.WriteString("\n")
}
}
+func mapToProperty(name string, pdata map[string]interface{}) Property {
+ p := Property{name: name}
+
+ if v, ok := pdata["properties"].(map[string]interface{}); ok {
+ p.Properties = v
+ }
+ if v, ok := pdata["markdownDescription"].(string); ok {
+ p.MarkdownDescription = v
+ }
+ if v, ok := pdata["description"].(string); ok {
+ p.Description = v
+ }
+ if v, ok := pdata["markdownDeprecationMessage"].(string); ok {
+ p.MarkdownDescription = v
+ }
+ if v, ok := pdata["deprecationMessage"].(string); ok {
+ p.DeprecationMessage = v
+ }
+ if v, ok := pdata["type"].(string); ok {
+ p.Type = v
+ }
+ if v, ok := pdata["enum"].([]interface{}); ok {
+ p.Enum = v
+ }
+ if v, ok := pdata["enumDescriptions"].([]interface{}); ok {
+ for _, d := range v {
+ p.EnumDescriptions = append(p.EnumDescriptions, d.(string))
+ }
+ }
+ if v, ok := pdata["markdownEnumDescriptions"].([]interface{}); ok {
+ for _, d := range v {
+ p.MarkdownEnumDescriptions = append(p.MarkdownEnumDescriptions, d.(string))
+ }
+ }
+ if v, ok := pdata["default"]; ok {
+ p.Default = v
+ }
+ return p
+}
+
func writeSettingsObjectProperties(b *bytes.Buffer, properties map[string]interface{}) {
if len(properties) == 0 {
return
@@ -307,37 +321,126 @@
names = append(names, name)
}
sort.Strings(names)
- b.WriteString("\n\n")
+ b.WriteString("\n")
b.WriteString("| Properties | Description |\n")
b.WriteString("| --- | --- |\n")
- for _, name := range names {
- p, ok := properties[name].(map[string]interface{})
+ ending := "\n"
+ for i, name := range names {
+ if i == len(names)-1 {
+ ending = ""
+ }
+ pdata, ok := properties[name].(map[string]interface{})
if !ok {
- b.WriteString(fmt.Sprintf("| `%s` | |\n", name))
+ fmt.Fprintf(b, "| `%s` | |%v", name, ending)
continue
}
+ p := mapToProperty(name, pdata)
- desc := ""
- if d := p["description"]; d != nil {
- desc = fmt.Sprintf("%v", d)
+ desc := p.Description
+ if p.MarkdownDescription != "" {
+ desc = p.MarkdownDescription
}
- if d := p["markdownDescription"]; d != nil {
- desc = fmt.Sprintf("%v", d)
+ deprecation := p.DeprecationMessage
+ if p.MarkdownDeprecationMessage != "" {
+ deprecation = p.MarkdownDeprecationMessage
}
- deprecation := ""
- if d := p["deprecationMessage"]; d != nil {
- deprecation = fmt.Sprintf("%v", d)
- }
- if d := p["markdownDeprecationMessage"]; d != nil {
- deprecation = fmt.Sprintf("%v", d)
- }
-
if deprecation != "" {
name += " (deprecated)"
desc = deprecation + "\n" + desc
}
- b.WriteString(fmt.Sprintf("| `%s` | %s |\n", name, desc))
+
+ if enum := enumDescriptionsSnippet(p); enum != "" {
+ desc += "\n\n" + enum
+ }
+
+ if defaults := defaultDescriptionSnippet(p); defaults != "" {
+ desc += "\n\n"
+ if p.Type == "object" {
+ desc += fmt.Sprintf("Default:\n```\n%v\n```", defaults)
+ } else {
+ desc += fmt.Sprintf("Default: `%v`", defaults)
+ }
+ }
+ desc = gocommentToMarkdown(desc)
+ fmt.Fprintf(b, "| `%s` | %s |%v", name, desc, ending)
}
- b.WriteString("| | |\n")
- b.WriteString("\n")
+}
+
+// enumDescriptionsSnippet returns the snippet for the allowed values.
+func enumDescriptionsSnippet(p Property) string {
+ b := &bytes.Buffer{}
+ if len(p.Enum) == 0 {
+ return ""
+ }
+ desc := p.EnumDescriptions
+ if len(p.MarkdownEnumDescriptions) != 0 {
+ desc = p.MarkdownEnumDescriptions
+ }
+
+ hasDesc := false
+ for _, d := range desc {
+ if d != "" {
+ hasDesc = true
+ break
+ }
+ }
+ b.WriteString("Allowed Options:")
+
+ if hasDesc && len(desc) == len(p.Enum) {
+ b.WriteString("\n\n")
+ for i, e := range p.Enum {
+ fmt.Fprintf(b, "* `%v`", e)
+ if d := desc[i]; d != "" {
+ fmt.Fprintf(b, ": %v", strings.TrimRight(strings.ReplaceAll(d, "\n\n", "<br/>"), "\n"))
+ }
+ b.WriteString("\n")
+ }
+ } else {
+ for i, e := range p.Enum {
+ fmt.Fprintf(b, " `%v`", e)
+ if i < len(p.Enum)-1 {
+ b.WriteString(",")
+ }
+ }
+ }
+ return b.String()
+}
+
+// gocommentToMarkdown converts the description string generated based on go comments
+// to more markdown-friendly style.
+// - treat indented lines as pre-formatted blocks (e.g. code snippets) like in go doc
+// - replace new lines with <br/>'s, so the new lines mess up formatting when embedded in tables
+// - preserve new lines inside preformatted sections, but replace them with <br/>'s
+// - skip unneeded new lines
+func gocommentToMarkdown(s string) string {
+ lines := strings.Split(s, "\n")
+ inPre := false
+ b := &bytes.Buffer{}
+ for i, l := range lines {
+ if strings.HasPrefix(l, "\t") { // indented
+ if !inPre { // beginning of the block
+ inPre = true
+ b.WriteString("<pre>")
+ } else { // preserve new lines in pre-formatted block
+ b.WriteString("<br/>")
+ }
+ l = l[1:] // remove one leading \t, in favor of <pre></pre> formatting.
+ } else { // not indented
+ if inPre {
+ inPre = false
+ b.WriteString("</pre>")
+ }
+ }
+ if l == "" && i != len(lines)-1 {
+ b.WriteString("<br/>") // add a new line.
+ } else {
+ b.WriteString(l) // just print l, no new line.
+ }
+ if i != len(lines)-1 {
+ if !inPre {
+ b.WriteString(" ")
+ }
+ }
+ }
+ return b.String()
}
