olexsmir.xyz
[mirror] Make your go dev experience better
github.com/olexsmir/gopher.nvim
neovim
golang
1# gopher.nvim
2
3[](https://stand-with-ukraine.pp.ua)
4
5Minimalistic plugin for Go development in Neovim written in Lua.
6
7It's **NOT** an LSP tool, the goal of this plugin is to add go tooling support in Neovim.
8
9> All development of new and maybe undocumented, and unstable features is happening on [develop](https://github.com/olexsmir/gopher.nvim/tree/develop) branch.
10
11## Table of content
12* [How to install](#install-using-lazynvim)
13* [Features](#features)
14* [Configuration](#configuration)
15* [Troubleshooting](#troubleshooting)
16* [Contributing](#contributing)
17
18## Install (using [lazy.nvim](https://github.com/folke/lazy.nvim))
19
20Requirements:
21
22- **Neovim 0.10** or later
23- Treesitter parser for `go`(`:TSInstall go` if you use [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter))
24- [Go](https://github.com/golang/go) installed
25
26> [!IMPORTANT]
27> If you prefer using other forges, this repository is also mirrored at:
28> - [tangled.org](https://tangled.org): [`https://tangled.org/olexsmir.xyz/gopher.nvim`](https://tangled.org/olexsmir.xyz/gopher.nvim)
29> - [codeberg.org](https://codeberg.org): [`https://codeberg.org/olexsmir/gopher.nvim`](https://codeberg.org/olexsmir/gopher.nvim)
30
31```lua
32-- NOTE: this plugin is already lazy-loaded and adds only about 1ms
33-- of load time to your config
34{
35 "olexsmir/gopher.nvim",
36 ft = "go",
37 -- branch = "develop"
38 -- (optional) updates the plugin's dependencies on each update
39 build = function()
40 vim.cmd.GoInstallDeps()
41 end,
42 ---@module "gopher"
43 ---@type gopher.Config
44 opts = {},
45}
46```
47
48## Features
49
50<details>
51 <summary>
52 <b>Install plugin's go deps</b>
53 </summary>
54
55 ```vim
56 :GoInstallDeps
57 ```
58
59 This will install the following tools:
60
61 - [gomodifytags](https://github.com/fatih/gomodifytags)
62 - [impl](https://github.com/josharian/impl)
63 - [gotests](https://github.com/cweill/gotests)
64 - [iferr](https://github.com/koron/iferr)
65</details>
66
67<details>
68 <summary>
69 <b>Add and remove tags for structs via <a href="https://github.com/fatih/gomodifytags">gomodifytags</a></b>
70 </summary>
71
72 
73
74 By default `json` tag will be added/removed, if not set:
75
76 ```vim
77 " add json tag
78 :GoTagAdd json
79
80 " add json tag with omitempty option
81 :GoTagAdd json=omitempty
82
83 " remove yaml tag
84 :GoTagRm yaml
85 ```
86
87 ```lua
88 -- or you can use lua api
89 require("gopher").tags.add "xml"
90 require("gopher").tags.rm "proto"
91 ```
92</details>
93
94<details>
95 <summary>
96 <b>Generating tests via <a href="https://github.com/cweill/gotests">gotests</a></b>
97 </summary>
98
99 ```vim
100 " Generate one test for a specific function/method(one under cursor)
101 :GoTestAdd
102
103 " Generate all tests for all functions/methods in the current file
104 :GoTestsAll
105
106 " Generate tests for only exported functions/methods in the current file
107 :GoTestsExp
108 ```
109
110 ```lua
111 -- or you can use lua api
112 require("gopher").test.add()
113 require("gopher").test.exported()
114 require("gopher").test.all()
115 ```
116
117 For named tests see `:h gopher.nvim-gotests-named`
118</details>
119
120<details>
121 <summary>
122 <b>Run commands like <code>go mod/get/etc</code> inside of nvim</b>
123 </summary>
124
125 ```vim
126 :GoGet github.com/gorilla/mux
127
128 " Link can have an `http` or `https` prefix.
129 :GoGet https://github.com/lib/pq
130
131 " You can provide more than one package url
132 :GoGet github.com/jackc/pgx/v5 github.com/google/uuid/
133
134 " go mod commands
135 :GoMod tidy
136 :GoMod init new-shiny-project
137
138 " go work commands
139 :GoWork sync
140
141 " run go generate in cwd
142 :GoGenerate
143
144 " run go generate for the current file
145 :GoGenerate %
146 ```
147</details>
148
149<details>
150 <summary>
151 <b>Interface implementation via <a href="https://github.com/josharian/impl">impl<a></b>
152 </summary>
153
154 
155
156 Syntax of the command:
157 ```vim
158 :GoImpl [receiver] [interface]
159
160 " also you can put a cursor on the struct and run
161 :GoImpl [interface]
162 ```
163
164 Usage examples:
165 ```vim
166 :GoImpl r Read io.Reader
167 :GoImpl Write io.Writer
168
169 " or you can simply put a cursor on the struct and run
170 :GoImpl io.Reader
171 ```
172</details>
173
174<details>
175 <summary>
176 <b>Generate boilerplate for doc comments</b>
177 </summary>
178
179 
180
181 First set a cursor on **public** package/function/interface/struct and execute:
182
183 ```vim
184 :GoCmt
185 ```
186</details>
187
188
189<details>
190 <summary>
191 <b>Generate <code>if err != nil {</code> via <a href="https://github.com/koron/iferr">iferr</a></b>
192 </summary>
193
194 
195
196 Set the cursor on the line with `err` and execute
197
198 ```vim
199 :GoIfErr
200 ```
201</details>
202
203## Configuration
204
205> [!IMPORTANT]
206>
207> If you need more info look `:h gopher.nvim`
208
209**Take a look at default options (might be a bit outdated, look `:h gopher.nvim-config`)**
210
211```lua
212require("gopher").setup {
213 -- log level, you might consider using DEBUG or TRACE for debugging the plugin
214 log_level = vim.log.levels.INFO,
215
216 -- timeout for running internal commands
217 timeout = 2000,
218
219 -- timeout for running installer commands(e.g :GoDepsInstall, :GoDepsInstallSync)
220 installer_timeout = 999999,
221
222 -- user specified paths to binaries
223 commands = {
224 go = "go",
225 gomodifytags = "gomodifytags",
226 gotests = "gotests",
227 impl = "impl",
228 iferr = "iferr",
229 },
230 gotests = {
231 -- a default template that gotess will use.
232 -- gotets doesn't have template named `default`, we use it to represent absence of the provided template.
233 template = "default",
234
235 -- path to a directory containing custom test code templates
236 template_dir = nil,
237
238 -- use named tests(map with test name as key) in table tests(slice of structs by default)
239 named = false,
240 },
241 gotag = {
242 transform = "snakecase",
243
244 -- default tags to add to struct fields
245 default_tag = "json",
246
247 -- default tag option added struct fields, set to nil to disable
248 -- e.g: `option = "json=omitempty,xml=omitempty`
249 option = nil,
250 },
251 iferr = {
252 -- choose a custom error message, nil to use default
253 -- e.g: `message = 'fmt.Errorf("failed to %w", err)'`
254 message = nil,
255 },
256}
257```
258
259## Troubleshooting
260The most common issue with the plugin is missing dependencies.
261Run `:checkhealth gopher` to verify that the plugin is installed correctly.
262If any binaries are missing, install them using `:GoInstallDeps`.
263
264If the issue persists, feel free to [open a new issue](https://github.com/olexsmir/gopher.nvim/issues/new).
265
266## Contributing
267
268PRs are always welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md)