explaingit

tpope/vim-surround

14,065Vim ScriptAudience · developerComplexity · 1/5LicenseSetup · easy

TLDR

A Vim plugin that adds keyboard shortcuts for adding, changing, or removing surrounding characters like quotes, parentheses, and HTML tags in just a few keystrokes.

Mindmap

mindmap
  root((vim-surround))
    What it does
      Add surroundings
      Change surroundings
      Remove surroundings
    Supported pairs
      Quotes
      Brackets
      HTML tags
    Modes
      Normal mode
      Visual mode
    Setup
      Built-in packages
      Plugin managers
      repeat.vim optional
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Switch a word from double quotes to single quotes in one key sequence without moving the cursor to both ends.

USE CASE 2

Wrap a selected block of code or text in an HTML tag while editing a template file.

USE CASE 3

Remove all surrounding parentheses from a function argument with a single command.

USE CASE 4

Add brackets or custom delimiters around any word to format code or markup faster.

Tech stack

Vim ScriptVim

Getting it running

Difficulty · easy Time to first run · 5min
Licensed under the same terms as Vim, a GPL-compatible charityware license, free to use and distribute.

In plain English

vim-surround is a plugin for the Vim text editor that makes it faster to work with paired characters like quotes, parentheses, brackets, and HTML or XML tags. These paired characters are called surroundings, and the plugin gives you keyboard shortcuts to add, change, or remove them without manually placing your cursor at both ends. For example, if you have a word wrapped in double quotes and want to switch to single quotes, one short key sequence handles it. If you want to wrap a word in an HTML tag like a bold or emphasis tag, another sequence does that. Removing the surrounding characters entirely is a single command. The plugin also works in visual mode, so you can select a line or a block of text and wrap it in a tag or bracket all at once. Most of the examples in the README involve switching between quote styles, adding brackets with or without spaces inside, and wrapping content in HTML tags. The plugin is described as particularly well-suited for editing HTML and XML, since changing both opening and closing tags simultaneously is otherwise tedious in a plain editor. Installation uses Vim's built-in package system, or any third-party Vim plugin manager. There is also an optional companion plugin called repeat.vim that lets you redo surround operations with Vim's dot-repeat command, which normally does not work with custom plugin mappings. The plugin is written by Tim Pope and is licensed under the same terms as Vim itself. It is one of several widely used Vim plugins from the same author.

Copy-paste prompts

Prompt 1
Show me the vim-surround key sequences to change double quotes to single quotes, add parentheses around a word, and wrap a line in a div tag.
Prompt 2
How do I use vim-surround in visual mode to wrap a multi-line selection in a custom HTML tag?
Prompt 3
Walk me through installing vim-surround using Vim 8 built-in packages without any plugin manager.
Prompt 4
I use vim-surround with the repeat.vim plugin, how do I redo the last surround operation with the dot command?
Open on GitHub → Explain another repo

← tpope on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.