.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.5.2/doc/user.md

   1 # User guide
   2
   3 ##### If you're having issues with `gopls`, please see the [troubleshooting guide](troubleshooting.md).
   4
   5 This 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
   9 The following is the list of editors with known integrations.
  10 If 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
  21 For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you.
  22
  23 If 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
  26 go 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
  31 To get a specific version of `gopls` (for example, to test a prerelease
  32 version), run:
  33
  34 ```sh
  35 go get golang.org/x/tools/gopls@vX.Y.Z
  36 ```
  37
  38 Where `vX.Y.Z` is the desired version.
  39
  40 If you see this error:
  41
  42 ```sh
  43 $ go get golang.org/x/tools/gopls@latest
  44 go: cannot use path@version syntax in GOPATH mode
  45 ```
  46
  47 then run
  48
  49 ```sh
  50 GO111MODULE=on go get golang.org/x/tools/gopls@latest
  51 ```
  52
  53 ### Unstable versions
  54
  55 `go get` doesn't honor the `replace` directive in the `go.mod` of
  56 `gopls` when you are outside of the `gopls` module, so a simple `go get`
  57 with `@master` could fail.  To actually update your `gopls` to the
  58 latest **unstable** version, use:
  59
  60 ```sh
  61 go get golang.org/x/tools/gopls@master golang.org/x/tools@master
  62 ```
  63
  64 In general, you should use `@latest` instead, to prevent frequent
  65 breakages.
  66
  67 ### Supported Go versions
  68
  69 `gopls` follows the
  70 [Go Release Policy](https://golang.org/doc/devel/release.html#policy),
  71 meaning that it officially supports the last 2 major Go releases. We run CI to
  72 verify that the `gopls` tests pass for the last 4 major Go releases, but do not
  73 prioritize issues only affecting legacy Go release (3 or 4 releases ago).
  74
  75 ## Configurations
  76
  77 ### Environment variables
  78
  79 These 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`.
  80
  81 Configuring your environment correctly is important, as `gopls` relies on the `go` command.
  82
  83 ### Command line flags
  84
  85 See the [command line page](command-line.md) for more information about the flags you might specify.
  86 All 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.
  87
  88 ### Editor settings
  89
  90 For 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.
  91
  92 #### The set of workspace folders
  93
  94 This 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.
  95
  96 If you are using modules there should be one of these per go.mod that you are working on.
  97 If you do not open the right folders, very little will work. **This is the most common misconfiguration of `gopls` that we see**.
  98
  99 #### Global configuration
 100
 101 There 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.
 102
 103 In VSCode, this would be a section in your settings file that might look like this:
 104
 105 ```json5
 106   "gopls": {
 107     "usePlaceholders": true,
 108     "completeUnimported": true
 109   },
 110 ```
 111
 112 See [Settings](settings.md) for more information about the available configurations.
 113
 114 #### Workspace folder configuration
 115
 116 This 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.
 117
 118 ## Special Features
 119
 120 ### Symbol Queries
 121
 122 Gopls supports some extended syntax for `workspace/symbol` requests, when using
 123 the `fuzzy` symbol matcher (the default). Inspired by the popular fuzzy matcher
 124 [FZF](https://github.com/junegunn/fzf), the following special characters are
 125 supported within symbol queries:
 126
 127 | Character | Usage     | Match        |
 128 | --------- | --------- | ------------ |
 129 | `'`       | `'abc`    | exact        |
 130 | `^`       | `^printf` | exact prefix |
 131 | `$`       | `printf$` | exact suffix |
 132
 133 ### Working on the Go source distribution
 134
 135 If you are working on the [Go project](https://go.googlesource.com/go) itself, your `go` command will have to correspond to the version of the source you are working on. That is, if you have downloaded the code to `$HOME/go`, your `go` command should be the `$HOME/go/bin/go` executable that you built with `make.bash` or equivalent.
 136
 137 You 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`:
 138
 139 ```json5
 140 {
 141
 142     "go.alternateTools": {
 143         "go": "$HOME/bin/go"
 144     }
 145 }
 146 ```
 147
 148 ## Command line support
 149
 150 Much of the functionality of `gopls` is available through a command line interface.
 151
 152 There 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.
 153
 154 It 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.
 155
 156 For more information, see the `gopls` [command line page](command-line.md).