How to: vim-surround

In this post I will show you the great vim plug-in vim-surround. It's another great plug-in from Tim Pope, the guy you can not avoid, if you really use vim.

The problem

So, what's the purpose of this plug-in? In every text file you will have text objects, that belong to another and create a semantical unit. vim already acknowledges this fact, and provides you the text objects which increase the efficiency of working with text enormously.

But, at least in programming/administrative context, there are almost always some sort of surroundings, too. Sometimes it's just parentheses or quotation marks, but sometimes it's more complex, for example html tags.

vim has already basic support for the simpler ones (try for example c i ) to change everything enclosed in parentheses), but this behavior can be improved. For example, what if you wanted to surround a word with single quotes? Jumping to the beginning, insert a quote, jump to the end and insert the second quote is not as efficient, as it could be. And therefore not vim-like :)

Enter vim-surround

This plug-in aims at providing shortcuts for all important work with any surroundings, whether only single chars or complex html tags.

At first I want to link to the great Introduction page , this will show you probably almost every important function.

But now let's starts with some examples: Suppose, we want to call a function and provide a string:

println!(Hello, World);

But wait, we forgot the quotes! With vim-surround no problem: If our cursor is inside the parentheses we can type the commands y s i ) ' and we fixed the call:

println!('Hello, World');

Let's look at what we have done: The first two commands y s are for the plug-in to start surrounding. Why ys? Try to remember it by saying: You Surround. The next two command tell the plug-in, what should be surrounded. This is just a normal text-object and includes everything inside the parentheses. If you had wanted to include the parentheses inside the quotes, you would replace the i by a . At last, you provide the surrounding, you want to have, in our case a single quote.

Oh no, we have to provide the string in double quotes. No we have to replace the quotes one by one, don't we?

No!

Of course we can change the surrounding with vim-surround. Our cursor must be inside the single quotes and then we type c s ' " and we have what we need:

println!("Hello, World");

How did we get there? We told the plugin to Change Surrounding. The first argument was then what we want to change, and secondly into what it should be changed. So we told the plugin to Change Surrounding from ' to ".

This scheme can be used for all kind of work with surrounding, also for deleting. Just set your cursor into the string and try d s " Again, speak the commands out loud. Delete Surrounding ".

Once you understood the general structure of the command, you can massively improve the work with surroundings. Just try it out.

tl;dr

Create surrounding

Always remember by saying ‘you surround’.

Change surrounding

Change surrounding from into

Delete surrounding