2534 lines
94 KiB
Text
2534 lines
94 KiB
Text
*vim-go.txt* Go development plugin
|
||
*vim-go*
|
||
|
||
==============================================================================
|
||
# #
|
||
# ## ## #### ## ## ###### ####### #
|
||
# ## ## ## ### ### ## ## ## ## #
|
||
# ## ## ## #### #### ## ## ## #
|
||
# ## ## ## ## ### ## ####### ## #### ## ## #
|
||
# ## ## ## ## ## ## ## ## ## #
|
||
# ## ## ## ## ## ## ## ## ## #
|
||
# ### #### ## ## ###### ####### #
|
||
# #
|
||
==============================================================================
|
||
CONTENTS *go-contents*
|
||
|
||
1. Intro........................................|go-intro|
|
||
2. Install......................................|go-install|
|
||
3. Commands.....................................|go-commands|
|
||
4. Mappings.....................................|go-mappings|
|
||
5. Text Objects.................................|go-text-objects|
|
||
6. Functions....................................|go-functions|
|
||
7. Settings.....................................|go-settings|
|
||
8. Syntax highlighting..........................|go-syntax|
|
||
9. Debugger.....................................|go-debug|
|
||
10. FAQ/Troubleshooting..........................|go-troubleshooting|
|
||
11. Development..................................|go-development|
|
||
12. Donation.....................................|go-donation|
|
||
13. Credits......................................|go-credits|
|
||
|
||
==============================================================================
|
||
INTRO *go-intro*
|
||
|
||
Go (golang) support for Vim. vim-go comes with sensible predefined settings
|
||
(e.g. automatic `gofmt` on save), has code completion, snippet support,
|
||
improved syntax highlighting, go toolchain commands, etc. It is highly
|
||
customizable, and individual features can be toggled easily. vim-go leverages
|
||
a number of tools developed by the Go community to provide a seamless Vim
|
||
experience.
|
||
|
||
* Compile your package with |:GoBuild|, install it with |:GoInstall| or
|
||
test it with |:GoTest|. Run a single test with |:GoTestFunc|).
|
||
* Quickly execute your current file(s) with |:GoRun|.
|
||
* Improved syntax highlighting and folding.
|
||
* Debug programs with integrated `delve` support with |:GoDebugStart|.
|
||
* Code completion support via `gocode` and `gopls`.
|
||
* `gofmt` or `goimports` on save keeps the cursor position and undo history.
|
||
* Go to symbol/declaration with |:GoDef|.
|
||
* Look up documentation with |:GoDoc| or |:GoDocBrowser|.
|
||
* Easily import packages via |:GoImport|, remove them via |:GoDrop|.
|
||
* Precise type-safe renaming of identifiers with |:GoRename|.
|
||
* See which code is covered by tests with |:GoCoverage|.
|
||
* Add or remove tags on struct fields with |:GoAddTags| and |:GoRemoveTags|.
|
||
* Call `golangci-lint` with |:GoMetaLinter| to invoke all possible linters
|
||
(`golint`, `vet`, `errcheck`, `deadcode`, etc.) and put the result in the
|
||
quickfix or location list.
|
||
* Lint your code with |:GoLint|, run your code through |:GoVet| to catch
|
||
static errors, or make sure errors are checked with |:GoErrCheck|.
|
||
* Advanced source analysis tools utilizing `guru`, such as |:GoImplements|,
|
||
|:GoCallees|, and |:GoReferrers|.
|
||
* Automatic `GOPATH` detection which works with `gb` and `godep`. Change or
|
||
display `GOPATH` with |:GoPath|.
|
||
* Integrated and improved snippets, supporting `ultisnips`, `neosnippet`,
|
||
and `vim-minisnip`.
|
||
* Share your current code to play.golang.org with |:GoPlay|.
|
||
* On-the-fly information about the word under the cursor. Plug it into your
|
||
custom Vim function.
|
||
* Text objects such as "a function" (|go-af|) or "inner function" (|go-if|).
|
||
* Most commands are run asynchronous in Neovim and Vim 8. Fully async
|
||
building and testing.
|
||
* Integrated with the Neovim terminal, launch |:GoRun| and other Go commands
|
||
in a terminal buffer.
|
||
* Switch between `file.go` and `file_test.go` code with |:GoAlternate|.
|
||
* Supports integration with the Tagbar and ctrlp.vim plugins.
|
||
* ...and more...
|
||
|
||
==============================================================================
|
||
INSTALL *go-install*
|
||
|
||
vim-go requires at least Vim 8.0.1453 or Neovim 0.3.2. On macOS, if you are
|
||
still using your system version of vim, you can use homebrew to keep your
|
||
version of Vim up-to-date with the following terminal command:
|
||
>
|
||
brew install vim
|
||
|
||
The latest stable release, https://github.com/fatih/vim-go/releases/latest, is
|
||
the recommended version to use. If you choose to use the master branch
|
||
instead, please do so with caution; it is a _development_ branch.
|
||
|
||
vim-go follows the standard runtime path structure and should work with any of
|
||
the major plugin managers.
|
||
|
||
For Pathogen or Vim |packages|, just clone the repo. For other plugin managers
|
||
you may also need to add the lines to your vimrc to execute the plugin
|
||
manager's install command.
|
||
|
||
* Vim 8 |packages| >
|
||
|
||
git clone https://github.com/fatih/vim-go.git \
|
||
~/.vim/pack/plugins/start/vim-go
|
||
<
|
||
* https://github.com/tpope/vim-pathogen >
|
||
|
||
git clone https://github.com/fatih/vim-go.git ~/.vim/bundle/vim-go
|
||
<
|
||
* https://github.com/junegunn/vim-plug >
|
||
|
||
Plug 'fatih/vim-go', { 'do': ':GoUpdateBinaries' }
|
||
<
|
||
* https://github.com/Shougo/neobundle.vim >
|
||
|
||
NeoBundle 'fatih/vim-go'
|
||
<
|
||
* https://github.com/gmarik/vundle >
|
||
|
||
Plugin 'fatih/vim-go'
|
||
<
|
||
* Manual (not recommended) >
|
||
|
||
Copy all of the files into your `~/.vim` directory
|
||
<
|
||
|
||
You will also need to install all the necessary binaries. vim-go makes it easy
|
||
to install all of them by providing a command, |:GoInstallBinaries|, to
|
||
`go get` all the required binaries. The binaries will be installed to $GOBIN
|
||
or $GOPATH/bin (default: $HOME/go/bin). It requires `git`.
|
||
|
||
Depending on your installation method, you may have to generate the plugin's
|
||
|:helptags| manually (e.g. `:helptags ALL`).
|
||
|
||
Code completion is enabled by default via 'omnifunc', which you can trigger
|
||
with |i_CTRL-X_CTRL-O| (`<C-x><C-o>`).
|
||
|
||
Supported Go plugins~ *vim-go-plugins*
|
||
|
||
The following plugins are supported for use with vim-go:
|
||
|
||
* Real-time completion (Vim):
|
||
https://github.com/Shougo/neocomplete.vim
|
||
|
||
* Real-time completion (Neovim and Vim 8):
|
||
https://github.com/Shougo/deoplete.nvim
|
||
|
||
Add the following line to your vimrc. This instructs deoplete to use omni
|
||
completion for Go files.
|
||
|
||
call deoplete#custom#option('omni_patterns', { 'go': '[^. *\t]\.\w*' })
|
||
|
||
* Display source code navigation in a sidebar:
|
||
https://github.com/majutsushi/tagbar
|
||
|
||
* Snippets:
|
||
https://github.com/Shougo/neosnippet.vim or
|
||
https://github.com/SirVer/ultisnips or
|
||
https://github.com/joereynolds/vim-minisnip
|
||
|
||
* Interactive |:GoDecls| and |:GoDeclsDir|:
|
||
https://github.com/ctrlpvim/ctrlp.vim or
|
||
https://github.com/junegunn/fzf.vim or
|
||
https://github.com/Shougo/unite.vim or
|
||
https://github.com/Shougo/denite.nvim
|
||
|
||
==============================================================================
|
||
COMMANDS *go-commands*
|
||
|
||
*:GoReportGitHubIssue*
|
||
:GoReportGitHubIssue
|
||
GoReportGitHubIssue opens the default browser and starts a new bug report
|
||
with useful system information.
|
||
|
||
*:GoPath*
|
||
:GoPath [path]
|
||
|
||
GoPath sets and overrides GOPATH with the given {path}. If no {path} is
|
||
given it shows the current GOPATH. If `""` is given as path, it clears
|
||
current `GOPATH` which was set with |:GoPath| and restores `GOPATH` back
|
||
to the initial value which was sourced when Vim was started.
|
||
|
||
*:GoImport*
|
||
:GoImport[!] [path]
|
||
|
||
Import ensures that the provided package {path} is imported in the current
|
||
Go buffer, using proper style and ordering. If {path} is already being
|
||
imported, an error will be displayed and the buffer will be untouched.
|
||
|
||
If [!] is given it will download the package with `go get`
|
||
|
||
*:GoImportAs*
|
||
:GoImportAs [localname] [path]
|
||
|
||
Same as Import, but uses a custom local name for the package.
|
||
|
||
*:GoDrop*
|
||
:GoDrop [path]
|
||
|
||
Remove the import line for the provided package {path}, if present in the
|
||
current Go buffer. If {path} is not being imported, an error will be
|
||
displayed and the buffer will be untouched.
|
||
|
||
*:GoLint*
|
||
:GoLint! [packages]
|
||
|
||
Run golint for the directory under your current file, or for the given
|
||
packages.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoDoc*
|
||
:GoDoc [word]
|
||
|
||
Open the relevant GoDoc in split window for either the word[s] passed to
|
||
the command or by default, the word under the cursor.
|
||
|
||
*:GoDocBrowser*
|
||
:GoDocBrowser [word]
|
||
|
||
Open the relevant GoDoc in browser for either the word[s] passed to the
|
||
command or by default, the word under the cursor. By default it opens the
|
||
documentation in 'https://godoc.org'. To change it see |'g:go_doc_url'|.
|
||
|
||
*:GoFmt*
|
||
:GoFmt
|
||
|
||
Filter the current Go buffer through gofmt. It tries to preserve cursor
|
||
position and avoids replacing the buffer with stderr output.
|
||
|
||
*:GoImports*
|
||
:GoImports
|
||
|
||
Filter the current Go buffer through goimports (needs to be installed).
|
||
`goimports` automatically discards/add import path based on the code. Like
|
||
|:GoFmt|, It tries to preserve cursor position and avoids replacing the
|
||
buffer with stderr output.
|
||
|
||
*:GoPlay*
|
||
:[range]GoPlay
|
||
|
||
Share snippet to play.golang.org. If no [range] is given it shares
|
||
the whole file, otherwise the selected lines are shared. Snippet URL
|
||
is copied to system clipboard if Vim is compiled with 'clipboard' or
|
||
'xterm-clipboard' otherwise it's get yanked into the `""` register.
|
||
|
||
*:GoVet*
|
||
:GoVet[!] [options]
|
||
|
||
Run `go vet` for the directory under your current file. Vet examines Go
|
||
source code and reports suspicious constructs, such as Printf calls whose
|
||
arguments do not align with the format string. Vet uses heuristics that do
|
||
not guarantee all reports are genuine problems, but it can find errors not
|
||
caught by the compilers.
|
||
|
||
You may optionally pass any valid go vet flags/options.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoDef*
|
||
:GoDef
|
||
gd
|
||
CTRL-]
|
||
g<C-LeftMouse>
|
||
<C-LeftMouse>
|
||
|
||
Go to declaration/definition for the identifier under the cursor. By
|
||
default the CTRL-] shortcut, the mapping `gd` and <C-LeftMouse>,
|
||
g<LeftMouse> are enabled to invoke :GoDef for the identifier under the
|
||
cursor. See |'g:go_def_mapping_enabled'| to disable them. No explicit
|
||
arguments are supported.
|
||
|
||
vim-go also keeps a per-window location stack, roughly analogous to how
|
||
Vim's internal |tags| functionality works. This is pushed to every time a
|
||
jump is made using the GoDef functionality. In essence, this is a LIFO
|
||
list of file locations you have visited with :GoDef that is retained to
|
||
help you navigate software.
|
||
|
||
The per-window location stack is shared with |:GoDefType|.
|
||
|
||
*:GoDefType*
|
||
:GoDefType
|
||
|
||
Go to type definition for the identifier under the cursor.
|
||
|
||
The per-window location stack is shared with |:GoDef|.
|
||
*:GoDefStack*
|
||
:GoDefStack [number]
|
||
|
||
This command Jumps to a given location in the jumpstack, retaining all
|
||
other entries. Jumps to non-existent entries will print an informative
|
||
message, but are otherwise a noop.
|
||
|
||
If no argument is given, it will print out an interactive list of all
|
||
items in the stack. Its output looks like this:
|
||
|
||
1 /path/first/file.go|1187 col 16|AddThing func(t *Thing)
|
||
> 2 /path/thing/thing.go|624 col 19|String() string
|
||
3 /path/thing/thing.go|744 col 6|func Sprintln(a ...interface{}) string
|
||
|
||
This list shows the identifiers that you jumped to and the file and cursor
|
||
position before that jump. The older jumps are at the top, the newer at
|
||
the bottom.
|
||
|
||
The '>' points to the active entry. This entry and any newer entries
|
||
below it will be replaced if |:GoDef| is done from this location. The
|
||
CTRL-t and |:GoDefPop| command will jump to the position above the active
|
||
entry.
|
||
|
||
Jumps to non-existent entries will print an informative message, but are
|
||
otherwise a noop.
|
||
|
||
*:GoDefStackClear*
|
||
:GoDefStackClear
|
||
|
||
Clears the current stack list and resets it.
|
||
|
||
*:GoDefPop*
|
||
:GoDefPop [count]
|
||
CTRL-t
|
||
|
||
Navigate to the [count] earlier entry in the jump stack, retaining the
|
||
newer entries. If no argument is given, it will jump to the next most
|
||
recent entry (`:GoDefPop 1`). If [count] is greater than the number of
|
||
prior entries, an error will be printed and no jump will be performed.
|
||
|
||
If you have used :GoDefPop to jump to an earlier location, and you issue
|
||
another :GoDef command, the current entry will be replaced, and all newer
|
||
entries will be removed, effectively resuming the stack at that location.
|
||
|
||
By default [count]CTRL-t is enabled to invoke :GoDefPop. Similarly,
|
||
hitting CTRL-t without a prior count is equivalent to `:GoDefPop 1`. See
|
||
|'g:go_def_mapping_enabled'| to disable this.
|
||
|
||
*:GoRun*
|
||
:GoRun[!] [expand]
|
||
|
||
Build and run your current main package. By default all main files for the
|
||
current file is used. If an argument is passed, [expand] is used as file
|
||
selector. For example use `:GoRun %` to select the current file only.
|
||
|
||
You may optionally pass any valid go run flags/options. For a full list
|
||
please see `go help run`.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
If using neovim then `:GoRun` will run in a new terminal according to
|
||
|'g:go_term_mode'|.
|
||
|
||
*:GoBuild*
|
||
:GoBuild[!] [expand]
|
||
|
||
Build your package with `go build`. Errors are populated in the quickfix
|
||
window. It automatically builds only the files that depends on the current
|
||
file. `:GoBuild` doesn't produce a result file.
|
||
Use |:make| to create a result file.
|
||
|
||
You may optionally pass any valid go build flags/options. For a full list
|
||
please see `go help build`. Options are expanded with [expand].
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
If using neovim then this command is fully async, it does not block the
|
||
UI.
|
||
|
||
*:GoGenerate*
|
||
:GoGenerate[!] [expand]
|
||
|
||
Creates or updates your auto-generated source files by running `go
|
||
generate`.
|
||
|
||
You may optionally pass any valid go generate flags/options. For a full
|
||
list please see `go help generate`. Options are expanded with [expand].
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoInfo*
|
||
:GoInfo
|
||
Show type information about the identifier under the cursor. For example
|
||
putting it above a function call is going to show the full function
|
||
signature. By default it uses `gopls` to get the type informations. To
|
||
change the underlying tool from `gopls` to another tool, see
|
||
|'g:go_info_mode'|.
|
||
|
||
|
||
*:GoInstall*
|
||
:GoInstall[!] [options]
|
||
|
||
Install your package with `go install`.
|
||
|
||
You may optionally pass any valid go install flags/options. For a full
|
||
list please see `go help install`.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoTest*
|
||
:GoTest[!] [expand]
|
||
|
||
Run the tests on your _test.go files via in your current directory. Errors
|
||
are populated in the quickfix window. If an argument is passed, [expand]
|
||
is used as file selector (useful for cases like `:GoTest ./...`).
|
||
|
||
You may optionally pass any valid go test flags/options. For a full list
|
||
please see `go help test`.
|
||
|
||
GoTest timesout automatically after 10 seconds. To customize the timeout
|
||
use |'g:go_test_timeout'|. This feature is disabled if any arguments are
|
||
passed to the `:GoTest` command.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
If using neovim `:GoTest` will run in a new terminal or run asynchronously
|
||
in the background according to |'g:go_term_enabled'|. You can set the mode
|
||
of the new terminal with |'g:go_term_mode'|.
|
||
|
||
*:GoTestFunc*
|
||
:GoTestFunc[!] [expand]
|
||
|
||
Runs :GoTest, but only on the single test function immediate to your
|
||
cursor using 'go test's '-run' flag.
|
||
|
||
Lookup is done starting at the cursor (including that line) moving up till
|
||
a matching `func Test` pattern is found or top of file is reached. Search
|
||
will not wrap around when at the top of the file.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
If using neovim `:GoTestFunc` will run in a new terminal or run
|
||
asynchronously in the background according to |'g:go_term_enabled'|. You
|
||
can set the mode of the new terminal with |'g:go_term_mode'|.
|
||
|
||
*:GoTestCompile*
|
||
:GoTestCompile[!] [expand]
|
||
|
||
Compile your _test.go files via in your current directory. Errors are
|
||
populated in the quickfix window. If an argument is passed, [expand] is
|
||
used as file selector (useful for cases like `:GoTest ./...`). Useful to
|
||
not run the tests and capture/fix errors before running the tests or to
|
||
create test binary.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
If using neovim `:GoTestCompile` will run in a new terminal or run
|
||
asynchronously in the background according to |'g:go_term_enabled'|. You
|
||
can set the mode of the new terminal with |'g:go_term_mode'|.
|
||
|
||
*:GoCoverage*
|
||
:GoCoverage[!] [options]
|
||
|
||
Create a coverage profile and annotates the current file's source code. If
|
||
called again it rerurns the tests.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoCoverageToggle*
|
||
:GoCoverageToggle[!] [options]
|
||
|
||
Create a coverage profile and annotates the current file's source code. If
|
||
called again clears the annotation (works as a toggle).
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoCoverageClear*
|
||
:GoCoverageClear [options]
|
||
|
||
Clears the coverage annotation.
|
||
|
||
|
||
*:GoCoverageBrowser*
|
||
:GoCoverageBrowser[!] [options]
|
||
|
||
Create a coverage profile and open a browser to display the annotated
|
||
source code of the current package.
|
||
|
||
You may optionally pass any valid go test flags/options, such as
|
||
`-covermode set,count,atomic`. For a full list please see `go help test`.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoErrCheck*
|
||
:GoErrCheck! [options]
|
||
|
||
Check for unchecked errors in you current package. Errors are populated in
|
||
the quickfix window.
|
||
|
||
You may optionally pass any valid errcheck flags/options. See
|
||
`errcheck -h` for a full list.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoFiles*
|
||
:GoFiles [source_files]
|
||
|
||
Show source files for the current package. The [source_files] specifies
|
||
which file types to list. See the "// Source files" section of
|
||
`go list -h` for possible values; multiple values are accepted.
|
||
Command-line completion also works for this command.
|
||
The default is to use `GoFiles` if no arguments are given.
|
||
|
||
*:GoDeps*
|
||
:GoDeps
|
||
|
||
Show dependencies for the current package.
|
||
|
||
*:GoInstallBinaries*
|
||
:GoInstallBinaries [binaries]
|
||
|
||
Download and install all necessary Go tool binaries such as `godef`,
|
||
`goimports`, `gocode`, etc. under |'g:go_bin_path'|. If [binaries] is
|
||
supplied, then only the specified binaries will be installed. The default
|
||
is to install everything.
|
||
|
||
Set |'g:go_get_update'| to disable updating dependencies.
|
||
|
||
*:GoUpdateBinaries*
|
||
:GoUpdateBinaries [binaries]
|
||
|
||
Download and update previously installed Go tool binaries such as `godef`,
|
||
`goimports`, `gocode`, etc. under |'g:go_bin_path'|. If [binaries] is
|
||
supplied, then only the specified binaries will be updated. The default is
|
||
to update everything.
|
||
|
||
Set |'g:go_get_update'| to disable updating dependencies.
|
||
|
||
*:GoImplements*
|
||
:GoImplements
|
||
|
||
Show "implements" relation for a selected package. A list of interfaces
|
||
for the type that implements an interface under the cursor (or selected
|
||
package) is shown in a location list.
|
||
*:GoRename*
|
||
:GoRename[!] [to]
|
||
|
||
Rename the identifier under the cursor to the desired new name. If no
|
||
argument is given a prompt will ask for the desired identifier.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
|
||
*:GoGuruScope*
|
||
:GoGuruScope [pattern] ...
|
||
|
||
Changes the custom |'g:go_guru_scope'| setting and overrides it with the
|
||
given package patterns. The custom scope is cleared (unset) if `""` is
|
||
given as the only path. If no arguments is given it prints the current
|
||
custom scope. Example patterns are:
|
||
>
|
||
golang.org/x/tools/cmd/guru # a single package
|
||
golang.org/x/tools/... # all packages beneath dir
|
||
... # the entire workspace.
|
||
<
|
||
Example usage, the following sets the scope to a `github.com/fatih/color`
|
||
and to all packages under `golang.org/x/tools/`:
|
||
>
|
||
:GoGuruScope github.com/fatih/color golang.org/x/tools/...
|
||
<
|
||
The following sets it to the entire workspace:
|
||
>
|
||
:GoGuruScope ...
|
||
<
|
||
Under the hood, the patterns are all joined to a comma-separated list and
|
||
passed to `guru`'s `-scope` flag.
|
||
|
||
Also see |go-guru-scope|.
|
||
|
||
*:GoCallees*
|
||
:GoCallees
|
||
|
||
Show "callees" relation for a selected package. A list of possible call
|
||
targets for the type under the cursor (or selected package) is shown in a
|
||
location list.
|
||
|
||
*:GoCallers*
|
||
:GoCallers
|
||
|
||
Show "callers" relation for a selected function. A list of possible
|
||
callers for the selected function under the cursor is shown in a location
|
||
list.
|
||
|
||
*:GoDescribe*
|
||
:GoDescribe
|
||
|
||
Shows various properties of the selected syntax: its syntactic kind, its
|
||
type (for an expression), its value (for a constant expression), its size,
|
||
alignment, method set and interfaces (for a type), its declaration (for an
|
||
identifier), etc. Almost any piece of syntax may be described, and the
|
||
guru will try to print all the useful information it can.
|
||
|
||
*:GoCallstack*
|
||
:GoCallstack
|
||
|
||
Shows "callstack" relation for the selected function. An arbitrary path
|
||
from the root of the callgraph to the selected function is shown in a
|
||
location list. This may be useful to understand how the function is
|
||
reached in a given program.
|
||
|
||
*:GoFreevars*
|
||
:GoFreevars
|
||
|
||
Enumerates the free variables of the selection. "Free variables" is a
|
||
technical term meaning the set of variables that are referenced but not
|
||
defined within the selection, or loosely speaking, its inputs.
|
||
|
||
This information is useful when considering whether to refactor the
|
||
selection into a function of its own, as the free variables would be the
|
||
necessary parameters of that function. It's also useful when you want to
|
||
understand what the inputs are to a complex block of code even if you
|
||
don’t plan to change it.
|
||
|
||
*:GoChannelPeers*
|
||
:GoChannelPeers
|
||
|
||
Shows the set of possible sends/receives on the channel operand of the
|
||
selected send or receive operation; the selection must be a `<-` token.
|
||
|
||
For example, visually select a channel operand in the form of:
|
||
>
|
||
done <- true
|
||
<
|
||
And call |:GoChannelPeers| on it. It will show where it was allocated, and
|
||
the sending and receiving endings.
|
||
|
||
*:GoReferrers*
|
||
:GoReferrers
|
||
|
||
The referrers query shows the set of identifiers that refer to the same
|
||
object as does the selected identifier.
|
||
|
||
*:GoSameIds*
|
||
:GoSameIds
|
||
|
||
Highlights all identifiers that are equivalent to the identifier under the
|
||
cursor.
|
||
|
||
*:GoSameIdsClear*
|
||
:GoSameIdsClear
|
||
|
||
Clears all SameIds highlights from a |:GoSameIds| call.
|
||
|
||
*:GoSameIdsToggle*
|
||
:GoSameIdsToggle
|
||
|
||
Toggle between |:GoSameIds| and |:GoSameIdsClear|.
|
||
|
||
*:GoSameIdsAutoToggle*
|
||
:GoSameIdsAutoToggle
|
||
|
||
Enables or disables automatic highlighting of |:GoSameIds| while moving
|
||
the cursor. This basically toggles the option |'g:go_auto_sameids'|
|
||
on/off.
|
||
If enabled it starts highlighting whenever your cursor is staying at the
|
||
same position for a configurable period of time (see |'g:go_updatetime'|).
|
||
If disabled it clears and stops automatic highlighting.
|
||
|
||
*:GoMetaLinter*
|
||
:GoMetaLinter! [path]
|
||
|
||
Calls the underlying `golangci-lint` tool and displays all warnings and
|
||
errors in the |quickfix| window. By default the following linters are
|
||
enabled: `vet`, `golint`, and `errcheck`. This can be changed with the
|
||
|'g:go_metalinter_enabled'| variable. To override the command completely
|
||
use the variable |'g:go_metalinter_command'|. To override the maximum
|
||
linters execution time use |'g:go_metalinter_deadline'| variable.
|
||
|
||
If [!] is not given the first error is jumped to.
|
||
|
||
*:GoBuildTags*
|
||
:GoBuildTags [tags]
|
||
|
||
Changes the build tags for various commands. If you have any file that
|
||
uses a custom build tag, such as `// +build integration` , this command
|
||
can be used to pass it to all tools that accepts tags, such as gopls,
|
||
guru, gorename, etc.
|
||
|
||
The build tags is cleared (unset) if `""` is given. If no arguments are
|
||
given it prints the current build tags.
|
||
|
||
*:AsmFmt*
|
||
:AsmFmt
|
||
|
||
Filter the current Go asm buffer through asmfmt. It tries to preserve
|
||
cursor position and avoids replacing the buffer with stderr output.
|
||
|
||
*:GoAlternate*
|
||
:GoAlternate[!]
|
||
|
||
Alternates between the implementation and test code. For example if in
|
||
main.go, switch to main_test.go. Uses the |'g:go_alternate_mode'| setting
|
||
as the command to open the file.
|
||
|
||
If [!] is given then it switches to the new file even if it does not
|
||
exist.
|
||
|
||
If you would like to override the traditional commands for alternating,
|
||
add the following to your .vimrc:
|
||
>
|
||
augroup go
|
||
autocmd!
|
||
autocmd Filetype go
|
||
\ command! -bang A call go#alternate#Switch(<bang>0, 'edit')
|
||
\| command! -bang AV call go#alternate#Switch(<bang>0, 'vsplit')
|
||
\| command! -bang AS call go#alternate#Switch(<bang>0, 'split')
|
||
augroup END
|
||
<
|
||
|
||
*:GoPointsTo*
|
||
:GoPointsTo
|
||
|
||
Show all variables to which the pointer under the cursor may point to.
|
||
|
||
*:GoWhicherrs*
|
||
:GoWhicherrs
|
||
|
||
Show the list of possible constants, global variables, and concrete types
|
||
for the error type under the cursor in a location list.
|
||
|
||
*:GoDecls*
|
||
:GoDecls [file]
|
||
|
||
Show all function and type declarations for the current file. If
|
||
[file] is non empty it parses the given file.
|
||
Requires `ctrlp.vim` or `fzf`; it will autodetect the plugin if installed,
|
||
but you can use |'g:go_decls_mode'| to force using one or the other.
|
||
By default `type` and `func` declarations are shown. This can be changed
|
||
via |'g:go_decls_includes'|. Also see |unite-decls|, |denite-decls|.
|
||
|
||
*:GoDeclsDir*
|
||
:GoDeclsDir [dir]
|
||
|
||
Show all function and type declarations for the current directory. If
|
||
[dir] is given it parses the given directory.
|
||
|
||
*unite-decls*
|
||
*denite-decls*
|
||
:Unite decls[:path]
|
||
:Denite decls[:path]
|
||
|
||
Only enabled if `unite.vim` or `denite.nvim` is installed. Show
|
||
declarations for all functions and types on the current file or directory
|
||
or for [path] if given.
|
||
|
||
Note: `denite.nvim` requires NeoVim or Vim 8 with |:python3| enabled.
|
||
>
|
||
" show declarations on the parent directory of the current file
|
||
:Unite decls
|
||
:Denite decls
|
||
|
||
" show declarations in the file.
|
||
:Unite decls:foo/bar.go
|
||
:Denite decls:foo/bar.go
|
||
|
||
" show declarations in the directory "foo".
|
||
:Unite decls:foo
|
||
:Denite decls:foo
|
||
<
|
||
*:GoImpl*
|
||
:GoImpl [receiver] [interface]
|
||
|
||
Generates method stubs for implementing an interface. If no arguments is
|
||
passed it takes the identifier under the cursor to be the receiver and
|
||
asks for the interface type to be generated. If used with arguments, the
|
||
receiver and the interface needs to be specified. Example usages:
|
||
>
|
||
:GoImpl f *Foo io.Writer
|
||
:GoImpl t Type io.ReadWriteCloser
|
||
<
|
||
*:GoAddTags*
|
||
:[range]GoAddTags [key],[option] [key1],[option] ...
|
||
|
||
Adds field tags for the fields of a struct. If called inside a struct it
|
||
automatically add field tags with the `json` key and the value
|
||
automatically generated based on the field name. An error message is given
|
||
if it's called outside a struct definition or if the file is not correctly
|
||
formatted.
|
||
|
||
If [range] is given, only the selected fields will be changed.
|
||
|
||
The default `json` can be changed by providing one or more [key]
|
||
arguments. An example of adding `xml` and `db` would be:
|
||
>
|
||
:GoAddTags xml db
|
||
<
|
||
If [option] is passed it'll either add a new tag with an option or will
|
||
modify existing tags. An example of adding `omitempty` to all `json`
|
||
fields would be:
|
||
>
|
||
:GoAddTags json,omitempty
|
||
<
|
||
You can define a constant value instead of the default field based value.
|
||
For example the following command will add ``valid:"1"`` to all fields.
|
||
>
|
||
:GoAddTags valid=1
|
||
<
|
||
*:GoRemoveTags*
|
||
:[range]GoRemoveTags [key],[option] [key1],[option1] ...
|
||
|
||
Remove field tags for the fields of a struct. If called inside a struct it
|
||
automatically remove all field tags. An error message is given if it's
|
||
called outside a struct definition or if the file is not correctly
|
||
formatted
|
||
|
||
If [range] is given, only the selected fields will be changed.
|
||
|
||
If [key] is given, it will only remove those keys. Example:
|
||
>
|
||
:GoRemoveTags json
|
||
<
|
||
If [option] is passed with a [key], it will only remove the options.
|
||
Example, this will only remove `omitempty` options from fields containing
|
||
`json`:
|
||
>
|
||
:GoRemoveTags json,omitempty
|
||
<
|
||
*:GoAutoTypeInfoToggle*
|
||
:GoAutoTypeInfoToggle
|
||
|
||
Toggles |'g:go_auto_type_info'|.
|
||
|
||
*:GoFmtAutoSaveToggle*
|
||
:GoFmtAutoSaveToggle
|
||
|
||
Toggles |'g:go_fmt_autosave'|.
|
||
|
||
*:GoModFmtAutoSaveToggle*
|
||
:GoModFmtAutoSaveToggle
|
||
|
||
Toggles |'g:go_mod_fmt_autosave'|.
|
||
|
||
*:GoAsmFmtAutoSaveToggle*
|
||
:GoAsmFmtAutoSaveToggle
|
||
|
||
Toggles |'g:go_asmfmt_autosave'|.
|
||
|
||
*:GoMetaLinterAutoSaveToggle*
|
||
:GoMetaLinterAutoSaveToggle
|
||
|
||
Toggles |'g:go_metalinter_autosave'|.
|
||
|
||
By default, `golangci-lint` messages will be shown in the |location-list|
|
||
window. The list to use can be set using |'g:go_list_type_commands'|.
|
||
|
||
*:GoTemplateAutoCreateToggle*
|
||
:GoTemplateAutoCreateToggle
|
||
|
||
Toggles |'g:go_template_autocreate'|.
|
||
|
||
*:GoKeyify*
|
||
:GoKeyify
|
||
|
||
Uses `keyify` to turn unkeyed struct literals into keyed ones.
|
||
|
||
For example:
|
||
>
|
||
Person{"John", "Smith"}
|
||
<
|
||
Becomes:
|
||
>
|
||
Person{
|
||
Name: "John",
|
||
Surname: "Smith",
|
||
}
|
||
<
|
||
*:GoFillStruct*
|
||
:GoFillStruct
|
||
|
||
Use `fillstruct` to fill a struct literal with default values. Existing
|
||
values (if any) are preserved. The cursor must be on the struct you wish
|
||
to fill.
|
||
|
||
For example:
|
||
>
|
||
addr := net.Address{Name: "Ford Prefect"}
|
||
<
|
||
Becomes:
|
||
>
|
||
addr := net.Address{
|
||
Name: "Ford Prefect",
|
||
Email: "",
|
||
}
|
||
<
|
||
|
||
*:GoIfErr*
|
||
:GoIfErr
|
||
|
||
Generate if err != nil { return ... } automatically which infer the type
|
||
of return values and the numbers.
|
||
|
||
For example:
|
||
>
|
||
func doSomething() (string, error) {
|
||
f, err := os.Open("file")
|
||
}
|
||
<
|
||
Becomes:
|
||
>
|
||
func doSomething() (string, error) {
|
||
f, err := os.Open("file")
|
||
if err != nil {
|
||
return "", err
|
||
}
|
||
}
|
||
<
|
||
*:GoModFmt*
|
||
:GoModFmt
|
||
|
||
Filter the current go.mod buffer through "go mod edit -fmt" command. It
|
||
tries to preserve cursor position and avoids replacing the buffer with
|
||
stderr output.
|
||
|
||
*:GoAddWorkspace*
|
||
:GoAddWorkspace [dir] ...
|
||
|
||
Add directories to the `gopls` workspace.
|
||
|
||
*:GoLSPDebugBrowser*
|
||
:GoLSPDebugBrowser
|
||
|
||
Open a browser to see gopls debugging information.
|
||
|
||
==============================================================================
|
||
MAPPINGS *go-mappings*
|
||
|
||
vim-go has several <Plug> keys which can be used to create custom mappings
|
||
For example, to create a mapping that calls `go run` for the current package,
|
||
create a mapping for the `(go-run)`: >
|
||
|
||
au FileType go nmap <leader>r <Plug>(go-run)
|
||
|
||
As always one is free to create more advanced mappings or functions based with
|
||
|go-commands|. For more information please check out the mappings command
|
||
documentation in the |go-commands| section. Available <Plug> keys are:
|
||
|
||
*(go-run)*
|
||
|
||
Calls `go run` for the current main package
|
||
|
||
*(go-run-tab)*
|
||
|
||
Calls `go run` for the current file in a new terminal tab
|
||
This option is neovim only.
|
||
|
||
*(go-run-split)*
|
||
|
||
Calls `go run` for the current file in a new terminal horizontal split
|
||
This option is neovim only.
|
||
|
||
*(go-run-vertical)*
|
||
|
||
Calls `go run` for the current file in a new terminal vertical split
|
||
This option is neovim only.
|
||
|
||
*(go-build)*
|
||
|
||
Calls `go build` for the current package
|
||
|
||
*(go-generate)*
|
||
|
||
Calls `go generate` for the current package
|
||
|
||
*(go-info)*
|
||
|
||
Shows type information for the word under the cursor
|
||
|
||
*(go-install)*
|
||
|
||
Calls `go install` for the current package
|
||
|
||
*(go-test)*
|
||
|
||
Calls `go test` for the current package
|
||
|
||
*(go-test-func)*
|
||
|
||
Calls `go test -run '...'` for the test function immediate to cursor
|
||
|
||
*(go-test-compile)*
|
||
|
||
Calls `go test -c` for the current package
|
||
|
||
*(go-coverage)*
|
||
|
||
Calls `go test -coverprofile-temp.out` for the current package and shows the
|
||
coverage annotation.
|
||
|
||
*(go-coverage-clear)*
|
||
|
||
Clears the coverage annotation
|
||
|
||
*(go-coverage-toggle)*
|
||
|
||
Calls `go test -coverprofile-temp.out` for the current package and shows the
|
||
coverage annotation. If run again it acts as a toggle and clears the
|
||
annotation.
|
||
|
||
*(go-imports)*
|
||
|
||
Calls `goimports` for the current package
|
||
|
||
*(go-lint)*
|
||
|
||
Calls `golint` for the current package
|
||
|
||
*(go-vet)*
|
||
|
||
Calls `go vet` for the current package
|
||
|
||
|
||
*(go-files)*
|
||
|
||
Show source files that depends for the current package
|
||
|
||
|
||
*(go-deps)*
|
||
|
||
Show dependencies for the current package
|
||
|
||
*(go-doc)*
|
||
|
||
Show the relevant GoDoc for the word under the cursor in a split window
|
||
leftabove (default mode).
|
||
|
||
*(go-doc-split)*
|
||
|
||
Show the relevant GoDoc for the word under the cursor in a split window.
|
||
|
||
|
||
*(go-doc-vertical)*
|
||
|
||
Show the relevant GoDoc for the word under the cursor in a vertical split
|
||
window.
|
||
|
||
*(go-doc-tab)*
|
||
|
||
Show the relevant GoDoc for the word under the cursor in a tab window.
|
||
|
||
|
||
*(go-doc-browser)*
|
||
|
||
Show the relevant GoDoc for the word under in browser
|
||
|
||
*(go-def)*
|
||
|
||
Goto declaration/definition. Results are shown in the current buffer.
|
||
|
||
*(go-def-split)*
|
||
|
||
Goto declaration/definition. Results are shown in a split window.
|
||
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.
|
||
|
||
*(go-def-vertical)*
|
||
|
||
Goto declaration/definition. Results are shown in a vertical split window.
|
||
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.
|
||
|
||
*(go-def-tab)*
|
||
|
||
Goto declaration/definition. Results are shown in a tab window.
|
||
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.
|
||
|
||
*(go-def-stack)*
|
||
|
||
Shows the godef tag stack
|
||
|
||
*(go-def-stack-clear)*
|
||
|
||
Resets and clears the tag stack
|
||
|
||
*(go-def-pop)*
|
||
|
||
Jump to previous entry in the tag stack
|
||
|
||
*(go-implements)*
|
||
|
||
Show the interfaces that the type under the cursor implements.
|
||
|
||
*(go-rename)*
|
||
|
||
Rename the identifier under the cursor to the desired new name
|
||
|
||
*(go-callees)*
|
||
|
||
Show the call targets for the type under the cursor
|
||
|
||
*(go-callers)*
|
||
|
||
Show possible callers of selected function
|
||
|
||
*(go-describe)*
|
||
|
||
Describe selected syntax: definition, methods, etc
|
||
|
||
*(go-callstack)*
|
||
|
||
Show path from callgraph root to selected function
|
||
|
||
*(go-freevars)*
|
||
|
||
Show free variables of selection
|
||
|
||
*(go-channelpeers)*
|
||
|
||
Show send/receive corresponding to selected channel op
|
||
|
||
*(go-referrers)*
|
||
|
||
Show all refs to entity denoted by selected identifier
|
||
|
||
*(go-pointsto)*
|
||
|
||
Show all variables to which the pointer under the cursor may point to.
|
||
|
||
*(go-metalinter)*
|
||
|
||
Calls `go-metalinter` for the current directory
|
||
|
||
*(go-alternate-edit)*
|
||
|
||
Alternates between the implementation and test code in the current window
|
||
|
||
*(go-alternate-split)*
|
||
|
||
Alternates between the implementation and test code in a new horizontal split
|
||
|
||
*(go-alternate-vertical)*
|
||
|
||
Alternates between the implementation and test code in a new vertical split
|
||
|
||
*(go-import)*
|
||
|
||
Calls `:GoImport` for the current package
|
||
|
||
*(go-iferr)*
|
||
|
||
Generate if err != nil { return ... } automatically which infer the type of
|
||
return values and the numbers.
|
||
|
||
*(go-mod-fmt)*
|
||
|
||
Calls |:GoModFmt| for the current buffer
|
||
|
||
==============================================================================
|
||
TEXT OBJECTS *go-text-objects*
|
||
|
||
vim-go comes with several custom |text-objects| that can be used to operate
|
||
upon regions of text. vim-go currently defines the following text objects:
|
||
|
||
*go-v_af* *go-af*
|
||
af "a function", select contents from a function definition to the
|
||
closing bracket. If |'g:go_textobj_include_function_doc'| is
|
||
enabled it also includes the comment doc for a function
|
||
declaration. This text-object also supports literal functions.
|
||
If |'g:go_textobj_include_variable'| is enabled it also
|
||
includes the variable of an function assignment
|
||
|
||
*go-v_if* *go-if*
|
||
if "inside a function", select contents of a function,
|
||
excluding the function definition and the closing bracket. This
|
||
text-object also supports literal functions
|
||
|
||
*go-v_ac* *go-ac*
|
||
ac "a comment", select contents of the current comment block.
|
||
|
||
*go-v_ic* *go-ic*
|
||
ic "inner comment", select contents of the current comment block,
|
||
excluding the start and end comment markers.
|
||
|
||
vim-go also defines the following text motion objects:
|
||
|
||
*go-v_]]* *go-]]*
|
||
]] [count] forward to next function declaration. If
|
||
|'g:go_textobj_include_function_doc'| is enabled and if your
|
||
on a comment, it skips the function which the comment
|
||
belongs and forwards to the next function declaration.
|
||
|
||
*go-v_[[* *go-[[*
|
||
[[ [count] backward to previous function declaration.
|
||
|
||
|
||
|
||
==============================================================================
|
||
FUNCTIONS *go-functions*
|
||
|
||
*go#statusline#Show()*
|
||
|
||
Shows the status of a job running asynchronously. Can be used to plug into the
|
||
statusline. It works to show the status per package instead of per file.
|
||
Assume you have three files open, all belonging to the same package, if the
|
||
package build (`:GoBuild`) is successful, all statuslines will show `success`,
|
||
if it fails all windows' statuslines will show `failed`.
|
||
|
||
To avoid always showing old status information, the status information is
|
||
cleaned for each package after `60` seconds. This can be changed with the
|
||
|'g:go_statusline_duration'| setting.
|
||
|
||
*go#complete#GetInfo()*
|
||
|
||
Returns the description of the identifer under the cursor. Can be used to plug
|
||
into the statusline.
|
||
|
||
*go#complete#Complete()*
|
||
|
||
Uses `gopls` for autocompletion. By default, it is hooked up to |'omnifunc'|.
|
||
|
||
|
||
*go#complete#GocodeComplete()*
|
||
|
||
Uses `gocode` for autocompletion.
|
||
|
||
*go#tool#DescribeBalloon()*
|
||
|
||
Suitable to be used as an expression to show the evaluation balloon. See `help
|
||
balloonexpr`.
|
||
|
||
==============================================================================
|
||
SETTINGS *go-settings*
|
||
|
||
*'g:go_version_warning'*
|
||
|
||
Enable warning when using an unsupported version of Vim. By default it is
|
||
enabled.
|
||
>
|
||
let g:go_version_warning = 1
|
||
<
|
||
|
||
*'g:go_code_completion_enabled'*
|
||
|
||
Enable code completion with |'omnifunc'|. By default it is enabled.
|
||
>
|
||
let g:go_code_completion_enabled = 1
|
||
<
|
||
|
||
*'g:go_test_show_name'*
|
||
|
||
Show the name of each failed test before the errors and logs output by the
|
||
test. By default it is disabled.
|
||
>
|
||
let g:go_test_show_name = 0
|
||
<
|
||
|
||
*'g:go_test_timeout'*
|
||
|
||
Use this option to change the test timeout of |:GoTest|. By default it is
|
||
set to 10 seconds . >
|
||
|
||
let g:go_test_timeout= '10s'
|
||
<
|
||
*'g:go_play_browser_command'*
|
||
|
||
Browser to use for |:GoPlay|, |:GoDocBrowser|, and |:GoLSPDebugBrowser|. The
|
||
url must be added with `%URL%`, and it's advisable to include `&` to make sure
|
||
the shell returns. For example:
|
||
>
|
||
let g:go_play_browser_command = 'firefox-developer %URL% &'
|
||
<
|
||
|
||
By default it tries to find it automatically for the current OS. >
|
||
|
||
let g:go_play_browser_command = ''
|
||
<
|
||
*'g:go_play_open_browser'*
|
||
|
||
Use this option to open browser after posting the snippet to play.golang.org
|
||
with |:GoPlay|. By default it's enabled. >
|
||
|
||
let g:go_play_open_browser = 1
|
||
<
|
||
*'g:go_auto_type_info'*
|
||
|
||
Use this option to show the type info (|:GoInfo|) for the word under the
|
||
cursor automatically. Whenever the cursor changes the type info will be
|
||
updated. By default it's disabled. The delay can be configured with the
|
||
|'g:go_updatetime'| setting.
|
||
>
|
||
let g:go_auto_type_info = 0
|
||
<
|
||
|
||
*'g:go_info_mode'*
|
||
|
||
Use this option to define the command to be used for |:GoInfo|. By default
|
||
`gopls` is used, because it is the fastest and is known to be highly accurate.
|
||
One might also use `guru` for its accuracy or `gocode` for its performance.
|
||
Valid options are `gocode`, `gopls`, and `guru`.
|
||
>
|
||
let g:go_info_mode = 'gopls'
|
||
<
|
||
*'g:go_auto_sameids'*
|
||
|
||
Use this option to highlight all uses of the identifier under the cursor
|
||
(|:GoSameIds|) automatically. By default it's disabled. The delay can be
|
||
configured with the |'g:go_updatetime'| setting.
|
||
>
|
||
let g:go_auto_sameids = 0
|
||
<
|
||
*'g:go_updatetime'*
|
||
|
||
Use this option to configure the delay until it starts some jobs (see
|
||
|'g:go_auto_type_info'|, |'g:go_auto_sameids'|). If set to 0, it uses the
|
||
value from 'updatetime'. By default it's set to 800ms.
|
||
>
|
||
let g:go_updatetime = 800
|
||
<
|
||
*'g:go_jump_to_error'*
|
||
|
||
Use this option to enable/disable passing the bang attribute to the mappings
|
||
|(go-build)|, |(go-run)|, etc.. When enabled it will jump to the first error
|
||
automatically (means it will NOT pass the bang attribute to the appropriate
|
||
command, i.e: (go-run) -> :GoRun ). Note, that calling this doesn't have any
|
||
affect on calling the commands manually. This setting is only useful for
|
||
changing the behaviour of our custom static mappings. By default it's enabled.
|
||
>
|
||
let g:go_jump_to_error = 1
|
||
<
|
||
*'g:go_fmt_autosave'*
|
||
|
||
Use this option to auto |:GoFmt| on save. By default it's enabled >
|
||
|
||
let g:go_fmt_autosave = 1
|
||
<
|
||
*'g:go_fmt_command'*
|
||
|
||
Use this option to define which tool is used to gofmt. By default `gofmt` is
|
||
used.
|
||
>
|
||
|
||
let g:go_fmt_command = "gofmt"
|
||
<
|
||
*'g:go_fmt_options'*
|
||
|
||
Use this option to add additional options to the |'g:go_fmt_command'|. It's
|
||
value type can be either a string or a dictionary. This is due backwards
|
||
compatibility. The string version will be removed in the future so please use
|
||
the dictionary version. Default is empty.
|
||
>
|
||
let g:go_fmt_options = ''
|
||
|
||
or
|
||
|
||
let g:go_fmt_options = {}
|
||
<
|
||
The dictionary version allows you to define options for multiple binaries:
|
||
>
|
||
let g:go_fmt_options = {
|
||
\ 'gofmt': '-s',
|
||
\ 'goimports': '-local mycompany.com',
|
||
\ }
|
||
<
|
||
*'g:go_fmt_fail_silently'*
|
||
|
||
Use this option to disable showing a location list when |'g:go_fmt_command'|
|
||
fails. By default the location list is shown. >
|
||
|
||
let g:go_fmt_fail_silently = 0
|
||
<
|
||
*'g:go_fmt_experimental'*
|
||
|
||
Use this option to enable fmt's experimental mode. This experimental mode is
|
||
superior to the current mode as it fully saves the undo history, so undo/redo
|
||
doesn't break. However, it's slow (creates/deletes a file for every save) and
|
||
it's causing problems on some Vim versions. By default it's disabled. >
|
||
|
||
let g:go_fmt_experimental = 0
|
||
|
||
<
|
||
*'g:go_mod_fmt_autosave'*
|
||
|
||
Use this option to auto |:GoModFmt| on save. By default it's enabled >
|
||
|
||
let g:go_mod_fmt_autosave = 1
|
||
<
|
||
|
||
*'g:go_doc_keywordprg_enabled'*
|
||
|
||
Use this option to run `godoc` on words under the cursor with |K|; this will
|
||
normally run the `man` program, but for Go using `godoc` is more idiomatic. It
|
||
will not override the |'keywordprg'| setting, but will run |:GoDoc|. Default
|
||
is enabled. >
|
||
|
||
let g:go_doc_keywordprg_enabled = 1
|
||
<
|
||
*'g:go_doc_height'*
|
||
|
||
Maximum height for the GoDoc window created with |:GoDoc|. Default is 20. >
|
||
|
||
let g:go_doc_max_height = 20
|
||
<
|
||
|
||
*'g:go_doc_url'*
|
||
|
||
godoc server URL used when |:GoDocBrowser| is used. Change if you want to use
|
||
a private internal service. Default is 'https://godoc.org'.
|
||
>
|
||
let g:go_doc_url = 'https://godoc.org'
|
||
<
|
||
|
||
*'g:go_doc_popup_window'*
|
||
|
||
Use this option to use the popup-window for |K| and |:GoDoc|, rather than the
|
||
|preview-window|. Default is disabled.
|
||
>
|
||
let g:go_doc_popup_window = 0
|
||
<
|
||
|
||
*'g:go_def_mode'*
|
||
|
||
Use this option to define the command to be used for |:GoDef|. By default
|
||
`gopls` is used, because it is the fastest. One might also use `guru` for its
|
||
accuracy or `godef` for its performance. Valid options are `godef`, `gopls`,
|
||
and `guru`.
|
||
>
|
||
let g:go_def_mode = 'gopls'
|
||
<
|
||
*'g:go_referrers_mode'*
|
||
|
||
Use this option to define the command to be used for |:GoReferrers|. By
|
||
default `gopls` is used, because it is the fastest and works with Go modules.
|
||
One might also use `guru` for its ability to show references from other
|
||
packages. This option will be removed after `gopls` can show references from
|
||
other packages. Valid options are `gopls` and `guru`.
|
||
>
|
||
let g:go_referrers_mode = 'gopls'
|
||
<
|
||
*'g:go_def_mapping_enabled'*
|
||
|
||
Use this option to enable/disable the default mapping of CTRL-],
|
||
<C-LeftMouse>, g<C-LeftMouse> and (`gd`) for GoDef and CTRL-t for :GoDefPop.
|
||
Disabling it allows you to map something else to these keys or mappings.
|
||
Default is enabled. >
|
||
|
||
let g:go_def_mapping_enabled = 1
|
||
<
|
||
*'g:go_def_reuse_buffer'*
|
||
|
||
Use this option to jump to an existing buffer for the split, vsplit and tab
|
||
mappings of |:GoDef|. By default it's disabled. >
|
||
|
||
let g:go_def_reuse_buffer = 0
|
||
<
|
||
*'g:go_bin_path'*
|
||
|
||
Use this option to change default path for vim-go tools when using
|
||
|:GoInstallBinaries| and |:GoUpdateBinaries|. If not set `$GOBIN` or
|
||
`$GOPATH/bin` is used. >
|
||
|
||
let g:go_bin_path = ""
|
||
<
|
||
*'g:go_search_bin_path_first'*
|
||
|
||
This option lets |'g:go_bin_path'| (or its default value) take precedence over
|
||
$PATH when invoking a tool command such as |:GoFmt| or |:GoImports|.
|
||
|
||
Enabling this option ensures that the binaries installed via
|
||
|:GoInstallBinaries| and |:GoUpdateBinaries| are the same ones that are
|
||
invoked via the tool commands.
|
||
|
||
By default it is enabled. >
|
||
|
||
let g:go_search_bin_path_first = 1
|
||
<
|
||
*'g:go_snippet_engine'*
|
||
|
||
Define the snippet engine to use. The default is to auto-detect one. Valid
|
||
values are:
|
||
|
||
automatic Automatically detect a snippet engine.
|
||
ultisnips https://github.com/SirVer/ultisnips
|
||
neosnippet https://github.com/Shougo/neosnippet.vim
|
||
minisnip https://github.com/joereynolds/vim-minisnip
|
||
Note: the original at KeyboardFire/vim-minisnip won't work.
|
||
>
|
||
let g:go_snippet_engine = "automatic"
|
||
<
|
||
*'g:go_get_update'*
|
||
|
||
Use this option to disable updating dependencies with |:GoInstallBinaries|. By
|
||
default this is enabled.
|
||
>
|
||
let g:go_get_update = 1
|
||
<
|
||
*'g:go_guru_scope'*
|
||
|
||
Use this option to define the scope of the analysis to be passed for guru
|
||
related commands, such as |:GoImplements|, |:GoCallers|, etc. You can change
|
||
it on-the-fly with |:GoGuruScope|. The input should be a a list of package
|
||
pattern. An example input might be:
|
||
`["github.com/fatih/color","github.com/fatih/structs"]`
|
||
|
||
Also see |go-guru-scope|.
|
||
|
||
By default it's not set, so the relevant commands' defaults are being used.
|
||
>
|
||
let g:go_guru_scope = []
|
||
<
|
||
*'g:go_build_tags'*
|
||
|
||
Space-separated list of build tags passed to the `-tags` flag of tools that
|
||
support it.
|
||
There is also the |:GoBuildTags| convenience command to change or remove build
|
||
tags.
|
||
>
|
||
let g:go_build_tags = ''
|
||
<
|
||
*'g:go_autodetect_gopath'*
|
||
|
||
Automatically modify GOPATH for certain directory structures, such as for
|
||
the `godep` tool which stores dependencies in the `Godeps` folder. What this
|
||
means is that all tools are now working with the newly modified GOPATH. So
|
||
|:GoDef| for example jumps to the source inside the `Godeps` (vendored)
|
||
source. Currently `godep` and `gb` are supported. By default it's disabled.
|
||
>
|
||
let g:go_autodetect_gopath = 0
|
||
<
|
||
*'g:go_textobj_enabled'*
|
||
|
||
Adds custom text objects. By default it's enabled. >
|
||
|
||
let g:go_textobj_enabled = 1
|
||
<
|
||
*'g:go_textobj_include_function_doc'*
|
||
|
||
Consider the comment above a function to be part of the function when using
|
||
the `af` text object and `[[` motion. By default it's enabled. >
|
||
|
||
let g:go_textobj_include_function_doc = 1
|
||
<
|
||
*'g:go_textobj_include_variable'*
|
||
|
||
Consider the variable of an function assignment to be part of the anonymous
|
||
function when using the `af` text object. By default it's enabled. >
|
||
|
||
let g:go_textobj_include_variable = 1
|
||
<
|
||
*'g:go_metalinter_autosave'*
|
||
|
||
Use this option to auto |:GoMetaLinter| on save. Only linter messages for
|
||
the active buffer will be shown.
|
||
|
||
By default, `golangci-lint` messages will be shown in the |location-list|
|
||
window. The list to use can be set using |'g:go_list_type_commands'|.
|
||
|
||
By default it's disabled >
|
||
let g:go_metalinter_autosave = 0
|
||
<
|
||
*'g:go_metalinter_autosave_enabled'*
|
||
|
||
Specifies the enabled linters for auto |:GoMetaLinter| on save. By
|
||
default it's using `vet` and `golint`.
|
||
>
|
||
let g:go_metalinter_autosave_enabled = ['vet', 'golint']
|
||
<
|
||
*'g:go_metalinter_enabled'*
|
||
|
||
Specifies the linters to enable for the |:GoMetaLinter| command. By default
|
||
it's using `vet`, `golint` and `errcheck`.
|
||
>
|
||
let g:go_metalinter_enabled = ['vet', 'golint', 'errcheck']
|
||
<
|
||
*'g:go_metalinter_disabled'*
|
||
|
||
Specifies the linters to disable for the |:GoMetaLinter| command. By default
|
||
it's empty
|
||
>
|
||
let g:go_metalinter_disabled = []
|
||
<
|
||
*'g:go_metalinter_command'*
|
||
|
||
Overrides the command to be executed when |:GoMetaLinter| is called. By
|
||
default it's `golangci-lint`. It can also be used as an advanced setting
|
||
for users who want to have more control over the metalinter.
|
||
>
|
||
let g:go_metalinter_command = "golangci-lint"
|
||
<
|
||
*'g:go_metalinter_deadline'*
|
||
|
||
Overrides the maximum time the linters have to complete. By default it's 5
|
||
seconds.
|
||
>
|
||
let g:go_metalinter_deadline = "5s"
|
||
<
|
||
*'g:go_list_height'*
|
||
|
||
Specifies the window height for the quickfix and location list windows. The
|
||
default value (empty) automatically sets the height to the number of items
|
||
(maximum up to 10 items to prevent large heights). Setting the value
|
||
explicitly overrides this behavior. For standard Vim behavior, set it to 10.
|
||
>
|
||
let g:go_list_height = 0
|
||
<
|
||
*'g:go_list_type'*
|
||
|
||
Specifies the type of list to use for command outputs (such as errors from
|
||
builds, results from static analysis commands, etc...). The list type for
|
||
specific commands can be overridden with |'g:go_list_type_commands'|. The
|
||
default value (empty) will use the appropriate kind of list for the command
|
||
that was called. Supported values are "", "quickfix", and "locationlist".
|
||
>
|
||
let g:go_list_type = ""
|
||
<
|
||
|
||
*'g:go_list_type_commands'*
|
||
|
||
Specifies the type of list to use for command outputs (such as errors from
|
||
builds, results from static analysis commands, etc...). When an expected key
|
||
is not present in the dictionary, |'g:go_list_type'| will be used instead.
|
||
Supported keys are "GoBuild", "GoErrCheck", "GoFmt", "GoModFmt", "GoInstall",
|
||
"GoLint", "GoMetaLinter", "GoMetaLinterAutoSave", "GoModifyTags" (used for
|
||
both :GoAddTags and :GoRemoveTags), "GoRename", "GoRun", and "GoTest".
|
||
Supported values for each command are "quickfix" and "locationlist".
|
||
>
|
||
let g:go_list_type_commands = {}
|
||
<
|
||
As an example, the following settings will change all list types to
|
||
`locationlist` except for `:GoBuild` where `quickfix` is used:
|
||
>
|
||
let g:go_list_type = "locationlist"
|
||
let g:go_list_type_commands = {"GoBuild": "quickfix"}
|
||
<
|
||
|
||
*'g:go_list_autoclose'*
|
||
|
||
Specifies whether the quickfix/location list should be closed automatically
|
||
in the absence of errors. The default value is 1.
|
||
If you prefer to keep a long running error window open, you can disable
|
||
this by setting the value to 0.
|
||
>
|
||
let g:go_list_autoclose = 1
|
||
<
|
||
*'g:go_asmfmt_autosave'*
|
||
|
||
Use this option to auto |:AsmFmt| on save. By default it's disabled. >
|
||
|
||
let g:go_asmfmt_autosave = 0
|
||
<
|
||
*'g:go_term_mode'*
|
||
|
||
This option is Neovim only. Use it to change the default command used to
|
||
open a new terminal for go commands such as |:GoRun|.
|
||
The default is vsplit.
|
||
>
|
||
let g:go_term_mode = "vsplit"
|
||
<
|
||
*'g:go_term_height'*
|
||
*'g:go_term_width'*
|
||
|
||
These options are Neovim only. Use them to control the height and width of
|
||
a terminal split. By default these are not set, meaning that the height and
|
||
width are set automatically by Neovim. The height only applies to a
|
||
horizontal split and width only applies to a vertical split.
|
||
|
||
For example here is how to set each to 30.
|
||
>
|
||
let g:go_term_height = 30
|
||
let g:go_term_width = 30
|
||
<
|
||
*'g:go_term_enabled'*
|
||
|
||
This option is Neovim only. Use it to change the behavior of the test
|
||
commands. If set to 1 it opens the test commands inside a new terminal
|
||
according to |'g:go_term_mode'|, otherwise it will run them in the background
|
||
just like `:GoBuild`. By default it is disabled.
|
||
>
|
||
let g:go_term_enabled = 0
|
||
<
|
||
*'g:go_term_close_on_exit'*
|
||
|
||
This option is Neovim only. If set to 1 it closes the terminal after the
|
||
command run in it exits when the command fails. By default it is enabled.
|
||
>
|
||
let g:go_term_close_on_exit = 1
|
||
<
|
||
*'g:go_alternate_mode'*
|
||
|
||
Specifies the command that |:GoAlternate| uses to open the alternate file.
|
||
By default it is set to edit.
|
||
>
|
||
let g:go_alternate_mode = "edit"
|
||
<
|
||
*'g:go_gorename_command'*
|
||
|
||
Use this option to define which tool is used to rename. By default `gorename`
|
||
is used. Valid options are `gorename` and `gopls`. Warning: as of `gopls`
|
||
v0.2.0, it will only rename identifiers in the current package.
|
||
>
|
||
let g:go_gorename_command = 'gorename'
|
||
<
|
||
*'g:go_gorename_prefill'*
|
||
|
||
Expression to prefill the new identifier when using |:GoRename| without any
|
||
arguments. Use an empty string if you don't want to prefill anything. By
|
||
default it converts the identifier to camel case but preserves the
|
||
capitalisation of the first letter to ensure that the exported state stays the
|
||
same.
|
||
>
|
||
let g:go_gorename_prefill = 'expand("<cword>") =~# "^[A-Z]"' .
|
||
\ '? go#util#pascalcase(expand("<cword>"))' .
|
||
\ ': go#util#camelcase(expand("<cword>"))'
|
||
<
|
||
*'g:go_gocode_propose_builtins'*
|
||
|
||
Specifies whether `gocode` should add built-in types, functions and constants
|
||
to code completion proposals. By default it is enabled.
|
||
>
|
||
let g:go_gocode_propose_builtins = 1
|
||
<
|
||
*'g:go_gocode_propose_source'*
|
||
|
||
Specifies whether `gocode` should use source files instead of binary packages
|
||
for code completion proposals. When disabled, only identifiers from the
|
||
current package and packages that have been installed will proposed.
|
||
>
|
||
let g:go_gocode_propose_source = 0
|
||
<
|
||
*'g:go_gocode_unimported_packages'*
|
||
|
||
Specifies whether `gocode` should include suggestions from unimported
|
||
packages. By default it is disabled.
|
||
>
|
||
let g:go_gocode_unimported_packages = 0
|
||
<
|
||
|
||
*'g:go_gocode_socket_type'*
|
||
|
||
Specifies whether `gocode` should use a different socket type. By default
|
||
`unix` is enabled. Possible values: `unix`, `tcp`
|
||
>
|
||
let g:go_gocode_socket_type = 'unix'
|
||
<
|
||
|
||
*'g:go_gopls_complete_unimported'*
|
||
|
||
Specifies whether `gopls` should include suggestions from unimported packages.
|
||
By default it is disabled.
|
||
>
|
||
let g:go_gopls_complete_unimported = 0
|
||
<
|
||
|
||
*'g:go_gopls_deep_completion'*
|
||
|
||
Specifies whether `gopls` should use deep completion. By default it is
|
||
enabled.
|
||
>
|
||
let g:go_gopls_deep_completion = 1
|
||
<
|
||
|
||
*'g:go_gopls_fuzzy_matching'*
|
||
|
||
Specifies whether `gopls` should use fuzzy matching for completions.
|
||
By default it is enabled.
|
||
>
|
||
let g:go_gopls_fuzzy_matching = 1
|
||
<
|
||
|
||
*'g:go_gopls_use_placeholders'*
|
||
|
||
Specifies whether `gopls` can provide placeholders for function parameters and
|
||
struct fields. By default it is disabled.
|
||
>
|
||
let g:go_gopls_use_placeholders = 0
|
||
<
|
||
|
||
*'g:go_template_autocreate'*
|
||
|
||
When a new Go file is created, vim-go automatically fills the buffer content
|
||
with a Go code template. By default, the templates under the `templates`
|
||
folder are used. This can be changed with the |'g:go_template_file'| and
|
||
|'g:go_template_test_file'| settings to either use a different file in the
|
||
same `templates` folder, or to use a file stored elsewhere.
|
||
|
||
If the new file is created in an already prepopulated package (with other Go
|
||
files), in this case a Go code template with only the Go package declaration
|
||
(which is automatically determined according to the current package) is added.
|
||
|
||
To always use the package name instead of the template, enable the
|
||
|'g:go_template_use_pkg'| setting.
|
||
|
||
By default it is enabled.
|
||
>
|
||
let g:go_template_autocreate = 1
|
||
<
|
||
*'g:go_template_file'*
|
||
|
||
Specifies either the file under the `templates` folder that is used if a new
|
||
Go file is created. Checkout |'g:go_template_autocreate'| for more info. By
|
||
default the `hello_world.go` file is used.
|
||
|
||
This variable can be set to an absolute path, so the template files don't have
|
||
to be stored inside the vim-go directory structure. Useful when you want to
|
||
use different templates for different projects.
|
||
>
|
||
let g:go_template_file = "hello_world.go"
|
||
<
|
||
*'g:go_template_test_file'*
|
||
|
||
Like with |'g:go_template_file'|, this specifies the file to use for test
|
||
tempaltes. The template file should be under the `templates` folder,
|
||
alternatively absolute paths can be used, too. Checkout
|
||
|'g:go_template_autocreate'| for more info. By default, the
|
||
`hello_world_test.go` file is used.
|
||
>
|
||
let g:go_template_test_file = "hello_world_test.go"
|
||
<
|
||
*'g:go_template_use_pkg'*
|
||
|
||
Specifies that, rather than using a template, the package name is used if a
|
||
new Go file is created. Checkout |'g:go_template_autocreate'| for more info.
|
||
By default the template file specified by |'g:go_template_file'| is used.
|
||
|
||
>
|
||
let g:go_template_use_pkg = 0
|
||
<
|
||
*'g:go_decls_includes'*
|
||
|
||
Only useful if `ctrlp.vim`, `unite.vim`, `denite.nvim` or `fzf` are installed.
|
||
This sets which declarations to show for |:GoDecls| (`ctrp.vim`),
|
||
|unite-decls| (`unite.vim`) and |denite-decls| (`denite.nvim`). It is a Comma
|
||
delimited list. Possible options are: {func,type}. The default is: >
|
||
|
||
let g:go_decls_includes = 'func,type'
|
||
<
|
||
*'g:go_decls_mode'*
|
||
|
||
Define the tool to be used for |:GoDecls|. Valid options are `ctrlp.vim`,
|
||
`fzf`, or an empty string; in which case it will try to autodetect either
|
||
`ctrlp.vim` or `fzf`.
|
||
>
|
||
let g:go_decls_mode = ''
|
||
<
|
||
*'g:go_echo_command_info'*
|
||
|
||
Echoes information about various Go commands, such as `:GoBuild`, `:GoTest`,
|
||
`:GoCoverage`, etc... Useful to disable if you use the statusline integration,
|
||
i.e: |go#statusline#Show()|. By default it's enabled
|
||
>
|
||
let g:go_echo_command_info = 1
|
||
<
|
||
*'g:go_echo_go_info'*
|
||
|
||
Use this option to show the identifier information when code completion is
|
||
done. By default it's enabled. >
|
||
|
||
let g:go_echo_go_info = 1
|
||
<
|
||
Please note that 'noshowmode' must be set for this feature to work correctly.
|
||
|
||
*'g:go_statusline_duration'*
|
||
|
||
Specifies the duration of statusline information being showed per package. By
|
||
default it's 60 seconds. Must be in milliseconds.
|
||
>
|
||
let g:go_statusline_duration = 60000
|
||
<
|
||
*'g:go_addtags_transform'*
|
||
|
||
Sets the `transform` option for `gomodifytags` when using |:GoAddTags| or if
|
||
it's being used for snippet expansion of single fields. Possible options are:
|
||
`snakecase`, `camelcase`, `lispcase`, `pascalcase`, `keep`. For the following
|
||
case, if `snakecase` is used the field will be transformed to:
|
||
>
|
||
type T struct {
|
||
FooBarQuz string `json:"foo_bar_quz"
|
||
}
|
||
<
|
||
|
||
If "camelcase" is used:
|
||
>
|
||
type T struct {
|
||
FooBarQuz string `json:"fooBarQuz"
|
||
}
|
||
<
|
||
By default "snakecase" is used. Current values are: ["snakecase",
|
||
"camelcase", "lispcase", "pascalcase", "keep"].
|
||
>
|
||
let g:go_addtags_transform = 'snakecase'
|
||
<
|
||
*'g:go_debug'*
|
||
|
||
A list of options to debug; useful for development and/or reporting bugs.
|
||
|
||
Currently accepted values:
|
||
|
||
shell-commands Echo all shell commands that vim-go runs.
|
||
debugger-state Expose debugger state in 'g:go_debug_diag'.
|
||
debugger-commands Echo communication between vim-go and `dlv`; requests and
|
||
responses are recorded in `g:go_debug_commands`.
|
||
lsp Echo communication between vim-go and `gopls`. All
|
||
communication is shown in a dedicated window. When
|
||
enabled before gopls is started, |:GoLSPDebugBrowser| can
|
||
be used to open a browser window to help debug gopls.
|
||
>
|
||
let g:go_debug = []
|
||
<
|
||
|
||
==============================================================================
|
||
SYNTAX HIGHLIGHTING *ft-go-syntax* *go-syntax*
|
||
|
||
vim-go comes with an enhanced version of Vim's Go syntax highlighting. It
|
||
comes with a number of features, most of which are disabled by default.
|
||
|
||
The recommended settings are the default values. If you're experiencing
|
||
slowdowns in Go files and you enabled some of these options then try disabling
|
||
them; some can be resource intensive.
|
||
|
||
*'g:go_fold_enable'*
|
||
|
||
Control syntax-based folding which takes effect when 'foldmethod' is set to
|
||
`syntax`.
|
||
You can enable specific fold regions by setting an array. Possible values are:
|
||
|
||
block `{` .. `}` blocks.
|
||
import `import` block.
|
||
varconst `var` and `const` blocks.
|
||
package_comment The package comment.
|
||
comment Any comment that is not the package comment.
|
||
|
||
By default all except "comment" are enabled:
|
||
>
|
||
let g:go_fold_enable = ['block', 'import', 'varconst', 'package_comment']
|
||
<
|
||
Enable folding of only imports:
|
||
>
|
||
let g:go_fold_enable = ['import']
|
||
<
|
||
Disable everything (same as not setting 'foldmethod' to `syntax`):
|
||
>
|
||
let g:go_fold_enable = []
|
||
<
|
||
*'g:go_highlight_array_whitespace_error'*
|
||
|
||
Highlight white space after `[]`. >
|
||
|
||
let g:go_highlight_array_whitespace_error = 0
|
||
<
|
||
*'g:go_highlight_chan_whitespace_error'*
|
||
|
||
Highlight white space around the receive operator (`<-`) that doesn't follow
|
||
the standard style. >
|
||
|
||
let g:go_highlight_chan_whitespace_error = 0
|
||
<
|
||
*'g:go_highlight_extra_types'*
|
||
|
||
Highlight commonly used library types (`io.Reader`, etc.). >
|
||
|
||
let g:go_highlight_extra_types = 0
|
||
<
|
||
*'g:go_highlight_space_tab_error'*
|
||
|
||
Highlight instances of tabs following spaces. >
|
||
|
||
let g:go_highlight_space_tab_error = 0
|
||
<
|
||
*'g:go_highlight_trailing_whitespace_error'*
|
||
|
||
Highlight trailing white space. >
|
||
|
||
let g:go_highlight_trailing_whitespace_error = 0
|
||
<
|
||
*'g:go_highlight_operators'*
|
||
|
||
Highlight operators such as `:=` , `==`, `-=`, etc.
|
||
>
|
||
let g:go_highlight_operators = 0
|
||
<
|
||
*'g:go_highlight_functions'*
|
||
|
||
Highlight function and method declarations.
|
||
>
|
||
let g:go_highlight_functions = 0
|
||
<
|
||
*'g:go_highlight_function_parameters'*
|
||
|
||
Highlight the variable names in parameters (including named return parameters)
|
||
in function declarations. Setting this implies the functionality from
|
||
|'g:go_highlight_functions'|.
|
||
>
|
||
let g:go_highlight_function_parameters = 0
|
||
<
|
||
*'g:go_highlight_function_calls'*
|
||
|
||
Highlight function and method calls.
|
||
>
|
||
let g:go_highlight_function_calls = 0
|
||
<
|
||
*'g:go_highlight_types'*
|
||
|
||
Highlight struct and interface names.
|
||
>
|
||
let g:go_highlight_types = 0
|
||
<
|
||
*'g:go_highlight_fields'*
|
||
|
||
Highlight struct field names.
|
||
>
|
||
let g:go_highlight_fields = 0
|
||
<
|
||
*'g:go_highlight_build_constraints'*
|
||
|
||
Highlights build constraints.
|
||
>
|
||
let g:go_highlight_build_constraints = 0
|
||
<
|
||
*'g:go_highlight_generate_tags'*
|
||
|
||
Highlight go:generate directives.
|
||
>
|
||
let g:go_highlight_generate_tags = 0
|
||
<
|
||
*'g:go_highlight_string_spellcheck'*
|
||
|
||
Highlight spelling errors in strings when |spell| is enabled.
|
||
>
|
||
let g:go_highlight_string_spellcheck = 1
|
||
<
|
||
*'g:go_highlight_format_strings'*
|
||
|
||
Highlight printf-style formatting verbs inside string literals.
|
||
>
|
||
let g:go_highlight_format_strings = 1
|
||
<
|
||
*'g:go_highlight_variable_declarations'*
|
||
|
||
Highlight variable names in variable declarations (`x` in ` x :=`).
|
||
>
|
||
let g:go_highlight_variable_declarations = 0
|
||
<
|
||
*'g:go_highlight_variable_assignments'*
|
||
|
||
Highlight variable names in variable assignments (`x` in `x =`).
|
||
>
|
||
let g:go_highlight_variable_assignments = 0
|
||
<
|
||
*'g:go_highlight_diagnostic_errors'*
|
||
|
||
Highlight diagnostic errors.
|
||
>
|
||
let g:go_highlight_diagnostic_errors = 1
|
||
<
|
||
*'g:go_highlight_diagnostic_warnings'*
|
||
|
||
Highlight diagnostic warnings.
|
||
>
|
||
let g:go_highlight_diagnostic_warnings = 1
|
||
<
|
||
|
||
==============================================================================
|
||
*gohtmltmpl* *ft-gohtmltmpl-syntax*
|
||
*gotexttmpl* *ft-gotexttmpl-syntax*
|
||
Go template syntax~
|
||
|
||
The `gotexttmpl` 'filetype' provides syntax highlighting and indentation for
|
||
Go's `text/template` package.
|
||
|
||
The `gohtmltmpl` filetype is for use with the `html/template` package and is
|
||
identical to `gotexttmpl` except that it will also load the standard `html`
|
||
filetype.
|
||
|
||
The `gohtmltmpl` filetype is automatically set for `*.tmpl` files; the
|
||
`gotexttmpl` is never automatically set and needs to be set manually.
|
||
|
||
==============================================================================
|
||
*gomod* *ft-gomod-syntax*
|
||
go.mod file syntax~
|
||
|
||
The `gomod` 'filetype' provides syntax highlighting for Go's module file
|
||
`go.mod`
|
||
|
||
|
||
==============================================================================
|
||
DEBUGGER *go-debug*
|
||
|
||
Vim-go comes with a special "debugger mode". This starts a `dlv` process in
|
||
the background and provides various commands to communicate with it.
|
||
|
||
This debugger is similar to Visual Studio or Eclipse and has the following
|
||
features:
|
||
|
||
* Show stack trace and jumps.
|
||
* List local variables.
|
||
* List function arguments.
|
||
* Expand values of struct or array/slice.
|
||
* Show balloon on the symbol.
|
||
* Show output of stdout/stderr.
|
||
* Toggle breakpoint.
|
||
* Stack operation continue/next/step out.
|
||
|
||
This feature requires either Vim 8.0.0087 or newer with the |+job| feature or
|
||
Neovim. This features also requires Delve 1.0.0 or newer, and it is
|
||
recommended to use Go 1.10 or newer, as its new caching will speed up
|
||
recompiles.
|
||
|
||
*go-debug-intro*
|
||
GETTING STARTED WITH THE DEBUGGER~
|
||
|
||
Use |:GoDebugStart| or |:GoDebugTest| to start the debugger. The first
|
||
argument is the package name, and any arguments after that will be passed on
|
||
to the program; for example:
|
||
>
|
||
:GoDebugStart . -someflag value
|
||
<
|
||
This may take few seconds. After the code is compiled you'll see three new
|
||
windows: the stack trace on left side, the variable list on the bottom-left,
|
||
and program output at the bottom.
|
||
|
||
You can add breakpoints with |:GoDebugBreakpoint| (<F9>) and run your program
|
||
with |:GoDebugContinue| (<F5>).
|
||
|
||
The program will halt on the breakpoint, at which point you can inspect the
|
||
program state. You can go to the next line with |:GoDebugNext| (<F10>) or step
|
||
in with |:GoDebugStep| (<F11>).
|
||
|
||
The variable window in the bottom left (`GODEBUG_VARIABLES`) will display all
|
||
local variables. Struct values are displayed as `{...}`, array/slices as
|
||
`[4]`. Use <CR> on the variable name to expand the values.
|
||
|
||
The `GODEBUG_OUTPUT` window displays output from the program and the Delve
|
||
debugger.
|
||
|
||
The `GODEBUG_STACKTRACE` window can be used to jump to different places in the
|
||
call stack.
|
||
|
||
When you're done use |:GoDebugStop| to close the debugging windows and halt
|
||
the `dlv` process, or |:GoDebugRestart| to recompile the code.
|
||
|
||
*go-debug-commands*
|
||
DEBUGGER COMMANDS~
|
||
|
||
Only |:GoDebugStart| and |:GoDebugBreakpoint| are available by default; the
|
||
rest of the commands and mappings become available after starting debug mode.
|
||
|
||
*:GoDebugStart*
|
||
:GoDebugStart [pkg] [program-args]
|
||
|
||
Start the debug mode for [pkg]; this does several things:
|
||
|
||
* Setup the debug windows according to |'g:go_debug_windows'|.
|
||
* Make the `:GoDebug*` commands and `(go-debug-*)` mappings available.
|
||
|
||
The directory of the current buffer is used if [pkg] is empty. Any other
|
||
arguments will be passed to the program.
|
||
|
||
Use |:GoDebugStop| to stop `dlv` and exit debugging mode.
|
||
|
||
*:GoDebugTest*
|
||
:GoDebugTest [pkg] [program-args]
|
||
|
||
Behaves the same as |:GoDebugStart| but runs `dlv test` instead of
|
||
`dlv debug` so you can debug tests.
|
||
|
||
Use `-test.flag` to pass flags to `go test` when debugging a test; for
|
||
example `-test.v` or `-test.run TestFoo`
|
||
|
||
*:GoDebugRestart*
|
||
:GoDebugRestart
|
||
|
||
Stop the program (if running) and restart `dlv` to recompile the package.
|
||
The current window layout and breakpoints will be left intact.
|
||
|
||
*:GoDebugStop*
|
||
*(go-debug-stop)*
|
||
:GoDebugStop
|
||
|
||
Stop `dlv` and remove all debug-specific commands, mappings, and windows.
|
||
|
||
*:GoDebugBreakpoint*
|
||
*(go-debug-breakpoint)*
|
||
:GoDebugBreakpoint [linenr]
|
||
|
||
Toggle breakpoint for the [linenr]. [linenr] defaults to the current line
|
||
if it is omitted. A line with a breakpoint will have the
|
||
{godebugbreakpoint} |:sign| placed on it. The line the program is
|
||
currently halted on will have the {godebugcurline} sign.
|
||
|
||
*hl-GoDebugCurrent* *hl-GoDebugBreakpoint*
|
||
A line with a breakpoint will be highlighted with the {GoDebugBreakpoint}
|
||
group; the line the program is currently halted on will be highlighted
|
||
with {GoDebugCurrent}.
|
||
|
||
Mapped to <F9> by default.
|
||
|
||
*:GoDebugContinue*
|
||
*(go-debug-continue)*
|
||
:GoDebugContinue
|
||
|
||
Continue execution until breakpoint or program termination. It will start
|
||
the program if it hasn't been started yet.
|
||
|
||
Mapped to <F5> by default.
|
||
|
||
*:GoDebugNext*
|
||
*(go-debug-next)*
|
||
:GoDebugNext
|
||
|
||
Advance execution by one line, also called "step over" by some other
|
||
debuggers.
|
||
It will behave as |:GoDebugContinue| if the program isn't started.
|
||
|
||
Mapped to <F10> by default.
|
||
|
||
*:GoDebugStep*
|
||
*(go-debug-step)*
|
||
:GoDebugStep
|
||
|
||
Advance execution by one step, stopping at the next line of code that will
|
||
be executed (regardless of location).
|
||
It will behave as |:GoDebugContinue| if the program isn't started.
|
||
|
||
Mapped to <F11> by default.
|
||
|
||
*:GoDebugStepOut*
|
||
*(go-debug-stepout)*
|
||
|
||
:GoDebugStepOut
|
||
|
||
Run all the code in the current function and halt when the function
|
||
returns ("step out of the current function").
|
||
It will behave as |:GoDebugContinue| if the program isn't started.
|
||
|
||
*:GoDebugSet*
|
||
:GoDebugSet {var} {value}
|
||
|
||
Set the variable {var} to {value}. Example:
|
||
>
|
||
:GoDebugSet truth 42
|
||
<
|
||
This only works for `float`, `int` and variants, `uint` and variants,
|
||
`bool`, and pointers (this is a `delve` limitation, not a vim-go
|
||
limitation).
|
||
|
||
*:GoDebugPrint*
|
||
*(go-debug-print)*
|
||
:GoDebugPrint {expr}
|
||
|
||
Print the result of a Go expression.
|
||
>
|
||
:GoDebugPrint truth == 42
|
||
truth == 42 true
|
||
<
|
||
Mapped to <F6> by default, which will evaluate the <cword> under the
|
||
cursor.
|
||
|
||
*go-debug-settings*
|
||
DEBUGGER SETTINGS~
|
||
|
||
*'g:go_debug_windows'*
|
||
|
||
Controls the window layout for debugging mode. This is a |dict| with four
|
||
possible keys: "vars", "stack", "goroutines", and "out"; each of the new
|
||
windows will be created in that that order with the commands in the value. The
|
||
current window is made the only window before creating the debug windows.
|
||
|
||
A window will not be created if a key is missing or empty.
|
||
|
||
Defaults:
|
||
>
|
||
let g:go_debug_windows = {
|
||
\ 'vars': 'leftabove 30vnew',
|
||
\ 'stack': 'leftabove 20new',
|
||
\ 'goroutines': 'botright 10new',
|
||
\ 'out': 'botright 5new',
|
||
\ }
|
||
<
|
||
Show only variables on the right-hand side: >
|
||
|
||
let g:go_debug_windows = {
|
||
\ 'vars': 'rightbelow 60vnew',
|
||
\ }
|
||
<
|
||
*'g:go_debug_address'*
|
||
|
||
Server address `dlv` will listen on; must be in `hostname:port` format.
|
||
Defaults to `127.0.0.1:8181`:
|
||
>
|
||
let g:go_debug_address = '127.0.0.1:8181'
|
||
<
|
||
|
||
*'g:go_debug_log_output'*
|
||
|
||
Specifies log output options for `dlv`. Value should be a single string of
|
||
comma-separated options suitable for passing to `dlv`. An empty string (`''`)
|
||
will suppress logging entirely. Default: `'debugger,rpc'`:
|
||
>
|
||
let g:go_debug_log_output = 'debugger,rpc'
|
||
<
|
||
|
||
*'g:go_highlight_debug'*
|
||
|
||
Highlight the current line and breakpoints in the debugger.
|
||
|
||
>
|
||
let g:go_highlight_debug = 1
|
||
<
|
||
|
||
==============================================================================
|
||
FAQ TROUBLESHOOTING *go-troubleshooting*
|
||
|
||
How do I troubleshoot problems?~
|
||
|
||
One of the best ways to understand what vim-go is doing and the output from
|
||
the tools to which it delegates is to use leverage the features described in
|
||
|'g:go_debug'|.
|
||
|
||
Completion and other functions that use `gopls` don't work~
|
||
|
||
Vim-go is heavily reliant on `gopls` for completion and other functionality.
|
||
Many of the features that use `gopls` (e.g. completion, jumping to
|
||
definitions, showing identifier information, et al.) can be configured to
|
||
delegate to other tools. e.g. completion via |'omnifunc'|, |'g:go_info_mode'|
|
||
and |'g:go_def_mode'| can be set to use other tools for now (though some of
|
||
the alternatives to `gopls` are effectively at their end of life and support
|
||
for them from within vim-go may be removed soon).
|
||
|
||
I get "Unknown function: go#config#..." error when I open a Go file.~
|
||
|
||
This often happens to vim-polyglot users when new config options are added to
|
||
vim-go. Run vim-polyglot's `build` script or make sure that vim-go is loaded
|
||
before vim-polyglot.
|
||
|
||
I get "not an editor command" error when I invoke :GoXXX~
|
||
|
||
This happens if vim-go is not installed properly. Be sure you have added this
|
||
line into your vimrc:
|
||
>
|
||
filetype plugin indent on
|
||
<
|
||
|
||
I get a "command not found" error when I invoke :GoXXX~
|
||
|
||
If you try to call |:GoDef|, |:GoInfo| and get a command not found, check that
|
||
you have the binaries installed by using |:GoInstallBinaries|.
|
||
|
||
Before opening vim, check your current $PATH:
|
||
>
|
||
echo $PATH
|
||
<
|
||
After opening vim, run `:echo $PATH`, the output must be your current `$PATH`
|
||
plus `$GOPATH/bin` (the location where |:GoInstallBinaries| installed the
|
||
binaries).
|
||
|
||
*go-guru-scope*
|
||
What is the guru scope and how do I set it?~
|
||
|
||
Many vim-go commands use the `guru` commandline tool to get information. Some
|
||
`guru` commands require an expensive analysis of the source code. To still get
|
||
a reasonable amount of performance `guru` limits this analysis to a selected
|
||
list of packages. This is known as the "guru scope".
|
||
|
||
The default is to use the package the current buffer belongs to, but this may
|
||
not always be correct. For example for the file `guthub.com/user/pkg/a/a.go`
|
||
the scope will be set to `github.com/user/pkg/a`, but you probably want
|
||
`github.com/user/pkg`
|
||
|
||
Guessing what package(s) you do want is not easy so you may need to set this
|
||
manually, usually from an |autocommand|:
|
||
>
|
||
autocmd BufRead /home/martin/go/src/github.com/user/pkg/*.go
|
||
\ :GoGuruScope github.com/user/pkg
|
||
<
|
||
|
||
If you have a lot of packages with the same prefix (`github.com/user`) you can
|
||
use a single autocommand:
|
||
>
|
||
autocmd BufRead /home/martin/go/src/*.go
|
||
\ let s:tmp = matchlist(expand('%:p'),
|
||
\ '/home/martin/go/src/\(github.com/user/[^/]\+\)')
|
||
\| if len(s:tmp) > 1 | exe 'silent :GoGuruScope ' . s:tmp[1] | endif
|
||
\| unlet s:tmp
|
||
<
|
||
Also see |:GoGuruScope| and |'g:go_guru_scope'|.
|
||
|
||
|
||
Vim becomes slow while editing Go files~
|
||
|
||
The most common cause for this is using an older version of Vim that doesn't
|
||
support asynchronous jobs. |'g:go_auto_sameids'| and |'g:go_auto_type_info'|
|
||
run jobs that can cause noticable delays when used with vim74. The problem is
|
||
most pronounced on vim74, but can occur on vim8 and nvim. On vim8 and nvim,
|
||
the problem should be restricted to a short period when the first buffer in a
|
||
package is first loaded.
|
||
|
||
If you see unexpected characters rendered in the current window, the problem
|
||
is most likely due to |'g:go_auto_sameids'| or |'g:go_auto_type_info'|. First,
|
||
try using another mode for |'g:go_info_mode'|. If that doesn't work, try
|
||
disabling |'g:go_auto_sameids'| and |'g:go_auto_type_info'|.
|
||
|
||
To a lesser extent, this can be caused by `g:go_highlight_*` options. If Vim
|
||
is just slower than normal, but doesn't render unexpected characters in the
|
||
currrent window, then the problem is most likely the `g:go_highlight_*`
|
||
options. Try disabling them if you've enabled some of them.
|
||
|
||
I get errors when using GoInstallBinaries~
|
||
|
||
If you see errors like this:
|
||
>
|
||
Error installing golang.org/x/tools/cmd/goimports
|
||
<
|
||
that means your local Go setup is broken or the remote website is down. For
|
||
example sometimes code.google.com times out. To test, just execute a simple
|
||
`go get`:
|
||
>
|
||
go get golang.org/x/tools/cmd/goimports
|
||
<
|
||
You'll see a more detailed error. If this works, vim-go will work too.
|
||
|
||
|
||
I want to use a different binary name than "go", can I do this?~
|
||
|
||
There is no way to directly configure the binary name; but you can use a
|
||
wrapper script; for example if you would like to run `goapp` instead of `go`:
|
||
|
||
1. In `~/gobin/go` (remember to make it executable):
|
||
>
|
||
#!/bin/sh
|
||
# Remove gobin from PATH and run goapp.
|
||
PATH=${PATH#$HOME/gobin} goapp "$@"
|
||
<
|
||
2. Start Vim with `~/gobin` as the first `PATH` entry so it will use the
|
||
wrapper script:
|
||
>
|
||
PATH="$HOME/gobin/:$PATH" vim
|
||
<
|
||
Alternatively you you could set `$PATH` in your vimrc with an |:autocmd|.
|
||
|
||
|
||
How do I use vim-go with syntastic?~
|
||
|
||
Sometimes when using both `vim-go` and `syntastic` Vim will start lagging
|
||
while saving and opening files. The following fixes this:
|
||
>
|
||
let g:syntastic_go_checkers = ['golint', 'govet']
|
||
let g:syntastic_mode_map = { 'mode': 'active', 'passive_filetypes': ['go'] }
|
||
<
|
||
If you want to add errcheck you can use golangci-lint as a wrapper:
|
||
>
|
||
let g:syntastic_go_checkers = ['golint', 'govet', 'golangci-lint']
|
||
let g:syntastic_go_gometalinter_args = ['--disable-all', '--enable=errcheck']
|
||
let g:syntastic_mode_map = { 'mode': 'active', 'passive_filetypes': ['go'] }
|
||
<
|
||
Another issue with `vim-go` and `syntastic` is that the location list window
|
||
that contains the output of commands such as `:GoBuild` and `:GoTest` might
|
||
not appear. To resolve this:
|
||
>
|
||
let g:go_list_type = "quickfix"
|
||
<
|
||
|
||
How do I run focused ginkgo tests?~
|
||
|
||
You must set this environment variable in your `.vimrc`:
|
||
>
|
||
let $GINKGO_EDITOR_INTEGRATION = "true"
|
||
<
|
||
|
||
Using with NeoVim~
|
||
|
||
Note: Neovim currently is not a first class citizen for vim-go. You are free
|
||
to open bug, however I'm not using Neovim so it's hard for me to test it.
|
||
vim-go might not work as well in Neovim as it does in Vim. I'm happy to accept
|
||
pull requests or very detailed bug reports. If you're interested to improve
|
||
the state of Neovim in vim-go you're always welcome!
|
||
|
||
Run `:GoRun` in a new tab, horizontal split or vertical split terminal
|
||
>
|
||
au FileType go nmap <leader>rt <Plug>(go-run-tab)
|
||
au FileType go nmap <leader>rs <Plug>(go-run-split)
|
||
au FileType go nmap <leader>rv <Plug>(go-run-vertical)
|
||
<
|
||
By default new terminals are opened in a vertical split. To change it
|
||
>
|
||
let g:go_term_mode = "split"
|
||
>
|
||
|
||
How can I customize the highlighting?~
|
||
|
||
All the highlight groups used by vim-go are prefixed with `go` (e.g.
|
||
`goType`) and are defined in the files in the `syntax` directory. To change
|
||
the highlighting for any group, add a `highlight` command for the group to
|
||
your vimrc. To turn off the highlighting for any group, add `highlight link
|
||
group-name NONE` (where `group-name` is the name of the group whose highlight
|
||
you'd like to turn off) to your vimrc.
|
||
|
||
Some people may wish to highlight Go's builtins as keywords. To do so, one
|
||
should simply add `highlight link goBuiltins Keyword` to the `vimrc` file.
|
||
|
||
==============================================================================
|
||
DEVELOPMENT *go-development*
|
||
|
||
vim-go supports test files written in VimScript; the way they're run is
|
||
roughly similar to Go tests:
|
||
|
||
- A `*.vim` file has a corresponding `*_test.vim`.
|
||
- All functions starting with `Test_` are run as test.
|
||
- A test is considered to be "failed" if |v:errors| has any entries. You can
|
||
use one of the |test-functions| to set this, or append to it directly.
|
||
|
||
A simple example:
|
||
>
|
||
function Test_run_fmt()
|
||
call assert_equal(expected, actual)
|
||
...
|
||
endfunction
|
||
<
|
||
To run tests vim-go comes with three small helper scripts:
|
||
|
||
`scripts/install-vim` Install a pristine Vim to `/tmp/vim-go-test/`.
|
||
`scripts/run-vim` Run a Vim version from `/tmp/vim-go-test/`.
|
||
`scripts/test` Run all tests with a Vim from `/tmp/vim-go-test/`.
|
||
|
||
All scripts accept a Vim version as the first argument, which can be
|
||
`vim-8.0` or `nvim`. You will need to install a Vim version with
|
||
`install-vim` before you can use `run-vim` or `test`.
|
||
|
||
You can install and test all Vim versions by running `make`.
|
||
|
||
|
||
==============================================================================
|
||
DONATION *go-donation*
|
||
|
||
People have asked for this for a long time, now you can be a fully supporter
|
||
by being a patreon at: https://www.patreon.com/bhcleek
|
||
|
||
By being a patron, you are enabling vim-go to grow and mature, helping me to
|
||
invest in bug fixes, new documentation, and improving both current and future
|
||
features. It's completely optional and is just a direct way to support
|
||
vim-go's ongoing development. Thanks!
|
||
|
||
Check it out: https://www.patreon.com/bhcleek
|
||
|
||
|
||
==============================================================================
|
||
CREDITS *go-credits*
|
||
|
||
* Go Authors for official Vim plugins.
|
||
* Gocode, Godef, Golint, Guru, Goimports, Errcheck projects and authors of
|
||
those projects.
|
||
* Other vim-plugins, thanks for inspiration (vim-golang, go.vim, vim-gocode,
|
||
vim-godef).
|
||
* vim-go contributors: https://github.com/fatih/vim-go/graphs/contributors.
|
||
|
||
|
||
vim: ft=help tw=78 et ts=2 sw=2 sts=2 norl
|