*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. Settings.....................................|go-settings| 7. Troubleshooting..............................|go-troubleshooting| 8. Credits......................................|go-credits| =============================================================================== INTRO *go-intro* Go (golang) support for Vim. vim-go installs automatically all necessary binaries for providing seamless Vim integration. It comes with pre-defined sensible settings (like auto gofmt on save), has autocomplete, snippet support, improved syntax highlighting, go toolchain commands, etc... It's highly customizable and each individual feature can be disabled/enabled easily. * Improved Syntax highlighting with items such as Functions, Operators, Methods. * Auto completion support via `gocode` * Better `gofmt` on save, which keeps cursor position and doesn't break your undo history * Go to symbol/declaration with `:GoDef` * Look up documentation with `:GoDoc` inside Vim or open it in browser * Automatically import packages via `:GoImport` or plug it into autosave * Compile your package with `:GoBuild`, install it with `:GoInstall` or test them with `:GoTest` (also supports running single tests via `:GoTestFunc`) * Quickly execute your current file/files with `:GoRun` * Automatic `GOPATH` detection based on the directory structure (i.e. `gb` projects, `godep` vendored projects) * Change or display `GOPATH` with `:GoPath` * Create a coverage profile and display annotated source code in browser to see which functions are covered with `:GoCoverage` * Call `gometalinter` with `:GoMetaLinter`, which invokes all possible linters (golint, vet, errcheck, deadcode, etc..) and shows the warnings/errors * Lint your code with `:GoLint` * Run your code through `:GoVet` to catch static errors * Advanced source analysis tools utilizing oracle, such as `:GoImplements`, `:GoCallees`, and `:GoReferrers` * Precise type-safe renaming of identifiers with `:GoRename` * List all source files and dependencies * Unchecked error checking with `:GoErrCheck` * Integrated and improved snippets, supporting `ultisnips` or `neosnippet` * Share your current code to [play.golang.org](http://play.golang.org) with `:GoPlay` * On-the-fly type information about the word under the cursor. Plug it into your custom vim function. * Tagbar support to show tags of the source code in a sidebar with `gotags` * Custom vim text objects such as `a function` or `inner function` * All commands support collecting and displaying errors in Vim's location list. =============================================================================== INSTALL *go-install* Vim-go follows the standard runtime path structure, so I highly recommend to use a common and well known plugin manager to install vim-go. Do not use vim-go with other Go plugins. For Pathogen just clone the repo, for other plugin managers add the appropriate lines and execute the plugin's install command. * 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' < * https://github.com/Shougo/neobundle.vim > NeoBundle 'fatih/vim-go' < * https://github.com/gmarik/vundle > Plugin 'fatih/vim-go' < * Manual > Copy all of the files into your `~/.vim` directory < Please be sure all necessary binaries are installed (such as `gocode`, `godef`, `goimports`, etc..). You can easily install them with the included |GoInstallBinaries| command. If you invoke it, all necessary binaries will be automatically downloaded and installed to your `$GOBIN` environment (if not set it will use `$GOPATH/bin`). It requires `git` for fetching the individual Go packages. * Autocompletion is enabled by default via ``, to get real-time completion (completion by type) install: https://github.com/Valloric/YouCompleteMe or https://github.com/Shougo/neocomplete.vim * To get displayed source code tag informations on a sidebar install https://github.com/majutsushi/tagbar. * For snippet feature install: https://github.com/SirVer/ultisnips or https://github.com/Shougo/neosnippet.vim. =============================================================================== COMMANDS *go-commands* *: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 current Go file, or for given packages. *: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. *: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 tool vet flags/options. In this case, `go tool vet` is run in place of `go vet`. For a full list please see `go tool vet -h`. If [!] is not given the first error is jumped to. *:GoDef* :GoDef [identifier] Goto declaration/definition for the given [identifier]. If no argument is given, it will jump to the declaration under the cursor. By default the mapping `gd` is enabled to invoke GoDef for the identifier under the cursor. See |g:go_def_mapping_enabled| to disable it. *: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. *:GoBuild* :GoBuild[!] [expand] Build your package with `go build`. 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. *: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. It uses gocode to get the type informations. *: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 location list. 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. *: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. *:GoTestCompile* :GoTestCompile[!] [expand] Compile your _test.go files via in your current directory. Errors are populated in location list. 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. *:GoCoverage* :GoCoverage[!] [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 location list. You may optionally pass any valid errcheck flags/options. For a full list please see `errcheck -h`. *:GoFiles* :GoFiles Show source files that depends for the current package *:GoDeps* :GoDeps Show dependencies for the current package *:GoInstallBinaries* :GoInstallBinaries Download and Install all necessary Go tool binaries such as `godef`, `goimports`, `gocode`, etc.. under `g:go_bin_path` *:GoUpdateBinaries* :GoUpdateBinaries Download and Update previously installed Go tool binaries such as `godef`, `goimports`, `gocode`, etc.. under `g:go_bin_path`. This can be used to update the necessary Go binaries. *: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 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. *:GoOracleScope* :GoOracleScope [path1] [path2] ... Changes the custom |g:go_oracle_scope| setting and overrides it with the given import paths. The custom scope is cleared (unset) if `""` is given as the only path. If no arguments is given it prints the current custom 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 oracle 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 showed 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 if you’re 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, within any package in the analysis scope. *:GoMetaLinter* :GoMetaLinter [path] Calls the underlying `gometalinter` tool and displays all warnings and errors in a location list. By default the following linters are enabled: "'vet', 'golint', '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. *:GoOracleTags* :GoOracleTags [tags] Changes the custom |g:go_oracle_tags| setting and overrides it with the given build tags. This command cooperate with GoReferrers command when there exist mulitiple build tags in your project,then you can set one of the build tags for GoReferrers to find more accurate. The custom build tags is cleared (unset) if `""` is given. If no arguments is given it prints the current custom build tags. =============================================================================== MAPPINGS *go-mappings* vim-go has several keys which can be used to create custom mappings For example, to create a mapping that `go run` the current file create a mapping for the `(go-run)`: > au FileType go nmap r (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 keys are: *(go-run)* Calls `go run` for the current file *(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 *(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. *(go-def-vertical)* Goto declaration/definition. Results are shown in a vertical split window. *(go-def-tab)* Goto declaration/definition. Results are shown in a tab window. *(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-metalinter)* Calls `go-metalinter` for the current directory =============================================================================== 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. *go-v_if* *go-if* if "inside a function", select contents of a function, excluding the function definition and the closing bracket. =============================================================================== SETTINGS *go-settings* *'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'* Use this option to change the browser that is used to open the snippet url posted to play.golang.org with |:GoPlay| or for the relevant documentation used with |:GoDocBrowser|. 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 > let g:go_auto_type_info = 0 < *'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|. Default is empty. > let g:go_fmt_options = '' < *'g:go_fmt_fail_silently'* Use this option to disable showing a location list when |g:go_fmt_command| fails. By default it's disabled. > 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 slows (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_doc_keywordprg_enabled'* Use this option to change the enable GoDoc to run on words under the cursor with the default K , keywordprg shortcut. This shortcut is by default set to use the program man. However in go using godoc is more idiomatic. Default is enabled. > let g:go_doc_keywordprg_enabled = 1 < *'g:go_def_mapping_enabled'* Use this option to enabled/ disable the default mapping (`gd`) for GoDef enabled. Disabling it allows you to map something else to the mapping `gd`. Default is enabled. > let g:go_def_mapping_enabled = 1 < *'g:go_dispatch_enabled'* Use this option to enable/disable the use of Dispatch to execute the `:GoRun`, `:GoBuild` and `:GoGenerate` commands. More information about Dispatch is available at https://github.com/tpope/vim-dispatch. Default is disabled. > let g:go_dispatch_enabled = 0 < *'g:go_doc_command'* Use this option to define which tool is used to godoc. By default `godoc` is used > let g:go_doc_command = "godoc" < *'g:go_doc_options'* Use this option to add additional options to the |g:go_doc_command|. Default is empty. > let g:go_doc_options = '' < *'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_snippet_engine'* Use this option to define the default snippet engine. By default "ultisnips" is used. Use "neosnippet" for neosnippet.vim: > let g:go_snippet_engine = "ultisnips" < *'g:go_oracle_scope'* Use this option to define the scope of the analysis to be passed for Oracle related commands, such as |GoImplements|, |GoCallers|, etc.. By default it's not set, so only the current packages go files are passed as scope. You can change it on-the-fly with |GoOracleScope|. For more info please have look at Oracle's User Manual: https://docs.google.com/document/d/1SLk36YRjjMgKqe490mSRzOPYEDe0Y_WQNRv-EiFYUyw/view#heading=h.nwso96pj07q8 > let g:go_oracle_scope = '' < *'g:go_highlight_array_whitespace_error'* Highlights white space after "[]". > let g:go_highlight_array_whitespace_error = 1 < *'g:go_highlight_chan_whitespace_error'* Highlights white space around the communications operator that don't follow the standard style. > let g:go_highlight_chan_whitespace_error = 1 < *'g:go_highlight_extra_types'* Highlights commonly used library types (io.Reader, etc.). > let g:go_highlight_extra_types = 1 < *'g:go_highlight_space_tab_error'* Highlights instances of tabs following spaces. > let g:go_highlight_space_tab_error = 1 < *'g:go_highlight_trailing_whitespace_error'* Highlights trailing white space. > let g:go_highlight_trailing_whitespace_error = 1 < *'g:go_highlight_operators'* Highlights operators such as `:=` , `==`, `-=`, etc ...By default it's disabled. > let g:go_highlight_operators = 0 < *'g:go_highlight_functions'* Highlights function names. By default it's disabled. > let g:go_highlight_functions = 0 < *'g:go_highlight_methods'* Highlights method names. By default it's disabled. > let g:go_highlight_methods = 0 < *'g:go_highlight_structs'* Highlights struct names. By default it's disabled. > let g:go_highlight_structs = 0 < *'g:go_highlight_build_constraints'* Highlights build constraints. By default it's disabled. > let g:go_highlight_build_constraints = 0 < *'g:go_highlight_string_spellcheck* Specifies spell checking enabled for strings. Spelling errors are highlighted if |spell| is enabled. By default it's enabled. > let g:go_highlight_string_spellcheck = 1 < *'g:go_autodetect_gopath'* Automatically modifies GOPATH for certain directory structures, such as for the tool godep which has his own dependencies via 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` is supported, in the near future more tool supports will be added. By default it's enabled. > let g:go_autodetect_gopath = 1 < *'g:go_textobj_enabled'* Adds custom text objects. By default it's enabled. > let g:go_textobj_enabled = 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 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 currently enabled linters for the |GoMetaLinter| command. By default it's using `vet`, `golint` and `errcheck` > let g:go_metalinter_enabled = ['vet', 'golint', 'errcheck'] < *'g:go_metalinter_command'* Overrides the command to be executed when |GoMetaLinter| is called. This is an advanced settings and is for users who want to have a complete control over of how `gometalinter` should be executed. By default it's empty. > let g:go_metalinter_command = "" < *'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_loclist_height'* Specifies the current location list height for all location lists. The default value (empty) sets automatically the height to the number of errors (maximum up to 10 errors to prevent large heights). Setting the value explicitly overrides this behavior. To get default Vim behavior set it to 10. > let g:go_loclist_height = 0 =============================================================================== TROUBLESHOOTING *go-troubleshooting* I'm using Fish shell but have some problems using vim-go~ First environment variables in Fish are applied differently, it should be like: > set -x GOPATH /your/own/gopath < Second, Vim needs a POSIX compatible shell (more info here: https://github.com/dag/vim-fish#teach-a-vim-to-fish). If you use Fish to open Vim, it will make certain shell based commands fail (means vim-go will fail too). To overcome this problem change the default shell by adding the following into your .vimrc (on the top of the file): > if $SHELL =~ 'fish' set shell='/bin/sh' endif < or > set shell='/bin/sh' > I'm seeing weird errors during installation of binaries with GoInstallBinaries: If you see errors like this: > Error installing code.google.com/p/go.tools/cmd/goimports: Error installing code.google.com/p/rog-go/exp/cmd/godef: < 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 code.google.com/p/go.tools/cmd/goimports < You'll see a more detailed error. If this works, vim-go will work too. =============================================================================== CREDITS *go-credits* * Go Authors for official vim plugins * Gocode, Godef, Golint, Oracle, 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:et:ts=2:sw=2:sts=2:norl