Learn Vim at your own pace with my self-study Core Vim Course.

Learn more

Learn Vim at your own pace with my self-study Core Vim Course.

Formatting text with par


Run time:

‘Do one thing and do it well’ is the principle of the Unix toolkit. Editing text is a broad domain, and there are many related tasks with which it overlaps. Vim acknowledges this by enabling certain tasks to be outsourced to external programs which do that one thing, and do it well. This episode will demonstrate how the par program can be used for formatting text.


Par was written by Adam Costello in 1993, aiming to do one narrow task: reformat a single paragraph that might have a border on either side. The documentation is terse, and the author apologises for the implementation being unclean. Nevertheless, the program is stable, portable, and most important of all, extremely useful.

The formatprg option allows you to specify an external program that will be called when you run the gq command. The simplest possible configuration would be:

:set formatprg=par

By default, par sets line width at 72 columns. You can alter this by passing the -w flag with a number, for example:

:set formatprg=par\ -w50

This sets the line width to 50 columns. The backslash is necessary to escape the space at the command line. There are many different flags that can be passed to the par program in this fashion. You can view a summary of these by running par help at the command line.

In the video, I give a quick overview of the following options:

  • w - specify line length
  • r - repeat characters in bodiless lines
  • j - justifies text
  • e - remove ‘superflous’ lines
  • q - handle nested quotations in plaintext email

Installing par

Before you can call par from Vim, you will have to make sure that it is installed on your system.

Installing Par on OS X with macports

If you have macports installed, you can install par on OS X by running:

sudo port install par

You will be prompted for your password.

Installing par on other platforms

I haven’t had time to try this out on either Linux or Windows. Please leave a comment if you find an article on the web with good instructions on how to install par, or build it from source.

Further reading


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..