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