Traditionally, vim-abolish is introduced by saying that what it does is hard to explain. This tradition dates back to its creator Tim Pope, who introduced it by saying that "I've deferred release, primarily because it's so gosh darn hard to explain" [1]. However, while exactly what is being abolished is uncertain, vim-abolish can best be described as advanced search and replace functions, roughly analogous to but less powerful than the command sed. It consists of four utilities: abbreviation (word completion), substitution, search, and coercion (case change). With a bit of organization, you can set up these utilities to use multiple forms of a word, such as different tenses, prefixes, suffixes, or spellings. With these tools, vim-abolish is equally useful for writing code or text documents.

Vim-abolish is installed by downloading the plugin from its homepage [1] to ~/.vim or ~\vimfiles, depending on your distribution. If you are using the plugin manager Pathogen, you can install Git and run the commands:

cd ~/.vim/bundle
git clone git://github.com/tpope/vim-abolish.git

The command installs the executable to ~/.vim/bundle/vim-abolish. From within Vim, you can run :help Abolish for examples of how to use each utility (Figure 1), including some complex search patterns [2].

Figure 1: Vim-abolish's help contains detailed examples of how to use the plugin's four utilities.

The Command Structure

Vim-abolish offers two command structure choices. The most verbose command structure begins with :Abolish and varies with each utility. For example, if you are using the abbreviation utility (see below), the structure would be:

:Abolish [options] {abbreviation} {replacement}

However, if you are using the search utility, the structure becomes:

:Abolish! -search OPTIONS PATTERN

The other command structure option, :Subvert, can also vary, but tends to be shorter and more consistent than Abolish. It can be used for substitution, search, and coercion, but not abbreviation. For example, Subvert's basic search command structure is:

:Subvert/PATTERN/FLAGS

Even more importantly, the command can be abbreviated to

:S/PATTERN/FLAGS

which also has the advantage of using fewer, lesser used keys that might tempt you to look down at the keyboard rather than the screen.

With both the Abolish and Subvert commands, you can use comma-separated strings in curly braces so that the command covers variations of the basic pattern, such as:

:S/gues{s,sed,stimate}/

In this example, the basic pattern of gues is supplemented by the flags or variations of s, sed, and stimate. With this structure, the command will find guess, guessed, and guesstimate in both lowercase, title case, and uppercase. A command can be any number of patterns, each with its own completion flags. For instance, the help file gives the example

:Abolish {despe,sepa}rat{e,es,ed,ing,ely,ion,ions,or}

which finds about 50 words, including desperate, separate, separates, and separated.

Such patterns make vim-abolish concise but also require careful planning. At the risk of not using the plugin's full power, new users should probably begin with simple patterns, avoiding more complex ones until they are comfortable with the command structure.

Abbreviation

Abbreviation is a more powerful version of Vim's substitution command. It creates autocorrect entries that can be stored for use with other files. Abbreviation entries can save typing or correct typos, serving as a personalized spell checker.

The command structure is:

:Abolish OPTIONS ABBREVIATION REPLACEMENT

For instance, once you enter the command:

:Abolish cmns communications

cmns is changed to communications. If you type Cmns, it becomes Communications, and CMNS becomes COMMUNICATIONS. No extra command structure is needed for this support of different letter cases. However, both the abbreviation and the correction must be a single word, and you cannot use single or double quotation marks to make the command treat a phrase as a word.

Similarly, if you regularly type fro for for, you can correct it automatically with:

:Abolish fro for

By default, abbreviations work only in Vim's Insert mode while the current document is open. However, if you add the option -buffer after the basic command, the abbreviation will work throughout the current buffer as well.

Similarly, adding the option -cmndline will make the abbreviation work in the Vim command line, whereas adding an exclamation mark to the basic command (:Abolish!) saves the abbreviation for general use in Vim. Abbreviations are saved in ~./.vim/after/plugin/abolish.vim.

To delete an abbreviation as thoroughly as possible from within Vim, enter the command:

:Abolish --delete -buffer -cmndline ABBREVIATION

The -buffer and -cmndline options, of course, can be omitted if you are sure they were not used in creating the abbreviation.

Search

The command structure for search is either:

:Abolish -search STRING

or

:S/STRING/

By default, both commands search forward from the present cursor position in the document, looping back to the beginning and continuing to the starting point. Alternatively, both :Abolish! or :S?TERM? search backward from the cursor position, looping back to the end of the document to complete the search.

Searches can be further refined with -flags=OPTION inserted after the Abolish command

:Abolish -flags=OPTION -search STRING

or placed after the search term in the abbreviated :Subvert command:

:S/STRING/ -search STRING

With both Abolish and Subvert searches, the I option disables support for case variations so that only the exact string entered is located. Additionally, v finds only variable names in code and w only complete words. These options are not always needed, but they can sometimes help to avoid false positives.

Vim-abolish's search command also supports grep options and regular expressions. For instance,

:S/gues{s,sed,stimate}/*.txt

finds the results guess.txt, guessed.txt, and guesstimate.txt.