sponsor Vim development Vim logo Vim Book Ad

surround.vim : Delete/change/add parentheses/quotes/XML-tags/much more with ease

 script karma  Rating 4161/1306, Downloaded by 56247  Comments, bugs, improvements  Vim wiki

created by
Tim Pope
 
script type
utility
 
description
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.  While it works under Vim 6, much of the functionality requires Vim 7.

Examples follow.  It is difficult to provide good examples in the variable width font of this site; check the documentation for more.

Press cs"' (that's c, s, double quote, single quote) inside

"Hello world!"

to change it to

'Hello world!'

Now press cs'<q> to change it to

<q>Hello world!</q>

To go full circle, press cst" to get

"Hello world!"

To remove the delimiters entirely, press ds" .

Hello world!

Now with the cursor on "Hello", press ysiw] (iw is a text object).

[Hello] world!

Let's make that braces and add some space (use "}" instead of "{" for no space): cs]{

{ Hello } world!

Now wrap the entire line in parentheses with yssb or yss) .

({ Hello } world!)

Revert to the original text: ds{ds)

Hello world!

Emphasize hello: ysiw<em>

<em>Hello</em> world!

Finally, let's try out visual mode. Press a capital V (for linewise visual mode)
followed by S<p>.

<p>
  Hello world!
</p>

This plugin is very powerful for HTML and XML editing, a niche which currently seems underfilled in Vim land.  (As opposed to HTML/XML *inserting*, for which many plugins are available).  Adding, changing, and removing pairs of tags simultaneously is a breeze.

The "." command will work with ds, cs, and yss if you install repeat.vim, vimscript #2136.

All feedback appreciated.

http://github.com/tpope/vim-surround
 
install details
Extract to ~/.vim, or ~\vimfiles (Windows).  You'll need to regenerate helptags (fill in the install path below)

:helptags ~/.vim/doc
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
surround.zip 2.2 2021-10-13 7.0 Tim Pope Keep HTML attributes when changing tags.
Support <Space><Space> as space replacement.
Bug fixes.
surround.zip 2.1 2015-02-08 7.0 Tim Pope Handle arbitrary punctuation delimiters with cs and ds.
Default to automatic indenting.
Provide cS to force surroundings on separate lines.
Support for disabling mappings only for insert mode.
Add repeat.vim support to surround with function.
Work around 'nomagic'.
surround.zip 2.0 2013-01-01 7.0 Tim Pope Fix vs with selection=exclusive.
Remove `unnamedplus' from clipboard in addition to `unnamed'.
Kill vs.
Bump to Vim 7.
Add support for repeating ys commands.
Add support for repeating tags.
Don't save deleted surrounding in unnamed register.
Fix deletion of delimiters on their own lines.
surround.zip 1.90 2010-03-06 6.0 Tim Pope Completely eliminate wonky % mapping in prompts.
Workaround for user remapped d. [Christian Oudard]
Introduce vgS and begin phasing out vs.
surround.zip 1.34 2008-02-15 6.0 Tim Pope One more regression fix.
This is really really planned as the last release with partial Vim 6.0 compatibility  (third time's the charm).
surround.zip 1.33 2008-02-03 7.0 Tim Pope Fixed regressions from previous release.
This is really planned as the last release with partial Vim 6.0 compatibility.
surround.zip 1.30 2008-01-27 7.0 Tim Pope Fixed edge case where ds could move a multiline inner text down one line.
This is planned as the last release with partial Vim 6.0 compatibility.
surround.zip 1.27 2007-10-03 7.0 Tim Pope Fixed multiline surrounds in insert mode
surround.vim 1.26 2007-07-31 7.0 Tim Pope Added a /* C style comment */ target.
Insert mode indenting limited to multiline insertions.
surround.zip 1.24 2007-05-10 7.0 Tim Pope surround_indent now works in insert mode.
Added <C-]> to add braces on separate lines.
surround.zip 1.23 2007-02-16 7.0 Tim Pope xmap rather than vmap, to avoid interfering with select mode.
surround_insert_tail to specify a universal suffix for use in insert mode.
surround.zip 1.22 2007-02-11 7.0 Tim Pope Function properly when clipboard=unnamed
Very experimental custom prompting for substitution text
surround.zip 1.18 2006-11-13 7.0 Tim Pope Zip file instead of documentation extraction hack
surround.vim 1.17 2006-11-09 6.0 Tim Pope Insert mode mapping that doesn't conflict with flow control.
Fixed edge case with ys where one too many characters would be grabbed.
surround.vim 1.16 2006-11-05 7.0 Tim Pope S in blockwise visual mode strips trailing whitespace.
surround.vim 1.12 2006-10-31 7.0 Tim Pope Lots of tiny bug fixes and cleanup.
"S" mappings to force surroundings onto a separate line.
Support for blockwise visual mode.
surround.vim 1.6 2006-10-29 7.0 Tim Pope Initial upload
ip used for rating: 52.205.218.160

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github