Introduction

I can spend hours telling you how important code formatting is. But I hope I won’t need to. Consistent code formatting is not only essential when working with solo projects, but is actually more important when working with teams and groups of other people.

Table of Contents

Let’s not get into that for now. What I’m interested in is the gq command I just discovered of in Vim (it’s not surprising how vast Vim is. The more you think that you know about it, the more you’ll be left wondering). It is mostly applicable for simple line formatting by hard-wrapping text, but it can also be taken many steps further by use of plugins and external programs which define the formatting to be interpreted by gq.

In this article, I’ll cover as much as I can regarding the gq keybinding Vim that I’ve learned of, as well as talk about the more practical use cases for it.

Wrap long lines with gqq

The most basic use case for gq is probably wrapping long lines into a given width. Those of you taking notes in markdown will make the most out of it. Besides, it is also useful for hard-wrapping comments in a code file too. But in order to achieve all this, we first need to set the textwidth option for the gq keybinding to work. Actually, what the gq keybinding does is look at a few options in Vim, which includes formatoptions, formatexpr, formatprg (we’ll talk about this later on in the article), and lastly, textwidth. If none of the other options have been set, then gq directs to the textwidth setting and formats the given lines.

Let’s take a simple example first into account. Take this below file as an example:

As you can already see, different lines in the above text have different text widths. In order to make all the lines look more justified in terms of width, let us first set the textwidth option to something viable from the command mode:

(tw is a shorthand for textwidth option. You can also type out the full form if you wish, but who would want that?)

As soon as the textwidth option is set, we can now apply the formatting to each line one by one using gqq, but once again, who would even do more work than necessary? So instead, we can use a little shorthand for this command as well, that is, by going to the first line, using gq and then pressing capital G to apply the formatting over all the text above. Overall, the command should be “gggqG” (the first 2 ggs will take your cursor to the first line). This is what it should look like in action:

Aha! Just as we wanted it to be. But notice that, the formatting not only hard-wraps the line in the beginning which is longer than the given text width, but it also joins the lines which are shorter to make them match the text width. This sure is good for our above situation, but you might not really want that in every scenario, and would turn out to be problematic. Later on in the article, we’ll talk about how to fix this, with the help of the global g command in Vim.

Wrap only selected lines with gq

For now, let us look at another scenario. Let’s say that we want to apply this formatting only on given lines, instead of the entire file. You may wish to use motions, and also combine the global g to achieve something truly impressive (we’ll cover some of it in the very next section), but the easiest way to go about it is selecting lines with the Visual Mode in Vim, and then run the formatting on then with gq. Take a look at the gif below:

Using gq with the global g command

You can also combine gq with the global g command, and take your code editing to the skies (literally, it’s that good). If you don’t already know what it is, well, it’s a topic off for another day. For now, here’s a slight little demo that you can take a look at:

What this is doing is technically simple. First, the g command searches for a pattern, which in our case is “dummy”, and then applies the given command to all the lines that match the pattern. The word normal is included to tell g that we want to execute the command in normal mode.

However, even if you don’t wish to use the global g much often, you might still need to use it, in case you don’t want the “joining of lines” problem to occur when using gq in smaller lines.

A slight problem and it’s fix

It depends on your and your specific task why you may not want to join smaller lines, but my task here would be to at least convey to you the command you’d need to run if you want to achieve that. So let’s say that you’re applying the formatting on the entire file, and don’t want the smaller lines to be joined. The below command is all you’d need to run:

:g/./ normal gqq

If I apply this on my previous file, this is how it would end up being:

Using formatprg with gq

The last thing I’d like to cover about the gq keybinding is the formatprg option. Well, there is actually a lot more we can talk about of gq, but those other things might not actually be that relevant most people, so I’m omitting them for the sake of minimizing this article.

The thing is, formatting lines with the textwidth option alone is boring, and practically useless as long as you’re not taking notes with markdown and stuff. What a real coder would be more interested in is to format their code files to maintain some design guidelines. There are several command line programs available in Linux and other UNIX systems which are capable of formatting your code automatically.

In Vim, the formatprg option takes an argument, where you specify a program that is capable of formatting code (such as black for Python), and once the option is set, you can use the gq keybinding on either the entire file, or only selected lines as well.

The syntax for the command should look like this:

:set formatprg=<program_name>

Now different formatters will vary quite largely, so it’ll be to you to figure out how you can apply an external program to format the selected lines.

All you need to know is that once the program name has been defined, you can use the gq keybinding as usual, in any way you like. Combine it with g, select lines with Visual Mode and what else not!