This project is not maintained anymore and is archived. Feel free to fork and
make your own changes if needed. For more detail read my blog post: Taking an indefinite sabbatical from my projects
Thanks to everyone for their valuable feedback and contributions.
vim-go-tutorial
Tutorial for vim-go. A simple tutorial on how to install and use vim-go.
We're going to use vim-plug to install vim-go. Feel free to use other plugin
managers instead. We will create a minimal ~/.vimrc, and add to it as we go along.
First fetch and install vim-plug along with vim-go:
Or open Vim and execute :GoInstallBinaries. This is a vim-go command that
installs all vim-go dependencies for you. It doesn't download pre compiled
binaries, instead it calls go get under the hood, so the binaries are all
compiled in your host machine (which is both safe and simplifies the
installation process as we don't need to provide binaries for multiple
platforms). If you already have some of the dependencies (such as guru,
goimports) call :GoUpdateBinaries to update the binaries.
For the tutorial, all our examples will be under
GOPATH/src/github.com/fatih/vim-go-tutorial/. Please be sure you're inside
this folder. This will make it easy to follow the
tutorial. If you already have a GOPATH set up just execute:
go get github.com/fatih/vim-go-tutorial
Or create the folder, if necessary.
Hello World!
Open the main.go file from your terminal:
vim main.go
It's a very basic file that prints vim-go to stdout.
Run it
You can easily run the file with :GoRun %. Under the hood it calls go run for
the current file. You should see that it prints vim-go.
For whole package run with :GoRun.
Build it
Replace vim-go with Hello Gophercon. Let us compile the file instead of running it.
For this we have :GoBuild. If you call it, you should see this message:
vim-go: [build] SUCCESS
Under the hood it calls go build, but it's a bit smarter. It does a couple of
things differently:
No binaries are created; you can call :GoBuild multiple times without
polluting your workspace.
It automatically cds into the source package's directory
It parses any errors and shows them inside a quickfix list
It automatically detects the GOPATH and modifies it if needed (detects
projects such as gb, Godeps, etc..)
Runs async if used within Vim 8.0.xxx or NeoVim
Fix it
Let's introduce two errors by adding two compile errors:
varb=foo()
funcmain() {
fmt.Println("Hello GopherCon")
a
}
Save the file and call :GoBuild again.
This time the quickfix view will be opened. To jump between the errors you can
use :cnext and :cprevious. Let us fix the first error, save the
file and call :GoBuild again. You'll see the quickfix list is updated with a
single error. Remove the second error as well, save the file and call
:GoBuild again. Now because there are no more errors, vim-go automatically
closes the quickfix window for you.
Let us improve it a little bit. Vim has a setting called autowrite that
writes the content of the file automatically if you call :make. vim-go also
makes use of this setting. Open your .vimrc and add the following:
set autowrite
Now you don't have to save your file anymore when you call :GoBuild. If we
reintroduce the two errors and call :GoBuild, we can now iterate much more
quickly by only calling :GoBuild.
:GoBuild jumps to the first error encountered. If you don't want to jump
append the ! (bang) sign: :GoBuild!.
In all the go commands, such as :GoRun, :GoInstall, :GoTest, etc..,
whenever there is an error the quickfix window always will pop up.
vimrc improvements
You can add some shortcuts to make it easier to jump between errors in quickfix
list:
There are two types of error lists in Vim. One is called location list the
other quickfix. Unfortunately the commands for each lists are different. So
:cnext only works for quickfix list, for location lists you have to use
:lnext. Some of the commands in vim-go open a location list, because
location lists are associated with a window and each window can have a
separate list. This means you can have multiple windows, and multiple
location lists, one for Build, one for Check, one for Tests, etc..
Some people prefer to use only quickfix though. If you add the following to
your vimrc all lists will be of type quickfix:
letg:go_list_type="quickfix"
Test it
Let's write a simple function and a test for the function. Add the following:
funcBar() string {
return"bar"
}
Open a new file called main_test.go (it doesn't matter how you open it, from
inside Vim, a separate Vim session, etc.. it's up to you). Let us use the
current buffer and open it from Vim via :edit main_test.go.
When you open the new file you notice something. The file automatically has the
package declaration added:
package main
This is done by vim-go automatically. It detected that the file is inside a
valid package and therefore created a file based on the package name (in our
case the package name was main). If there are no files, vim-go automatically
populates the content with a simple main package.
Update the test file with the following code:
package main
import (
"testing"
)
funcTestBar(t*testing.T) {
result:=Bar()
ifresult!="bar" {
t.Errorf("expecting bar, got %s", result)
}
}
Call :GoTest. You'll see the following message:
vim-go: [test] PASS
:GoTest calls go test under the hood. It has the same improvements
we have for :GoBuild. If there is any test error, a quickfix list is
opened again and you can jump to it easily.
Another small improvement is that you don't have to open the test file itself.
Try it yourself: open main.go and call :GoTest. You'll see the tests will
be run for you as well.
:GoTest times out after 10 seconds by default. This is useful because Vim is
not async by default. You can change the timeout value with let g:go_test_timeout = '10s'
We have two more commands that make it easy to deal with test files. The first
one is :GoTestFunc. This only tests the function under your cursor.
Let us change the content of the test file (main_test.go) to:
Now when we call :GoTest a quickfix window will open with two errors.
However if go inside the TestBar function and call :GoTestFunc, you'll see
that our test passes! This is really useful if you have a lot of tests that
take time and you only want to run certain tests.
The other test-related command is :GoTestCompile. Tests not only need to
pass with success, they must compile without any problems.
:GoTestCompile compiles your test file, just like :GoBuild and opens a
quickfix if there are any errors. This however doesn't run the tests. This
is very useful if you have a large test which you're editing a lot. Call
:GoTestCompile in the current test file, you should see the following:
vim-go: [test] SUCCESS
vimrc improvements
As with :GoBuild we can add a mapping to easily call :GoTest with a key
combination. Add the following to your .vimrc:
autocmdFileTypegonmap<leader>t<Plug>(go-test)
Now you can easily test your files via <leader>t
Let's make building Go files simpler. First, remove the following mapping we added
previously:
autocmdFileTypegonmap<leader>b<Plug>(go-build)
We're going to add an improved mapping. To make it seamless for
any Go file we can create a simple Vim function that checks the type of the Go
file, and executes :GoBuild or :GoTestCompile. Below is the helper function
you can add to your .vimrc:
" run :GoBuild or :GoTestCompile based on the go filefunction!s:build_go_files()
letl:file=expand('%')
ifl:file=~# '^\f\+_test\.go$'callgo#test#Test(0, 1)
elseifl:file=~# '^\f\+\.go$'callgo#cmd#Build(0)
endifendfunctionautocmdFileTypegonmap<leader>b :<C-u>call<SID>build_go_files()<CR>
Now whenever you hit <leader>b it'll build either your Go file or it'll
compile your test files seamlessly.
By default the leader shortcut is defined as: \ I've mapped my leader to
, as I find it more useful with the following setting (put this in the
beginning of .vimrc):
let mapleader =","
So with this setting, we can easily build any test and non test files with ,b.
Cover it
Let's dive further into the world of tests. Tests are really important. Go
has a really great way of showing the coverage of your source code. vim-go
makes it easy to see the code coverage without leaving Vim in a very elegant
way.
Let's first change our main_test.go file back to:
package main
import (
"testing"
)
funcTestBar(t*testing.T) {
result:=Bar()
ifresult!="bar" {
t.Errorf("expecting bar, got %s", result)
}
}
Now let us call :GoCoverage. Under the hood this calls go test -coverprofile tempfile. It parses the lines from the profile and then dynamically changes
the syntax of your source code to reflect the coverage. As you see, because we
only have a test for the Bar() function, that is the only function that is
green.
To clear the syntax highlighting you can call :GoCoverageClear. Let us add a
test case and see how the coverage changes. Add the following to main_test.go:
If we call :GoCoverage again, you'll see that the Quz function is now
tested as well and that it has a larger coverage. Call :GoCoverageClear again
to clear the syntax highlighting.
Because calling :GoCoverage and :GoCoverageClear are used a lot together,
there is another command that makes it easy to call and clear the result. You
can also use :GoCoverageToggle. This acts as a toggle and shows the coverage,
and when called again it clears the coverage. It's up to your workflow how you
want to use them.
Finally, if you don't like vim-go's internal view, you can also call
:GoCoverageBrowser. Under the hood it uses go tool cover to create a HTML
page and then opens it in your default browser. Some people like this more.
Using the :GoCoverageXXX commands does not create any kind of temporary files
and doesn't pollute your workflow. So you don't have to deal with removing
unwanted files every time.
With this you can easily call :GoCoverageToggle with <leader>c
Edit it
Imports
Let us start with a sample main.go file:
package main
import"fmt"funcmain() {
fmt.Println("gopher" )
}
Let's start with something we know already. If we save the file, you'll see that
it'll be formatted automatically. It's enabled by default but can be disabled
if desired (not sure why you would though :)) with let g:go_fmt_autosave = 0.
Optionally we also provide :GoFmt command, which runs gofmt under the hood.
Let's print the "gopher" string in all uppercase. For it we're going to use
the strings package. Change the definition to:
fmt.Println(strings.ToUpper("gopher"))
When you build it you'll get an error of course:
main.go|8| undefined: strings in strings.ToUpper
You'll see we get an error because the strings package is not imported. vim-go
has a couple of commands to make it easy to manipulate the import declarations.
We can easily go and edit the file, but instead we're going to use the Vim
command :GoImport. This command adds the given package to the import path.
Run it via: :GoImport strings. You'll see the strings package is being
added. The great thing about this command is that it also supports
completion. So you can just type :GoImport s and hit tab.
We also have :GoImportAs and :GoDrop to edit the import paths.
:GoImportAs is the same as :GoImport, but it allows changing the package
name. For example :GoImportAs str strings, will import strings with the
package name str.
Finally :GoDrop makes it easy to remove any import paths from the import
declarations. :GoDrop strings will remove it from the import declarations.
Of course manipulating import paths is so 2010. We have better tools to handle
this case for us. If you haven't heard yet, it's called goimports.
goimports is a replacement for gofmt. You have two ways of using it. The
first (and recommended) way is telling vim-go to use it when saving the
file:
let g:go_fmt_command = "goimports"
Now whenever you save your file, goimports will automatically format and also
rewrite your import declarations. Some people do not prefer goimports as it
might be slow on very large codebases. In this case we also have the
:GoImports command (note the s at the end). With this, you can explicitly
call goimports
Text objects
Let us show more editing tips/tricks. There are two text objects that we can
use to change functions. Those are if and af. if means inner function and
it allows you to select the content of a function enclosure. Change your main.go file to:
package main
import"fmt"funcmain() {
fmt.Println(1)
fmt.Println(2)
fmt.Println(3)
fmt.Println(4)
fmt.Println(5)
}
Put your cursor on the func keyword Now execute the following in normal
mode and see what happens:
dif
You'll see that the function body is removed. Because we used the d operator.
Undo your changes with u. The great thing is that your cursor can be anywhere
starting from the func keyword until the closing right brace }. It uses the tool
motion under the hood. I wrote motion
explicitly for vim-go to support features like this. It's Go AST aware and thus
its capabilities are really good. Like what you might ask? Change main.go to:
Previously we were using regexp-based text objects, which leads to problems.
For example in this example, put your cursor to the anonymous functions' func
keyword and execute dif in normal mode. You'll see that only the body of
the anonymous function is deleted.
We have only used the d operator (delete) so far. However it's up to you. For
example you can select it via vif or yank(copy) with yif.
We also have af, which means a function. This text object includes the
whole function declaration. Change your main.go to:
package main
import"fmt"// bar returns a the string "foo" even though it's named as "bar". It's an// example to be used with vim-go's tutorial to show the 'if' and 'af' text// objects.funcbar() string {
fmt.Println("calling bar")
foo:=func() string {
return"foo"
}
returnfoo()
}
So here is the great thing. Because of motion we have full knowledge about
every single syntax node. Put your cursor on top of the func keyword or
anywhere below or above (doesn't matter). If you now execute vaf, you'll see
that the function declaration is being selected, along with the doc comment as
well! You can for example delete the whole function with daf, and you'll see
that the comment is gone as well. Go ahead and put your cursor on top of the
comment and execute vif and then vaf. You'll see that it selects the
function body, even though your cursor is outside the function, or it selects
the function comments as well.
This is really powerful and this all is thanks to the knowledge we have from
let g:go_textobj_include_function_doc = 1motion. If you don't like comments
being a part of the function declaration, you can easily disable it with:
(Optional question: without looking at the go/ast package, is the doc comment
a part of the function declaration or not?)
Struct split and join
There is a great plugin that allows you to split or join Go structs. It's
actually not a Go plugin, but it has support for Go structs. To enable it add
plugin directive between the plug definition into your vimrc, then do a :source ~/.vimrc in your vim editor and run
:PlugInstall. Example:
Put your cursor on the same line as the struct expression. Now type gS. This
will split the struct expression into multiple lines. And you can even
reverse it. If your cursor is still on the foo variable, execute gJ in
normal mode. You'll see that the field definitions are all joined.
This doesn't use any AST-aware tools, so for example if you type gJ on top of
the fields, you'll see that only two fields are joined.
Snippets
Vim-go supports two popular snippet plugins.
Ultisnips and
neosnippet. By default,
if you have Ultisnips installed it'll work. Let us install ultisnips
first. Add it between the plug directives in your vimrc, then do a :source ~/.vimrc in your vim editor and then run
:PlugInstall. Example:
Let's put our cursor just after the newFoo() expression. Let's panic here if
the err is non-nil. Type errp in insert mode and just hit tab. You'll see
that it'll be expanded and put your cursor inside the `panic()`` function:
if err != nil {
panic( )
^
cursor position
}
Fill the panic with err and move on to the json.Marshal statement. Do the
same for it.
Now let us print the variable out. Because variable printing is so popular,
we have several snippets for it:
Here ff and lf are special. They dynamically copy the variable name into
the format string as well. Try it yourself. Move your cursor to the end of the
main function and type ff and hit tab. After expanding the snippet you can
start typing. Type string(out) and you'll see that both the format string and
the variadic arguments will be filled with the same string you have typed.
This comes very handy to quickly print variables for debugging.
Run your file with :GoRun and you should see the following output:
Great. Now let me show one last snippet that I think is very useful. As you see
from the output the fields Message and Ports begin with uppercase
characters. To fix it we can add a json tag to the struct field. vim-go makes it
very easy to add field tags. Move your cursor to the end of the Message
string line in the field:
type foo struct {
Message string .
^ put your cursor here
}
In insert mode, type json and hit tab. You'll see that it'll be
automatically expanded to valid field tag. The field name is converted
automatically to a lowercase and put there for you. You should now see the
following:
type foo struct {
Message string `json:"message"`
}
It's really amazing. But we can do even better! Go ahead and create a
snippet expansion for the ServerName field. You'll see that it's converted to
server_name. Amazing right?
When you save your file, gofmt shows any errors during parsing the file. If
there are any parse errors it'll show them inside a quickfix list. This is
enabled by default. Some people don't like it. To disable it add:
letg:go_fmt_fail_silently=1
You can change which case it should apply while converting. By default vim-go
uses snake_case. But you can also use camelCase if you wish. For example
if you wish to change the default value to camel case use the following
setting:
请发表评论