diff options
Diffstat (limited to 'doc/vim-go.txt')
| -rw-r--r-- | doc/vim-go.txt | 2706 |
1 files changed, 2706 insertions, 0 deletions
diff --git a/doc/vim-go.txt b/doc/vim-go.txt new file mode 100644 index 00000000..480b4848 --- /dev/null +++ b/doc/vim-go.txt @@ -0,0 +1,2706 @@ +if !exists('g:polyglot_disabled') || index(g:polyglot_disabled, 'go') == -1 + +*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.4.0. 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://pkg.go.dev'. 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'|. + + The working directory will be the directory containing the current buffer. + + + *: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 times out 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`, `gopls`, 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`, `gopls`, 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. + + *:GoDiagnostics* +:GoDiagnostics! [packages] + + Displays the diagnostics from `gopls` for the given packages in a + |quickfix| window. The diagnostics for the current package are displayed + when no package is given. The diagnostics for all packages will be + displayed when `all` is as an argument. + + Disabled when |'g:go_diagnostics_enabled'| is not set. + + 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 window. + + *(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-type)* + +Goto type declaration/definition. Results are shown in the current window. +Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled. + + *(go-def-type-vertical)* +Goto type 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-type-split)* +Goto type declaration/definition. Results are shown in a split window. +Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled. + + *(go-def-type-tab)* +Goto type 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 + + *(go-diagnostics)* +Calls `:GoDiagnostics` + +============================================================================== +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#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_code_completion_icase'* + +Override the icase field in 'omnifunc' results. By default it is set to 0. +See 'complete-items' for details. +> + let g:go_code_completion_icase = 0 +< + + *'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. +Valid options are `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 +(e.g. |(go-build)|, |(go-run)|, etc.) and the metalinter on save. 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. When both 'g:go_imports_autosave' +and 'g:go_fmt_autosave' are enabled and both 'g:go_fmt_command' and +'g:go_imports_mode' are set to `goimports`, `goimports` will be run only once. +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 format code. Valid options are +`gofmt`, `goimports`, and `gopls`. 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', + \ } +< + *'b:go_fmt_options'* + +This option is identical to |'g:go_fmt_options'|, but a buffer-level setting. +If present, it's used instead of the global setting. By default it is not set. + +As an example, the following autocmd will configure goimports to put imports +of packages from the current module in their own group: +> + autocmd FileType go let b:go_fmt_options = { + \ 'goimports': '-local ' . + \ trim(system('{cd '. shellescape(expand('%:h')) .' && go list -m;}')), + \ } +< + *'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. This has no effect if +`g:go_fmt_command` is set to `gopls`. By default it's disabled. +> + + let g:go_fmt_experimental = 0 + +< + + *'g:go_imports_autosave'* + +Use this option to auto |:GoImports| on save. When both +'g:go_imports_autosave' and 'g:go_fmt_autosave' are enabled and both +'g:go_fmt_command' and 'g:go_imports_mode' are set to `goimports`, `goimports` +will be run only once. By default it's disabled. +> + let g:go_imports_autosave = 0 +< + *'g:go_imports_mode'* + +Use this option to define which tool is used to adjust imports. Valid options +are `goimports` and `gopls`. The buffer will not be formatted when this is set +to `gopls`. By default `goimports` is used. +> + + let g:go_imports_mode = "goimports" +< + *'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://pkg.go.dev'. +> + let g:go_doc_url = 'https://pkg.go.dev' +< + + *'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`. By default it's `gopls`. +> + let g:go_referrers_mode = 'gopls' +< + *'g:go_implements_mode'* + +Use this option to define the command to be used for |:GoImplements|. +The Implements feature in gopls is still new and being worked upon. +Valid options are `gopls` and `guru`. By default it's `guru`. +> + let g:go_implements_mode = 'guru' +< + *'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`. If any are enabled, `--disable-all` +will be sent to the metalinter. +> + 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`. If any are enabled, `--disable-all` +will be sent to the metalinter. +> + let g:go_metalinter_enabled = ['vet', 'golint', 'errcheck'] +< + *'g:go_metalinter_command'* + +Overrides the command to be executed when |:GoMetaLinter| is called. By +default it's `golangci-lint`. Valid options are `golangci-lint` and `gopls`. +When the value is `gopls`, users may want to consider setting +`g:go_gopls_staticcheck`. 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'* + +The default command used to open a new terminal for go commands such as +|:GoRun|. The default is `:vsplit`. + +Applicable to Neovim and Vim with `terminal` feature only. +> + let g:go_term_mode = "vsplit" +< + *'g:go_term_height'* + *'g:go_term_width'* + +Controls the height and width of a terminal split, respectively. By default +these are not set, meaning that the height and width are set automatically by +the editor. The height only applies to a horizontal split and width only +applies to a vertical split. + +Applicable to Neovim and Vim with `terminal` feature only. + +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'* + +Causes some types of jobs to run inside a new terminal according to +|'g:go_term_mode'|. By default it is disabled. + +Applicable to Neovim and Vim with `terminal` feature only. +> + let g:go_term_enabled = 0 +< + *'g:go_term_close_on_exit'* + +Closes the terminal after the command run in it exits when the command fails. +By default it is enabled. + +Applicable to Neovim and Vim with `terminal` feature only. + +> + 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_rename_command'* + +Use this option to define which tool is used to rename. By default `gopls` +is used. Valid options are `gorename` and `gopls`. +> + let g:go_rename_command = 'gopls' +< + *'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_gopls_enabled'* + +Specifies whether `gopls` can be used by vim-go. By default gopls is enabled. +When gopls is disabled completion will not work and other configuration +options may also need to be adjusted. + +> + let g:go_gopls_enabled = 1 +< + + *'g:go_gopls_options'* + +The commandline arguments to pass to gopls. By default, it's `-remote=auto`. +> + let g:go_gopls_options = [] +< + + *'g:go_gopls_analyses'* + +The analyses settings for `gopls`. By default, it's `v:null`. Valid map values +are `v:true` and `v:false`. +> + let g:go_gopls_analyses = v:null +< + + *'g:go_gopls_complete_unimported'* + +Specifies whether `gopls` should include suggestions from unimported packages. +When it is `v:null`, `gopls`' default will be used. By default it is +`v:null`. +> + let g:go_gopls_complete_unimported = v:null +< + + *'g:go_gopls_deep_completion'* + +Specifies whether `gopls` should use deep completion. When it is `v:null`, +`gopls`' default will be used. By default it is `v:null`. + +> + let g:go_gopls_deep_completion = v:null +< + + *'g:go_gopls_matcher'* + +Specifies how `gopls` should match for completions. Valid values are `v:null`, +`fuzzy`, and `caseSensitive`. When it is `v:null`, `gopls`' default will be +used. By default it is `v:null`. +> + let g:go_gopls_matcher = v:null +< + + *'g:go_gopls_staticcheck'* + +Specifies whether `gopls` should run staticcheck checks. When it is `v:null`, +`gopls`' default will be used. By default it is `v:null`. +> + let g:go_gopls_staticcheck = v:null +< + + *'g:go_gopls_use_placeholders'* + +Specifies whether `gopls` can provide placeholders for function parameters and +struct fields. When set, completion items will be treated as anonymous +snippets if UltiSnips is installed and configured to be used as +|'g:go_snippet_engine'|. When it is `v:null`, `gopls`' default will be used. +By default it is `v:null`. +> + let g:go_gopls_use_placeholders = v:null +< + + *'g:go_gopls_temp_modfile'* + +Specifies whether `gopls` should use a temp modfile and suggest edits rather +than modifying the ambient go.mod file. When it is `v:null`, `gopls`' default +will be used. By default it is `v:null`. +> + let g:go_gopls_temp_modfile = v:null +< + + *'g:go_gopls_local'* + +Specifies the prefix for imports that `gopls` should consider group +separately. When it is `v:null`, `gopls`' default will be used. By default it +is `v:null`. +> + let g:go_gopls_local = v:null +< + + *'g:go_diagnostics_enabled'* + +Specifies whether `gopls` diagnostics are enabled. Only the diagnostics for +the current buffer will be processed when it is not set; all others will be +ignored. By default it is disabled. +> + let g:go_diagnostics_enabled = 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_addtags_skip_unexported'* + +Sets the `skip-unexported` option for `gomodifytags` when using |:GoAddTags|. +If set it will prevent `gomodifytags` from adding tags to unexported fields: +> + type T struct { + FooBar string `json:"foo_bar"` + quz string + } +< +By default it is disabled. +> + let g:go_addtags_skip_unexported = 0 +< + *'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|, `:GoDebugTest`, and |:GoDebugBreakpoint| are available +by default. `:GoDebugContinue` becomes available after running `:GoDebugStart` +or `:GoDebugTest`. The rest of the commands and mappings become available +after executing `:GoDebugContinue`. + + *: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. + + 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). + + 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"). + + *: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 +< + + *'go:go_debug_breakpoint_sign_text'* + +Set the sign text used for breakpoints in the debugger. By default it's '>'. + +> + let g:go_debug_breakpoint_sign_text = '>' +< + +============================================================================== +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 want to disable `gopls`~ + +Vim-go's use of `gopls` can be disabled with 'g:go_gopls_enabled'. + +Some users want to do this to limit the load on their system when using vim-go +concurrently with an LSP client like vim-lsp. Instead of disabling vim-go's +use of `gopls`, you may prefer to configure vim-go to share the `gopls` +instance with other LSP plugins. 'g:go_gopls_options' can be used to configure +how vim-go starts `gopls` so that the instance can be shared with other +plugins and vim-go user's can leverage the full power of vim-go. + +I get a "Unknown function: go#config#..." error~ + +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. + +It can also happen when multiple versions of vim-go are installed and the +version loaded by Vim doesn't have a function introduced by a later version. +To see where vim-go is being loaded from run +> + :verbose function go#config#FmtAutosave +< + +The output will show the path to the `autoload/go/config.vim` that was loaded +by Vim. Make sure the root of the path to output by the command is the path +from which vim-go is expected to sourced. If it is not rooted as expected, +then there are multiple copies of vim-go installed; remove the unexpected +copies. + +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 + +endif |