ultimate-vim/sources_non_forked/vim-go/doc/vim-go.txt

*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. Troubleshooting..............................|go-troubleshooting|
  9. 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 them with `:GoInstall` or
    test them with `:GoTest` (also supports running single tests with
    `:GoTestFunc`).
  * Quickly execute your current file/files with `:GoRun`.
  * Automatic `GOPATH` detection based on the directory structure (e.g. `gb`
    projects, `godep` vendored projects).
  * Change or display `GOPATH` with `:GoPath`.
  * Create a coverage profile and display annotated source code in 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 guru, 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.
  * Go asm formatting on save.
  * 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`.
  * A async launcher for the go command is implemented for neovim, fully async
    building and testing.
  * Integrated with the neovim terminal, launch `:GoRun` and other go commands
    in their own new terminal.
  * Alternate between implementation and test code with `:GoAlternate`.

==============================================================================
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'

*  Vim |packages| (since Vim 7.4.1528)
>
    git clone https://github.com/fatih/vim-go.git \
      ~/.vim/pack/plugins/start/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 `<C-x><C-o>`, to get real-time
completion (completion by type) install:
https://github.com/Shougo/neocomplete.vim for Vim or
https://github.com/Shougo/deoplete.nvim and
https://github.com/zchee/deoplete-go for Neovim
* To get displayed source code tag informations on a sidebar install
https://github.com/majutsushi/tagbar.
* For snippet feature install:
https://github.com/Shougo/neosnippet.vim or
https://github.com/SirVer/ultisnips.
* For a better documentation viewer check out:
  https://github.com/garyburd/go-explorer

==============================================================================
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 
gd
CTRL-]

    Goto declaration/definition for the declaration under the cursor. By default
    the CTRL-] key and the mapping `gd` 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.

                                                                 *:GoDefStack*
:GoDefStack [number]

    This command Jumps to a given location in the jumpstack, retaining all
    other entries. Jumps to non-existent entries will print an informative
    message, but are otherwise a noop.

    If no argument is given, it will print out an interactive list of all
    items in the stack. Its output looks like this:

      1 /path/first/file.go|1187 col 16|AddThing func(t *Thing)
    > 2 /path/thing/thing.go|624 col 19|String() string
      3 /path/thing/thing.go|744 col 6|func Sprintln(a ...interface{}) string

    This list shows the identifiers that you jumped to and the file and cursor
    position before that jump.  The older jumps are at the top, the newer at
    the bottom.

    The '>' points to the active entry.  This entry and any newer entries
    below it will be replaced if |:GoDef| is done from this location. The
    CTRL-t and |:GoDefPop| command will jump to the position above the active
    entry.

    Jumps to non-existent entries will print an informative message, but are
    otherwise a noop.

                                                            *:GoDefStackClear*
:GoDefStackClear

    Clears the current stack list and resets it.

                                                                   *:GoDefPop*
:GoDefPop [count]
CTRL-t

    Navigate to the [count] earlier entry in the jump stack, retaining the
    newer entries. If no argument is given, it will jump to the next most
    recent entry (`:GoDefPop 1`).  If [count] is greater than the number of
    prior entries, an error will be printed and no jump will be performed.

    If you have used :GoDefPop to jump to an earlier location, and you issue
    another :GoDef command, the current entry will be replaced, and all newer
    entries will be removed, effectively resuming the stack at that location.

    By default [count]CTRL-t is enabled to invoke :GoDefPop.  Similarly,
    hitting CTRL-t without a prior count is equivalent to `:GoDefPop 1`.  See
    |'g:go_def_mapping_enabled'| to disable this.

                                                                      *:GoRun*
:GoRun[!] [expand]

    Build and run your current main package. By default all main files for the
    current file is used. If an argument is passed, [expand] is used as file
    selector. For example use `:GoRun %` to select the current file only.

    You may optionally pass any valid go run flags/options. For a full list
    please see `go help run`.

    If [!] is not given the first error is jumped to.

    If using neovim then `:GoRun` will run in a new terminal according to
    |'g:go_term_mode'|.

                                                                    *:GoBuild*
:GoBuild[!] [expand]

    Build your package with `go build`. Errors are populated in the quickfix
    window. It automatically builds only the files that depends on the current
    file. `:GoBuild` doesn't produce a result file.
    Use |:make| to create a result file.

    You may optionally pass any valid go build flags/options. For a full list
    please see `go help build`. Options are expanded with [expand].

    If [!] is not given the first error is jumped to.

    If using neovim then this command is fully async, it does not block the
    UI.

                                                                 *:GoGenerate*
:GoGenerate[!] [expand]

    Creates or updates your auto-generated source files by running `go
    generate`.

    You may optionally pass any valid go generate flags/options. For a full
    list please see `go help generate`. Options are expanded with [expand].

    If [!] is not given the first error is jumped to.

                                                                     *:GoInfo*
:GoInfo
    Show type information about the identifier under the cursor. For example
    putting it above a function call is going to show the full function
    signature. By default it uses `gocode` to get the type informations. To
    change the underlying tool from `gocode` to another tool, see
    |g:go_info_mode|.


                                                                  *:GoInstall*
:GoInstall[!] [options]

    Install your package with `go install`.

    You may optionally pass any valid go install flags/options. For a full
    list please see `go help install`.

    If [!] is not given the first error is jumped to.

                                                                     *:GoTest*
:GoTest[!] [expand]

    Run the tests on your _test.go files via in your current directory. Errors
    are populated in the quickfix window.  If an argument is passed, [expand]
    is used as file selector (useful for cases like `:GoTest ./...`).

    You may optionally pass any valid go test flags/options. For a full list
    please see `go help test`.

    GoTest timesout automatically after 10 seconds. To customize the timeout
    use |'g:go_test_timeout'|. This feature is disabled if any arguments are
    passed to the `:GoTest` command.

    If [!] is not given the first error is jumped to.

    If using neovim `:GoTest` will run in a new terminal or run asynchronously
    in the background according to |'g:go_term_enabled'|. You can set the mode
    of the new terminal with |'g:go_term_mode'|.

                                                                 *:GoTestFunc*
:GoTestFunc[!] [expand]

    Runs :GoTest, but only on the single test function immediate to your
    cursor using 'go test's '-run' flag.

    Lookup is done starting at the cursor (including that line) moving up till
    a matching `func Test` pattern is found or top of file is reached. Search
    will not wrap around when at the top of the file.

    If [!] is not given the first error is jumped to.

    If using neovim `:GoTestFunc` will run in a new terminal or run
    asynchronously in the background according to |'g:go_term_enabled'|. You
    can set the mode of the new terminal with |'g:go_term_mode'|.

                                                              *:GoTestCompile*
:GoTestCompile[!] [expand]

    Compile your _test.go files via in your current directory. Errors are
    populated in the quickfix window.  If an argument is passed, [expand] is
    used as file selector (useful for cases like `:GoTest ./...`). Useful to
    not run the tests and capture/fix errors before running the tests or to
    create test binary.

    If [!] is not given the first error is jumped to.

    If using neovim `:GoTestCompile` will run in a new terminal or run
    asynchronously in the background according to |'g:go_term_enabled'|. You
    can set the mode of the new terminal with |'g:go_term_mode'|.

                                                                 *:GoCoverage*
:GoCoverage[!] [options]

    Create a coverage profile and annotates the current file's source code. If
    called again it rerurns the tests.

    If [!] is not given the first error is jumped to.

                                                           *:GoCoverageToggle*
:GoCoverageToggle[!] [options]

    Create a coverage profile and annotates the current file's source code. If
    called again clears the annotation (works as a toggle).

    If [!] is not given the first error is jumped to.

                                                            *:GoCoverageClear*
:GoCoverageClear [options]

   Clears the coverage annotation.


                                                          *:GoCoverageBrowser*
:GoCoverageBrowser[!] [options]

    Create a coverage profile and open a browser to display the annotated
    source code of the current package.

    You may optionally pass any valid go test flags/options, such as
    `-covermode set,count,atomic`. For a full list please see `go help test`.

    If [!] is not given the first error is jumped to.

                                                                 *:GoErrCheck*
:GoErrCheck [options]

    Check for unchecked errors in you current package. Errors are populated in
    the quickfix window.

    You may optionally pass any valid errcheck flags/options. 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`. Set
    |'g:go_get_update'| to disable updating dependencies.

                                                           *: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 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] [pattern2] ... [patternN]

    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.

                                                                  *: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 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.

                                                                  *: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 'updatetime'). If
    disabled it clears and stops automatic highlighting.

                                                               *:GoMetaLinter*
