Status Lines

Vim allows you to customize the text in the status line at the bottom of each window. This is done through the statusline option. Run the following command:

:set statusline=%f

You should see the path to the file (relative to the current directory) in the status line. Now run this command:

:set statusline=%f\ -\ FileType:\ %y

Now you'll see something like foo.markdown - FileType: [markdown] in the status line.

If you're familiar with C's printf or Python's string interpolation the format of this option may look familiar. If not, the only trick is that things that start with % are expanded to different text depending on what comes after them. In our example %f is replaced with the filename and %y is replaced with the type of the file.

Notice how the spaces in the status line need to be escaped with backslashes. This is because set allows you to set multiple options at once, as we saw in the second chapter.

Status lines can get extremely complicated very quickly, so there's a better way to set them that will let us be more clear. Run the following commands:

:set statusline=%f         " Path to the file
:set statusline+=\ -\      " Separator
:set statusline+=FileType: " Label
:set statusline+=%y        " Filetype of the file

In the first command we used = to wipe out any existing value present. In the rest we used += to build up the option one piece at a time. We also added comments explaining each piece for other people reading the code (or ourselves several months later).

Run the following commands:

:set statusline=%l    " Current line
:set statusline+=/    " Separator
:set statusline+=%L   " Total lines

Now the status line contains only the current line number and number of lines in the file, and looks something like 12/223.

Width and Padding

Additional characters can be used in some of the various % codes to change how the information is displayed. Run the following command:

:set statusline=[%4l]

The line number in the status line will now be preceded by enough spaces to make it at least four characters wide (for example: [ 12]). This can be useful to prevent the text in the status line from shifting around distractingly.

By default the padding spaces are added on the left side of the value. Run this command:

:set statusline=Current:\ %4l\ Total:\ %4L

Your status line will now look like this:

Current:   12 Total:  223

You can use - to place padding on the right instead of the left. Run this command:

:set statusline=Current:\ %-4l\ Total:\ %-4L

Your status line will now look like this:

Current: 12   Total: 223

This looks much nicer because the numbers are next to their labels.

For codes that result in a number you can tell Vim to pad with zeros instead of spaces. Run the following command:

:set statusline=%04l

Now your status line will read 0012 when on line twelve.

Finally, you can also set the maximum width of a code's output. Run this command:

:set statusline=%F

%F displays the full path to the current file. Now run this command to change the maximum width:

:set statusline=%.20F

The path will be truncated if necessary, looking something like this:

<hapters/17.markdown

This can be useful for preventing paths and other long codes from taking up the entire line.

General Format

The general format for a code in a status line is shown in :help statusline:

%-0{minwid}.{maxwid}{item}

Everything except the % and the item is optional.

Splitting

We're not going to cover status lines in too much detail here (Vim's own documentation on them is very extensive if you want to learn more), but there's one more simple code that can be very useful immediately. Run the following commands:

:set statusline=%f         " Path to the file
:set statusline+=%=        " Switch to the right side
:set statusline+=%l        " Current line
:set statusline+=/         " Separator
:set statusline+=%L        " Total lines

Now the status line will contain the path to the file on the left side, and the current/total lines on the right side. The %= code tells Vim that everything coming after that should be aligned (as a whole) to the right instead of the left.

Exercises

Skim the list of available codes in :help statusline. Don't worry if you don't understand some of them just yet.

Add some lines to your ~/.vimrc file to build yourself a custom status line. Be sure to use the += form of set to split the definition across multiple lines, and add a comment on each line to document what each piece does.

Try using autocommands and setlocal to define different status lines for different filetypes. Make sure to wrap the autocommands in groups to prevent duplication (as always).