This article is part of the article series "Vim Plugins You Should Know About."
<- previous article next article ->
Vim Plugins, surround.vim

Hi all. I am starting a new article series called "Vim Plugins You Should Know About". This series of articles is going to be about Vim plugins that you should know about and perhaps even be using. The first article in this series will be about one of my favorite plugins called "surround.vim".

If you are intrigued by this article series, I suggest that you subscribe to my posts!

Don't worry, I'll finish all the previous article series that I have started (creating and marketing a video downloading tool, awk one-liners explained, sed one-liners explained and mit algorithms). I just wanted to utilize my excitement and get this article published ASAP.

Okay, so what is surround.vim plugin? Here is what Tim Pope, the author of this plugin, says:

Surround.vim is all about "surroundings": parentheses, brackets, quotes, XML tags, and more. The plugin provides mappings to easily delete, change and add such surroundings in pairs.

That's what the plugin does. It allows you to easily delete, change and add various "surroundings" in pairs. For example, you may quickly wrap a line in an html tag, or you may delete a pair of { }, or you may add quotes around words, etc.

Let's take a look at a few examples for each surrounding command: delete surrounding, change surrounding, and add surrounding. In the examples | indicates the position of the cursor.

Examples of deleting surroundings:

Surroundings can be deleted with the "ds" command. After you type "ds", the command expects the surrounding target you want to delete. It may be any of three quote marks, ', ", and `, the eight punctuation marks, (, ), {, }, [, ], <, > , and a special 't' target for deleting the innermost HTML tag.

Text              Command    New Text
---------------   -------    -----------
'Hello W|orld'    ds'        Hello World
(12|3+4*56)/2     ds(        123+4*56/2
<div>fo|o</div>   dst        foo

(| is the position of cursor in these examples)

See how easy it was to delete surroundings? Just 3 keystrokes. Compare it with doing it old fashioned way:

Text              Command    New Text
---------------   -------    -----------
'Hello W|orld'    F'x,x      Hello World
(12|3+4*56)/2     Bxf)x      123+4*56/2
<div>fo|o</div>   Bdf>wdf>   foo

(| is the position of cursor in these examples)

That was really messy, wasn't it? I hope you start to see now how handy surround.vim is!

Examples of changing surroundings:

Surroundings can be changed with the "cs" command. The "cs" command, just like "ds" command takes a surrounding target, and it also takes the surrounding replacement. There are a few more surrounding targets for this command. They are w for word, W for word + skip punctuation, s for sentence, and p for paragraph.

Text              Command    New Text
---------------   -------    -----------
"Hello |world!"   cs"'       'Hello world!'
"Hello |world!"   cs"<q>     <q>Hello world!</q>
(123+4|56)/2      cs)]       [123+456]/2
(123+4|56)/2      cs)[       [ 123+456 ]/2
<div>foo|</div>   cst<p>     <p>foo</p>
fo|o!             csw'       'foo'!
fo|o!             csW'       'foo!'

(| is the position of cursor in these examples)

Examples of adding surroundings:

Surroundings can be added with the same "cs" command, which takes a surrounding target, or with the "ys" command that takes a valid vim motion. There is a special "yss" command that applies a surrounding to the whole line, and "ySS" that applies the surrounding to the whole line, places the text on a new line and indents it.

Text              Command      New Text
---------------   -------      -----------
Hello w|orld!     ysiw)        Hello (world)!
Hello w|orld!     csw)         Hello (world)!
fo|o              ysiwt<html>  <html>foo</html>
foo quu|x baz     yss"         "foo quux baz"
foo quu|x baz     ySS"         "
                                   foo quux baz

(| is the position of cursor in these examples)

You can also add surroundings while in insert mode. That is supported via <CTRL-s> mapping.

Please be very careful with CTRL-s. On many terminals it stops the output and your session will appear to be frozen! If that happens, use CTRL-q to unfreeze it. You may want to remove CTRL+s mapping from your terminal altogether. Add "stty stop ''" to your shell startup file (.bashrc for bash, .kshrc for ksh, etc).

For example (while in insert mode):

Command                  New Text
-------                  ------------
<CTRL-s>"                ""
<CTRL-s><CTRL-s><html>   <html>

(| is the position of cursor in these examples)

I urge you to try these mappings out. You won't become a hockey player by just looking at the game, you have to play it yourself!

For a complete reference, here are all the commands/mappings surround.vim provides:

Normal mode
ds  - delete a surrounding
cs  - change a surrounding
ys  - add a surrounding
yS  - add a surrounding and place the surrounded text on a new line + indent it
yss - add a surrounding to the whole line
ySs - add a surrounding to the whole line, place it on a new line + indent it
ySS - same as ySs