:GoMetaLinter [path]

    Calls the underlying `gometalinter` 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.

                                                                 *: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 guru, gorenate,
    etc.. 

    The build tags is cleared (unset) if `""` is given. If no arguments is
    given it prints the current custom 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
<
                                                                *: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]

    Only enabled if `ctrlp.vim` is installed. If run shows all function and
    type declarations for the current file. If [file] is non empty it parses
    the given file.
    By default `type` and `func` declarations are shown. This can be changed
    via |'g:go_decls_includes'|.

                                                                 *:GoDeclsDir*
:GoDeclsDir [dir]

    Only enabled if `ctrlp.vim` is installed. If run shows all function and
    type declarations for the current directory. If [dir] is given it parses
    the given directory.

                                                                     *: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 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 exising 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] ...

    Rmove 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'|.

                                                     *:GoAsmFmtAutoSaveToggle*
:GoAsmFmtAutoSaveToggle

    Toggles |'g:go_asmfmt_autosave'|.

                                                 *:GoMetaLinterAutoSaveToggle*
:GoMetaLinterAutoSaveToggle

    Toggles |'g:go_metalinter_autosave'|.

                                                 *:GoTemplateAutoCreateToggle*
:GoTemplateAutoCreateToggle

    Toggles |'g:go_template_autocreate'|.


