1# User guide
2
3##### If you're having issues with `gopls`, please see the [troubleshooting guide](troubleshooting.md).
4
5This document focuses on VSCode, as at the time of writing, VSCode is the most popular Go editor. However, most of the features described here work in any editor. The settings should be easy to translate to those of another editor's LSP client. The differences will be in the place where you define the settings and the syntax with which you declare them.
6
7## Editors
8
9The following is the list of editors with known integrations.
10If you use `gopls` with an editor that is not on this list, please let us know by [filing an issue](#new-issue) or [modifying this documentation](#contribute).
11
12* [VSCode](vscode.md)
13* [Vim / Neovim](vim.md)
14* [Emacs](emacs.md)
15* [Acme](acme.md)
16* [Sublime Text](subl.md)
17* [Atom](atom.md)
18
19## Installation
20
21For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you.
22
23If 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
24
25```sh
26go get golang.org/x/tools/gopls@latest
27```
28
29**Do not** use the `-u` flag, as it will update your dependencies to incompatible versions.
30
31If you see this error:
32
33```sh
34$ go get golang.org/x/tools/gopls@latest
35go: cannot use path@version syntax in GOPATH mode
36```
37then run
38```sh
39GO111MODULE=on go get golang.org/x/tools/gopls@latest
40```
41
42### Unstable versions
43
44`go get` doesn't honor the `replace` directive in the `go.mod` of
45`gopls` when you are outside of the `gopls` module, so a simple `go get`
46with `@master` could fail.  To actually update your `gopls` to the
47latest **unstable** version, use:
48
49```sh
50$ go get golang.org/x/tools/gopls@master golang.org/x/tools@master
51```
52
53In general, you should use `@latest` instead, to prevent frequent
54breakages.
55
56## Configurations
57
58### Environment variables
59
60These are often inherited from the editor that launches `gopls`, and sometimes the editor has a way to add or replace values before launching. For example, VSCode allows you to configure `go.toolsEnvVars`.
61
62Configuring your environment correctly is important, as `gopls` relies on the `go` command.
63
64### Command line flags
65
66See the [command line page](command-line.md) for more information about the flags you might specify.
67All editors support some way of adding flags to `gopls`, for the most part you should not need to do this unless you have very unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps) `gopls` behavior.
68
69### Editor settings
70
71For the most part these will be settings that control how the editor interacts with or uses the results of `gopls`, not modifications to `gopls` itself. This means they are not standardized across editors, and you will have to look at the specific instructions for your editor integration to change them.
72
73#### The set of workspace folders
74
75This is one of the most important pieces of configuration. It is the set of folders that gopls considers to be "roots" that it should consider files to be a part of.
76
77If you are using modules there should be one of these per go.mod that you are working on.
78If you do not open the right folders, very little will work. **This is the most common misconfiguration of `gopls` that we see**.
79
80#### Global configuration
81
82There should be a way of declaring global settings for `gopls` inside the editor. The settings block will be called `"gopls"` and contains a collection of controls for `gopls` that the editor is not expected to understand or control.
83
84In VSCode, this would be a section in your settings file that might look like this:
85
86```json5
87  "gopls": {
88    "usePlaceholders": true,
89    "completeUnimported": true
90  },
91```
92
93See [Settings](settings.md) for more information about the available configurations.
94
95#### Workspace folder configuration
96
97This contains exactly the same set of values that are in the global configuration, but it is fetched for every workspace folder separately. The editor can choose to respond with different values per-folder.
98
99## Command line support
100
101Much of the functionality of `gopls` is available through a command line interface.
102
103There are two main reasons for this. The first is that we do not want users to rely on separate command line tools when they wish to do some task outside of an editor. The second is that the CLI assists in debugging. It is easier to reproduce behavior via single command.
104
105It is not a goal of `gopls` to be a high performance command line tool. Its command line is intended for single file/package user interaction speeds, not bulk processing.
106
107For more information, see the `gopls` [command line page](command-line.md).
108