Visual mode
s   - in visual mode, add a surrounding
S   - in visual mode, add a surrounding but place text on new line + indent it

Insert mode
<CTRL-s> - in insert mode, add a surrounding
<CTRL-s><CTRL-s> - in insert mode, add a new line + surrounding + indent
<CTRL-g>s - same as <CTRL-s>
<CTRL-g>S - same as <CTRL-s><CTRL-s>

How to install surround.vim?

  • 1. Download It will actually be a zip file containing the surround.vim script and documentation.
  • 2. Extract to ~/.vim (on Unix/Linux), or ~\vimfiles (Windows).
  • 3. Restart Vim (or just source surround.vim script with ":so ~/.vim/plugin/surround.vim" on Unix or ":so ~/vimfiles/plugin/surround.vim" on Windows).
  • 4. Regenerate helptags with ":helptags ~/.vim/doc" on Unix or ":helptags ~/vimfiles/doc" on Windoze.

Type ":help surround" to read help.

Comments appreciated!

What plugins do you use? Your comments will help me and my blog readers to find more plugins which we might have not heard about. You may also share any tips and aha-moments that you have had while using vim. I might add my own and turn them into a valuable article. Thanks!

This article is part of the article series "Vim Plugins You Should Know About."
<- previous article next article ->


December 08, 2008, 14:07

What does this plugin do that text objects doesn't provide already?

December 08, 2008, 14:23

JB, this plugin uses text objects to apply surroundings.

December 08, 2008, 15:28

Comment copied from HN:

I tried this plugin a few days ago, but it seemed to break the s (substitute) command, so I removed it. Does someone know how to make it work?

The problem is the following: Write a line of text, select part of it using v, then press s to remove the selection and enter insert mode start replacing it. This doesn't work anymore when surround.vim is loaded. Too bad, it sure looks great…

December 08, 2008, 15:47

thamer, replied to you on HN. Copied here:

Try 'R' instead of 's' that you were used to.


Edit surround.vim and comment out the 's' mappings in visual mode.

Chris Permalink
December 08, 2008, 15:54

Instead of 's' for substitute, try 'c' for change.

December 08, 2008, 16:22

Peter, I seem to be hitting this bug: when I hit Ctrl+S in my VIM. Then I had to hit Ctrl+Q to unfreeze.

I'm on a Solaris machine running dtterm and ksh. Any idea on how to get around this problem?

December 08, 2008, 16:37

Srikanth, that is not a bug at all. It's your terminal controlling the flow. With Ctrl+S you stop the terminal, with Ctrl+Q you restart the output.

To avoid this "bug", try redefining the Ctrl+S at terminal level:

stty stop ''

And put it in your .profile or .kshrc file.

December 08, 2008, 16:42

Surround is one of the plugins featured as one of the 15 best vim plugins here..
15 Best Vim Plugins

Check out the other 14 to have a highly customized efficient vim environment.

December 08, 2008, 17:06

surround.vim looks very useful. I've wanted something similar in the past but I was too lazy to search for it. Thanks for the tip!

Vim by itself is usually enough for me, so I haven't tried many plugins. The only plugin that I use regularly is vim-latex; it's amazing how fast one can type LaTeX documents with it (more efficient than using a wysiwyg, me thinks).

December 08, 2008, 18:20

Thanks for blogging about this plugin, I absolutely dig surround.vim!

FuzzyFinder.vim and taglist.vim are two other staples I would definitely add to the list.


Chephren Permalink
December 08, 2008, 18:23

Apart from surround.vim, my favourite editing script is yankring.vim. Works really well, with lots of delightful features.

I also use bufexplorer.vim winfileexplorer.vim taglist.vim and winmanager.vim to get all that ide functionality.

Another nifty plugin is the ZoomWin.vim plugin, which allows you to maximise a vim window, and then restore your previous window configuration. I have tons of plugins lying around, many of which I can't remember what they do.

Oh yeah, the themes.vim with all the colourschemes is necessary as well.

December 08, 2008, 19:42

Wow nice plugin! Already using it :)

dogmachine Permalink
December 08, 2008, 20:19

I can do that surround removal shit in under a second with clever use of cmd+cursors/option+cursors shift and delete when I'm in textmate.
and I can do it instantly without having to remember that obscure command to perform something this abstract.

You think your saving time because your calling automation, but really the amount of time you'll be wasting in remembering that wont be saved at all.
If we both did it at exactly the same time I would be finished before you even started typing.

Shortcuts are mostly a myth, you feel more productive when your actually slower.

December 08, 2008, 23:51


You mock vim users for using shortcuts to delete text, whilst giving the example of . . . yourself using shortcuts to delete text. *laughs*

How is remembering a "clever use of cmd+cursors/option+cursors shift and delete" any easier than remembering 'ds'?