==============================================================================
MAPPINGS                                                        *go-mappings*

vim-go has several <Plug> keys which can be used to create custom mappings
For example, to create a mapping that `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 agains it acts as a toggle and clears the
annotation.

                                                                *(go-imports)*

Calls `goimports` for the current package

                                                                   *(go-lint)*

Calls `golint` for the current package

                                                                    *(go-vet)*

Calls `go vet` for the current package


                                                                  *(go-files)*

Show source files that depends for the current package


                                                                   *(go-deps)*

Show dependencies for the current package

                                                                    *(go-doc)*

Show the relevant GoDoc for the word under the cursor in a split window
leftabove (default mode).

                                                              *(go-doc-split)*

Show the relevant GoDoc for the word under the cursor in a split window.


                                                           *(go-doc-vertical)*

Show the relevant GoDoc for the word under the cursor in a vertical split
window.

                                                                *(go-doc-tab)*

Show the relevant GoDoc for the word under the cursor in a tab window.


                                                            *(go-doc-browser)*

Show the relevant GoDoc for the word under in browser

                                                                    *(go-def)*

Goto declaration/definition. Results are shown in the current buffer.

                                                              *(go-def-split)*

Goto declaration/definition. Results are shown in a split window.
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.

                                                           *(go-def-vertical)*

Goto declaration/definition. Results are shown in a vertical split window.
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.

                                                                *(go-def-tab)*

Goto declaration/definition. Results are shown in a tab window.
Jumps to an existing buffer if |'g:go_def_reuse_buffer'| is enabled.

                                                              *(go-def-stack)*

Shows the godef tag stack

                                                        *(go-def-stack-clear)*

Resets and clears the tag stack

                                                                *(go-def-pop)*

Jump to previous entry in the tag stack

                                                             *(go-implements)*

Show the interfaces that the type under the cursor implements.

                                                                 *(go-rename)*

Rename the identifier under the cursor to the desired new name

                                                                *(go-callees)*

Show the call targets for the type under the cursor

                                                                *(go-callers)*

Show possible callers of selected function

                                                               *(go-describe)*

Describe selected syntax: definition, methods, etc

                                                              *(go-callstack)*

Show path from callgraph root to selected function

                                                               *(go-freevars)*

Show free variables of selection

                                                           *(go-channelpeers)*

Show send/receive corresponding to selected channel op

                                                              *(go-referrers)*

Show all refs to entity denoted by selected identifier

                                                             *(go-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


==============================================================================
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.

                                               *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


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 statusline's will show
`success`, if you it fails all file's statusline 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. This function is also used for |'g:go_auto_type_info'|.

==============================================================================
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. 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
`gocode` is being used as it's the fastest option. But one might also use
`guru` as it's covers more cases and is more accurate.  Current valid options
are: `[gocode, guru]` >

  let g:go_info_mode = 'gocode'
<
                                                         *'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 a custom 'updatetime' for Go source files. If
set to 0, no custom time will be configured. By default it's set to 800ms.
>
  let g:go_updatetime = 800
<
                                                        *'g:go_jump_to_error'*

Use this option to enable/disable passing the bang attribute to the mappings
|(go-build)|, |(go-run)|, etc..  When enabled it will jump to the first error
automatically (means it will NOT pass the bang attribute to the appropriate
command, i.e: (go-run) -> :GoRun ). Note, that calling this doesn't have any
affect on calling the commands manually. This setting is only useful for
changing the behaviour of our custom static mappings. By default it's enabled.
>
  let g:go_jump_to_error = 1
<
                                                         *'g:go_fmt_autosave'*

Use this option to auto |:GoFmt| on save. By default it's enabled >

  let g:go_fmt_autosave = 1
<
                                                          *'g:go_fmt_command'*

Use this option to define which tool is used to gofmt. By default `gofmt` is
used >

  let g:go_fmt_command = "gofmt"
<
                                                          *'g:go_fmt_options'*

Use this option to add additional options to the |'g:go_fmt_command'|. 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 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 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 run `godoc` on words under the cursor with the default K ,
keywordprg shortcut. Usually this shortcut is set to use the program `man`. In
Go, using `godoc` is more idiomatic. Default is enabled. >

  let g:go_doc_keywordprg_enabled = 1
<
                                                             *'g:go_def_mode'*

Use this option to define the command to be used for |:GoDef|. By default
`guru` is being used as it covers all edge cases. But one might also use
`godef` as it's more faster. Current valid options are: `[guru, godef]` >

  let g:go_def_mode = 'guru'
<
                                                  *'g:go_def_mapping_enabled'*

Use this option to enable/disable the default mapping of CTRL-] 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_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_snippet_case_type'*

Use this option to define the default conversion type of snippet expansion for
field tags. For the following case, if `snakecase` is used the `json` snippet
will expand 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"].
>
  let g:go_snippet_case_type = "snakecase"
<
                                                           *'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"]` By default it's not
