3 GO111MODULE=on go get mvdan.cc/gofumpt
5 Enforce a stricter format than `gofmt`, while being backwards compatible. That
6 is, `gofumpt` is happy with a subset of the formats that `gofmt` is happy with.
8 The tool is a modified fork of `gofmt`, so it can be used as a drop-in
9 replacement. Running `gofmt` after `gofumpt` should be a no-op.
11 Most of the Go source files in this repository belong to the Go project.
12 The added formatting rules are in the `format` package.
16 No empty lines at the beginning or end of a function
18 <details><summary><i>example</i></summary>
35 No empty lines around a lone statement (or comment) in a block
37 <details><summary><i>example</i></summary>
54 No empty lines before a simple error check
56 <details><summary><i>example</i></summary>
59 foo, err := processFoo()
67 foo, err := processFoo()
75 Composite literals should use newlines consistently
77 <details><summary><i>example</i></summary>
80 // A newline before or after an element requires newlines for the opening and
82 var ints = []int{1, 2,
85 // A newline between consecutive elements requires a newline between all
101 var matrix = [][]int{
112 Empty field lists should use a single line
114 <details><summary><i>example</i></summary>
128 var V interface{} = 3
141 var matrix = [][]int{
152 `std` imports must be in a separate group at the top
154 <details><summary><i>example</i></summary>
177 Short case clauses should take a single line
179 <details><summary><i>example</i></summary>
190 case 'a', 'b', 'c', 'd':
196 Multiline top-level declarations must be separated by empty lines
198 <details><summary><i>example</i></summary>
202 println("multiline foo")
205 println("multiline bar")
211 println("multiline foo")
215 println("multiline bar")
221 Single var declarations should not be grouped with parentheses
223 <details><summary><i>example</i></summary>
237 Contiguous top-level declarations should be grouped together
239 <details><summary><i>example</i></summary>
258 Simple var-declaration statements should use short assignments
260 <details><summary><i>example</i></summary>
273 The `-s` code simplification flag is enabled by default
275 <details><summary><i>example</i></summary>
278 var _ = [][]int{[]int{1}}
288 Octal integer literals should use the `0o` prefix on modules using Go 1.13 and later
290 <details><summary><i>example</i></summary>
302 Comments which aren't Go directives should start with a whitespace
304 <details><summary><i>example</i></summary>
322 #### Extra rules behind `-extra`
324 Adjacent parameters with the same type should be grouped together
326 <details><summary><i>example</i></summary>
329 func Foo(bar string, baz string) {}
333 func Foo(bar, baz string) {}
340 `gofumpt` is a replacement for `gofmt`, so you can simply `go get` it as
341 described at the top of this README and use it.
343 When using an IDE or editor with Go integrations, it's best to use `gofumpt` as
344 part of `gopls`. The instructions below show how to do that for some of the
345 major editors out there.
347 #### Visual Studio Code
349 Enable the language server following [the official docs](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md),
350 and then enable gopls's `gofumpt` option. Note that VS Code will complain about
351 the `gopls` settings, but they will still work.
354 "go.useLanguageServer": true,
362 Once `gofumpt` is installed, follow the steps below:
364 - Open **Settings** (File > Settings)
365 - Open the **Tools** section
366 - Find the *File Watchers* sub-section
367 - Click on the `+` on the right side to add a new file watcher
368 - Choose *Custom Template*
370 When a window asks for settings, you can enter the following:
372 * File Types: Select all .go files
373 * Scope: Project Files
374 * Program: Select your `gofumpt` executable
375 * Arguments: `-w $FilePath$`
376 * Output path to refresh: `$FilePath$`
377 * Working directory: `$ProjectFileDir$`
378 * Environment variables: `GOROOT=$GOROOT$;GOPATH=$GOPATH$;PATH=$GoBinDirs$`
380 To avoid unecessary runs, you should disable all checkboxes in the *Advanced* section.
384 Ensure you are at least running version
385 [v1.24](https://github.com/fatih/vim-go/blob/master/CHANGELOG.md#v124---september-15-2020),
386 and set up `gopls` for formatting code with `gofumpt`:
389 let g:go_fmt_command="gopls"
390 let g:go_gopls_gofumpt=1
395 With a [new enough version of govim](https://github.com/govim/govim/pull/1005),
396 simply configure `gopls` to use `gofumpt`:
399 call govim#config#Set("Gofumpt", 1)
404 This tool is a place to experiment. In the long term, the features that work
405 well might be proposed for `gofmt` itself.
407 The tool is also compatible with `gofmt` and is aimed to be stable, so you can
408 rely on it for your code as long as you pin a version of it.
412 Note that much of the code is copied from Go's `gofmt` and `goimports` commands.
413 You can tell which files originate from the Go repository from their copyright
414 headers. Their license file is `LICENSE.google`.
416 `gofumpt`'s original source files are also under the 3-clause BSD license, with
417 the separate file `LICENSE`.