Legend Permalink
December 09, 2008, 00:07

Unfortunately, commands added by this plugin are not repeated by the '.' command -- they are treated as a couple of separate commands. For example, if you have two words and you move the cursor to one and do ds", then you move the cursor to the other and hit '.' and it won't preform ds", it will just delete the word under the cursor. Kind of a drag -- anybody know how to change this?

Wade Mealing Permalink
December 09, 2008, 01:06

As usual, people hide behind pseudonyms to spew their craziness on the net. I guess you know you look a bit silly to any prospective employer who may read your response.

December 09, 2008, 01:22

When im adding surroundings, i usually select the target text in visual mode then hit s) or s" etc. This requires less thinking than using text objects which often makes it faster.

Legend: if you use repeat.vim (by the same author) then some of the commands are repeatable with "." but not all :(

December 09, 2008, 04:35

Legend: install repeat.vim

December 09, 2008, 11:41

Thanks Peter, of course it's not a bug; it's a feature. What was I thinking! :)

Nice plugin. Autoclose is also very useful.

December 09, 2008, 14:07

A few comments:

- Use <CTRL-g>S if you want to keep <CTRL-s> for your terminal.
- Debian makes it easy to install vim addons: apt-get install vim-{scripts,addon-manager} && vim-addons install surround


Speculos Permalink
December 09, 2008, 17:50

You can also have a look at the project plugin which let you load all files of a project, grep some pattern in the files, run a script on all files of the project, etc.

You can find a small introduction here.

f00li5h Permalink
December 10, 2008, 03:09

come out, we've got the place surrounded!

December 13, 2008, 11:32

I have been using VIM for a long time, but I have not heard about this plug-in. Thank you!

February 05, 2009, 19:25

I noticed that in visual mode s is redundant because c does the same thing. So having s rebound in visual mode is not a problem for me.

It's a pretty sweet plugin IMO.

Casey Permalink
August 20, 2009, 01:51

Acutaly, I don't find this very helpful. There are still to many commands, and even with repeat.vim, the repeat action doesn't always work.

I'll try it out a little more, but not going to hold my breadth.

Brett Stahlman Permalink
November 06, 2009, 02:30

If you're looking for Vim plugins that people should know about... You might want to check out Txtfmt (The Vim Highlighter), which provides a sort of "rich text" highlighting capability in Vim: fg/bg colors and all combinations of bold, underline, italic, etc...

Vim download page:

Disclaimer: Yes, I am the author, but my experience has convinced me that there are still a number of people looking for this capability in Vim, who aren't aware that this plugin exists.

February 28, 2010, 22:54

I noticed that in visual mode s is redundant because c does the same thing. So having s rebound in visual mode is not a problem for me.

so i think it is sweet plugin

Andy Permalink
March 02, 2010, 16:08

How to keep s unmapped in Visual mode:

" map another key to <Plug>Vsurround
:vmap <Leader>s <Plug>Vsurround

This is directly taken from surround.vim's help file, thus the author pretty much is aware about the issue.

October 27, 2010, 16:05

Very usefull plugin, I suggest the pathogen plugin and this article [1] contains interesting things. Finally this fantastic screencast [2]

1 -
2 -

hmmm Permalink
June 10, 2011, 13:45

This is no question specifically regarding the add on, but googling didnt quite help me: I'm new to Ubuntu and I can't seem to find an installation directory of GVim where I could eventually put the plugins. In usr/bin I see a couple of related files, but no folder to extract into? Or should I directly put it in usr/bin?

Thanks in advance

June 10, 2011, 17:42

Hi hmmm. Put it in your home directory in .vim/plugins directory!

Eric Permalink
August 03, 2012, 13:47

This should actually be ~/.vim/plugin (and not plugins)

October 08, 2011, 07:07

Dear peter ,
pls could you tell me how to use vim plugins for source code trace like for example i want to know which function where it is defined similarly class, stracture. if not understood see the link you will get idea

prathamesh Permalink
October 18, 2011, 18:33

This Helped. Thanks !

nga Permalink
July 03, 2012, 19:36

run stty -ixon on terminal.

December 05, 2012, 19:29

check out the "i" (in) operator. That's stock in vim, which is nice so you don't have to worry about installing extra plugins.

"Hello W|orld" di", ci" etc work just as this does.

You can certainly do it in " ' ( [ {. If you get a good xml plugin then I will work in >< as well.

John Permalink
April 23, 2013, 05:02

The shortcuts have changes a little bit:
S - in visual mode, add a surrounding
gS - in visual mode, add a surrounding but place text on new line + indent it

Leave a new comment

(why do I need your e-mail?)

(Your twitter handle, if you have one.)

Type the word "rocket_112": (just to make sure you're a human)

Please preview the comment before submitting to make sure it's OK.