Golines is a Go code formatter that shortens long lines, in addition to all
of the formatting fixes done by gofmt.
The standard Go formatting tools (gofmt, goimports, etc.) are great, but
deliberately don't shorten long lines;
instead, this is an activity left to developers.
While there are different tastes when it comes to line lengths in go, we've generally found that very long lines are more difficult to read than their shortened alternatives. As an example:
myMap := map[string]string{"first key": "first value", "second key": "second value", "third key": "third value", "fourth key": "fourth value", "fifth key": "fifth value"}vs.
myMap := map[string]string{
"first key": "first value",
"second key": "second value",
"third key": "third value",
"fourth key": "fourth value",
"fifth key": "fifth value",
}We built golines to give Go developers the option to automatically shorten long lines, like
the one above, according to their preferences.
More background and technical details are available in this blog post.
See this before and after
view of a file with very long lines. More example pairs can be found in the
_fixtures directory.
Newer releases of golines require at least Go 1.18 due to generics-related dependencies.
However, the minimum version in go.mod
should be considered the minimum required version of Go for any given version
of golines. If you need to use golines with an older version of go, install
the tool from the v0.9.0 release.
First, install the tool. If you're using Go 1.21 or newer, run:
go install github.com/segmentio/golines@latest
Otherwise, for older Go versions, run:
go install github.com/segmentio/[email protected]
Then, run:
golines [paths to format]
The paths can be either directories or individual files. If no paths are
provided, then input is taken from stdin (as with gofmt).
By default, the results are printed to stdout. To overwrite the existing
files in place, use the -w flag.
Some other options are described in the sections below. Run golines --help to
see all available flags and settings.
By default, the tool tries to shorten lines that are longer than 100 columns
and assumes that 1 tab = 4 columns. The latter can be changed via the
-m and -t flags respectively.
Running the tool with the --dry-run flag will show pretty, git-style diffs.
Shortening long comment lines is harder than shortening code because comments can
have arbitrary structure and format. golines includes some basic
logic for shortening single-line (i.e., //-prefixed) comments, but this is turned
off by default since the quality isn't great. To enable this feature anyway, run
with the --shorten-comments flag.
By default, the tool will use goimports
as the base formatter (if found), otherwise it will revert to gofmt. An explicit
formatter can be set via the --base-formatter flag; the command provided here
should accept its input via stdin and write its output to stdout.
By default, the tool will not format any files that look like they're generated.
If you want to reformat these too, run with the flag --ignore-generated=false.
There are several possible ways to split lines that are part of
method chains. The original
approach taken by golines was to split on the args, e.g.:
myObj.Method(
arg1,
arg2,
arg3,
).AnotherMethod(
arg1,
arg2,
).AThirdMethod(
arg1,
arg2,
)Starting in version 0.3.0, the tool now splits on the dots by default, e.g.:
myObj.Method(arg1, arg2, arg3).
AnotherMethod(arg1, arg2).
AThirdMethod(arg1, arg2)The original behavior can be used by running the tool with the
--no-chain-split-dots flag.
In addition to shortening long lines, the tool also aligns struct tag keys; see the
associated before and after
examples in the _fixtures directory. To turn this behavior off, run with --no-reformat-tags.
Add the following lines to your vimrc, substituting 128 with your preferred line length:
let g:go_fmt_command = "golines"
let g:go_fmt_options = {
\ 'golines': '-m 128',
\ }- Install the Run on Save extension
- Go into the VSCode settings menu, scroll down to the section for the "Run on Save" extension, click the "Edit in settings.json" link
- Set the
emeraldwalk.runonsavekey as follows (adding other flags to thegolinescommand as desired):
"emeraldwalk.runonsave": {
"commands": [
{
"match": "\\.go$",
"cmd": "golines ${file} -w"
}
]
}
- Save the settings and restart VSCode
- Go into the Goland settings and click "Tools" -> "File Watchers" then click the plus to create a new file watcher
- Set the following properties and confirm by clicking OK:
- Name:
golines - File type:
Go files - Scope:
Project Files - Program:
golines - Arguments:
$FilePath$ -w - Output paths to refresh:
$FilePath$
- Name:
- Activate your newly created file watcher in the Goland settings under "Tools" -> "Actions on save"
Coming soon.
For each input source file, golines runs through the following process:
- Read the file, break it into lines
- Add a specially-formatted annotation (comment) to each line that's longer than the configured maximum
- Use Dave Brophy's excellent decorated syntax tree library to parse the code plus added annotations
- Do a depth-first traversal of the resulting tree, looking for nodes that have an annotation on them
- If a node is part of a line that's too long, shorten it by altering the newlines around the node and/or its children
- Repeat steps 2-5 until no more shortening can be done
- Run the base formatter (e.g.,
gofmt) over the results, write these to eitherstdoutor the source file
See this blog post for more technical details.
The tool has been tested on a variety of inputs, but it's not perfect. Among other examples, the handling of long lines in comments could be improved. If you see anything particularly egregious, please report via an issue.