set, so the relevant commands defaults are being used.
>
  let g:go_guru_scope = []
<
                                                           *'g:go_build_tags'*

These options that will be automatically passed to the `-tags` option of
various tools, such as `guru`, `gorename`, etc... This is a permanatent
setting. A more useful way is to use |:GoBuildTags| to dynamically change or
remove build tags. By default it's not set.
>
  let g:go_build_tags = ''
<
                                     *'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 doesn'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_types'*

Highlights struct and interface names. By default it's disabled. >

  let g:go_highlight_types = 0
<
                                                     *'g:go_highlight_fields'*

Highlights field names. By default it's disabled. >

  let g:go_highlight_fields = 0
<
                                          *'g:go_highlight_build_constraints'*

Highlights build constraints. By default it's disabled. >

  let g:go_highlight_build_constraints = 0
<
                                          *'g:go_highlight_generate_tags'*

Highlights go:generate directives. By default it's disabled. >

  let g:go_highlight_generate_tags = 0
<
                                          *'g:go_highlight_string_spellcheck'*

Use this option to highlight spelling errors in strings when |spell| is
also enabled. By default it's enabled. >

  let g:go_highlight_string_spellcheck = 1
<
                                             *'g:go_highlight_format_strings'*

Use this option to highlight printf-style operators inside string literals.
By default it's enabled. >

  let g:go_highlight_format_strings = 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_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_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 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_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. 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_asmfmt_autosave'*

