golang.org/x/tools/gopls@v0.15.3/doc/workspace.md (about)

     1  # Setting up your workspace
     2  
     3  `gopls` supports both Go module and GOPATH modes. However, it needs a defined
     4  scope in which language features like references, rename, and implementation
     5  should operate.
     6  
     7  The following options are available for configuring this scope:
     8  
     9  ## Module mode
    10  
    11  ### One module
    12  
    13  If you are working with a single module, you can open the module root (the
    14  directory containing the `go.mod` file), a subdirectory within the module,
    15  or a parent directory containing the module.
    16  
    17  **Note**: If you open a parent directory containing a module, it must **only**
    18  contain that single module. Otherwise, you are working with multiple modules.
    19  
    20  ### Multiple modules
    21  
    22  Gopls has several alternatives for working on multiple modules simultaneously,
    23  described below. Starting with Go 1.18, Go workspaces are the preferred solution.
    24  
    25  #### Go workspaces (Go 1.18+)
    26  
    27  Starting with Go 1.18, the `go` command has native support for multi-module
    28  workspaces, via [`go.work`](https://go.dev/ref/mod#workspaces) files. These
    29  files are recognized by gopls starting with `gopls@v0.8.0`.
    30  
    31  The easiest way to work on multiple modules in Go 1.18 and later is therefore
    32  to create a `go.work` file containing the modules you wish to work on, and set
    33  your workspace root to the directory containing the `go.work` file.
    34  
    35  For example, suppose this repo is checked out into the `$WORK/tools` directory.
    36  We can work on both `golang.org/x/tools` and `golang.org/x/tools/gopls`
    37  simultaneously by creating a `go.work` file using `go work init`, followed by
    38  `go work use MODULE_DIRECTORIES...` to add directories containing `go.mod` files to the
    39  workspace:
    40  
    41  ```sh
    42  cd $WORK
    43  go work init
    44  go work use ./tools/ ./tools/gopls/
    45  ```
    46  
    47  ...followed by opening the `$WORK` directory in our editor.
    48  
    49  #### DEPRECATED: Experimental workspace module (Go 1.17 and earlier)
    50  
    51  **This feature is deprecated and will be removed in future versions of gopls.
    52  Please see [issue #52897](https://go.dev/issue/52897) for additional
    53  information.**
    54  
    55  With earlier versions of Go, `gopls` can simulate multi-module workspaces by
    56  creating a synthetic module requiring the modules in the workspace root.
    57  See [the design document](https://github.com/golang/proposal/blob/master/design/37720-gopls-workspaces.md)
    58  for more information.
    59  
    60  This feature is experimental, and will eventually be removed once `go.work`
    61  files are accepted by all supported Go versions.
    62  
    63  You can enable this feature by configuring the
    64  [experimentalWorkspaceModule](settings.md#experimentalworkspacemodule-bool)
    65  setting.
    66  
    67  #### Multiple workspace folders
    68  
    69  If neither of the above solutions work, and your editor allows configuring the
    70  set of
    71  ["workspace folders"](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#workspaceFolder)
    72  used during your LSP session, you can still work on multiple modules by adding
    73  a workspace folder at each module root (the locations of `go.mod` files). This
    74  means that each module has its own scope, and features will not work across
    75  modules. 
    76  
    77  In VS Code, you can create a workspace folder by setting up a
    78  [multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
    79  View the [documentation for your editor plugin](../README.md#editor) to learn how to
    80  configure a workspace folder in your editor.
    81  
    82  ### GOPATH mode
    83  
    84  When opening a directory within your GOPATH, the workspace scope will be just
    85  that directory.
    86  
    87  ### At your own risk
    88  
    89  Some users or companies may have projects that encompass one `$GOPATH`. If you
    90  open your entire `$GOPATH` or `$GOPATH/src` folder, the workspace scope will be
    91  your entire `GOPATH`. If your GOPATH is large, `gopls` to be very slow to start
    92  because it will try to find all of the Go files in the directory you have
    93  opened. It will then load all of the files it has found.
    94  
    95  To work around this case, you can create a new `$GOPATH` that contains only the
    96  packages you want to work on.
    97  
    98  ---
    99  
   100  If you have additional use cases that are not mentioned above, please
   101  [file a new issue](https://github.com/golang/go/issues/new).