1# User guide 2 3**If you're having issues with `gopls`, please see the 4[troubleshooting guide](troubleshooting.md).** 5 6## Editors 7 8The following is the list of editors with known integrations for `gopls`. 9 10* [VSCode](vscode.md) 11* [Vim / Neovim](vim.md) 12* [Emacs](emacs.md) 13* [Acme](acme.md) 14* [Sublime Text](subl.md) 15* [Atom](atom.md) 16 17If you use `gopls` with an editor that is not on this list, please let us know 18by [filing an issue](#new-issue) or [modifying this documentation](contributing.md). 19 20## Overview 21 22* [Installation](#installation) 23* [Configuration](#configuration) 24 25Learn more at the following pages: 26 27* [Features](features.md) 28* [Command-line](command-line.md) 29 30## Installation 31 32For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you. 33 34If you do want to get the latest stable version of `gopls`, change to any directory that is both outside of your `GOPATH` and outside of a module (a temp directory is fine), and run 35 36```sh 37go get golang.org/x/tools/gopls@latest 38``` 39 40**Do not** use the `-u` flag, as it will update your dependencies to incompatible versions. 41 42To get a specific version of `gopls` (for example, to test a prerelease 43version), run: 44 45```sh 46go get golang.org/x/tools/gopls@vX.Y.Z 47``` 48 49Where `vX.Y.Z` is the desired version. 50 51If you see this error: 52 53```sh 54$ go get golang.org/x/tools/gopls@latest 55go: cannot use path@version syntax in GOPATH mode 56``` 57 58then run 59 60```sh 61GO111MODULE=on go get golang.org/x/tools/gopls@latest 62``` 63 64### Unstable versions 65 66`go get` doesn't honor the `replace` directive in the `go.mod` of 67`gopls` when you are outside of the `gopls` module, so a simple `go get` 68with `@master` could fail. To actually update your `gopls` to the 69latest **unstable** version, use: 70 71```sh 72go get golang.org/x/tools/gopls@master golang.org/x/tools@master 73``` 74 75In general, you should use `@latest` instead, to prevent frequent 76breakages. 77 78### Supported Go versions 79 80`gopls` follows the 81[Go Release Policy](https://golang.org/doc/devel/release.html#policy), 82meaning that it officially supports the last 2 major Go releases. We run CI to 83verify that the `gopls` tests pass for the last 4 major Go releases, but do not 84prioritize issues only affecting legacy Go release (3 or 4 releases ago). 85 86## Configuration 87 88### Environment variables 89 90These are often inherited from the editor that launches `gopls`, and sometimes 91the editor has a way to add or replace values before launching. For example, 92VSCode allows you to configure `go.toolsEnvVars`. 93 94Configuring your environment correctly is important, as `gopls` relies on the 95`go` command. 96 97### Command-line flags 98 99See the [command-line page](command-line.md) for more information about the 100flags you might specify. All editors support some way of adding flags to 101`gopls`, for the most part you should not need to do this unless you have very 102unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps) 103`gopls` behavior. 104 105### Editor settings 106 107For the most part these will be settings that control how the editor interacts 108with or uses the results of `gopls`, not modifications to `gopls` itself. This 109means they are not standardized across editors, and you will have to look at 110the specific instructions for your editor integration to change them. 111 112#### The set of workspace folders 113 114This is one of the most important pieces of configuration. It is the set of 115folders that gopls considers to be "roots" that it should consider files to 116be a part of. 117 118If you are using modules there should be one of these per go.mod that you 119are working on. If you do not open the right folders, very little will work. 120**This is the most common misconfiguration of `gopls` that we see**. 121 122#### Global configuration 123 124There should be a way of declaring global settings for `gopls` inside the 125editor. The settings block will be called `"gopls"` and contains a collection 126of controls for `gopls` that the editor is not expected to understand or 127control. 128 129In VSCode, this would be a section in your settings file that might look like 130this: 131 132```json5 133 "gopls": { 134 "usePlaceholders": true, 135 "completeUnimported": true 136 }, 137``` 138 139See [Settings](settings.md) for more information about the available 140configurations. 141 142#### Workspace folder configuration 143 144This contains exactly the same set of values that are in the global 145configuration, but it is fetched for every workspace folder separately. 146The editor can choose to respond with different values per-folder. 147 148### Working on the Go source distribution 149 150If you are working on the [Go project](https://go.googlesource.com/go) itself, 151your `go` command will have to correspond to the version of the source you are 152working on. That is, if you have downloaded the code to `$HOME/go`, your `go` 153command should be the `$HOME/go/bin/go` executable that you built with 154`make.bash` or equivalent. 155 156You can achieve this by adding the right version of `go` to your `PATH` (`export PATH=$HOME/go/bin:$PATH` on Unix systems) or by configuring your editor. In VS Code, you can use the `go.alternateTools` setting to point to the correct version of `go`: 157 158```json5 159{ 160 161 "go.alternateTools": { 162 "go": "$HOME/bin/go" 163 } 164} 165``` 166