Use this option to auto |:AsmFmt| on save. By default it's disabled. >

  let g:go_asmfmt_autosave = 0
<
                                                            *'g:go_term_mode'*

This option is Neovim only. Use it to change the default command used to
open a new terminal for go commands such as |:GoRun|.
The default is vsplit.
>
  let g:go_term_mode = "vsplit"
<
                                                          *'g:go_term_height'*
                                                           *'g:go_term_width'*

These options are Neovim only. Use them to control the height and width of
a terminal split. By default these are not set, meaning that the height and
width are set automatically by Neovim. The height only applies to a
horizontal split and width only applies to a vertical split.

For example here is how to set each to 30.
>
  let g:go_term_height = 30
  let g:go_term_width = 30
<
                                                         *'g:go_term_enabled'*

This option is Neovim only. Use it to change the behavior of the test
commands. If set to 1 it opens the test commands inside a new terminal
according to |'g:go_term_mode'|, otherwise it will run them in the background
just like `:GoBuild`. By default it is disabled.
>
  let g:go_term_enabled = 0
<
                                                       *'g:go_alternate_mode'*

Specifies the command that |:GoAlternate| uses to open the alternate file.
By default it is set to edit.
>
  let g:go_alternate_mode = "edit"
<
                                                     *'g:go_gorename_prefill'*

Specifies whether |:GoRename| prefills the new identifier name with the
word under the cursor. By default it is enabled.
>
  let g:go_gorename_prefill = 1
<
                                                     *'g:go_gocode_autobuild'*

Specifies whether `gocode` should automatically build out-of-date packages
when their source fields are modified, in order to obtain the freshest
autocomplete results for them.  By default it is enabled.
>
  let g:go_gocode_autobuild = 1
<
                                              *'g:go_gocode_propose_builtins'*

Specifies whether `gocode` should add built-in types, functions and constants
to an autocompletion proposals. By default it is enabled.
>
  let g:go_gocode_propose_builtins = 1
<
                                              *'g:go_gocode_unimported_packages'*

Specifies whether `gocode` should include suggestions from unimported packages.
By default it is disabled.
>
  let g:go_gocode_unimported_packages = 0
<

                                                   *'g:go_gocode_socket_type'*

Specifies whether `gocode` should use a different socket type. By default
`unix` is enabled. Possible values: `unix`, `tcp`
>
  let g:go_gocode_socket_type = 'unix'
<
                                                  *'g:go_template_autocreate'*

When a new Go file is created, vim-go automatically fills the buffer content
with a Go code template. By default the template under
`templates/hello_world.go` is used. This can be changed with the
|'g:go_template_file'| setting.

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 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.
>
  let g:go_template_file = "hello_world.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` is installed. This sets which declarations to show
for |:GoDecls|.  It is a Comma delimited list Possible options are:
{func,type}.  The default is: >

      let g:go_decls_includes = 'func,type'
<
                                                       *'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 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'*

Specifices 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
<
==============================================================================
TROUBLESHOOTING                                         *go-troubleshooting*

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).


Vim becomes slow while editing Go files~

Don't enable these options:
>
  let g:go_highlight_types = 0
  let g:go_highlight_operators = 0
<

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.


==============================================================================
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:et:ts=2:sw=2:sts=2:norl