vim-surround
surround.vim: Delete/change/add parentheses/quotes/XML-tags/much more with ease
Top Related Projects
Set of operators and textobjects to search/select/edit sandwiched texts.
Add/change/delete surrounding delimiter pairs with ease. Written with :heart: in Lua.
repeat.vim: enable repeating supported plugin maps with "."
Quick Overview
vim-surround is a popular Vim plugin that provides mappings to easily delete, change, and add surroundings in pairs. It allows users to manipulate parentheses, brackets, quotes, XML tags, and more with simple keystrokes, enhancing productivity for programmers and text editors.
Pros
- Intuitive and easy-to-use commands for manipulating surroundings
- Supports a wide range of surrounding types (quotes, parentheses, tags, etc.)
- Customizable and extensible for user-defined surroundings
- Integrates seamlessly with Vim's existing commands and motions
Cons
- Requires some initial learning curve to master all commands
- May conflict with other plugins or custom mappings
- Limited functionality outside of Vim (not applicable to other text editors)
- Some users may find the default keybindings unintuitive
Code Examples
- Surrounding a word with quotes:
" Place cursor on the word and type:
ysiw"
- Changing surrounding parentheses to square brackets:
" Place cursor inside the parentheses and type:
cs([
- Deleting surrounding XML tags:
" Place cursor inside the XML tags and type:
dst
- Surrounding a visual selection with curly braces:
" Select text in visual mode and type:
S{
Getting Started
To install vim-surround using a plugin manager like vim-plug, add the following line to your .vimrc
:
Plug 'tpope/vim-surround'
Then run :PlugInstall
in Vim.
Basic usage:
ys<motion><char>
: Add surroundingcs<old><new>
: Change surroundingds<char>
: Delete surroundingS<char>
: Surround visual selection
For more detailed instructions and examples, refer to the plugin's documentation by running :help surround
in Vim after installation.
Competitor Comparisons
Set of operators and textobjects to search/select/edit sandwiched texts.
Pros of vim-sandwich
- More customizable and flexible, allowing users to define their own recipes
- Supports dot-repeat for all operations, enhancing efficiency
- Provides visual mode support for surrounding operations
Cons of vim-sandwich
- Steeper learning curve due to more complex configuration options
- Default keybindings differ from vim-surround, requiring adjustment for users switching over
Code Comparison
vim-surround:
" Surround word with quotes
ysiw"
" Change surrounding parentheses to brackets
cs)]
vim-sandwich:
" Surround word with quotes
saiw"
" Change surrounding parentheses to brackets
srb()[]
Both plugins aim to simplify the process of adding, changing, and deleting surrounding characters in Vim. vim-surround is known for its simplicity and ease of use, while vim-sandwich offers more advanced features and customization options. The choice between the two often comes down to personal preference and specific needs.
Add/change/delete surrounding delimiter pairs with ease. Written with :heart: in Lua.
Pros of nvim-surround
- Written in Lua, providing better performance and integration with Neovim
- Offers more customization options and extensibility
- Includes built-in text objects for easier manipulation
Cons of nvim-surround
- Requires Neovim 0.7+ and Lua knowledge for advanced configuration
- May have a steeper learning curve for users familiar with vim-surround
- Potentially less stable due to being a newer project
Code Comparison
vim-surround:
" Add double quotes around a word
ysiw"
" Change single quotes to double quotes
cs'"
nvim-surround:
-- Add double quotes around a word
vim.keymap.set("n", "ys", require("nvim-surround").surround_add)
-- Change single quotes to double quotes
vim.keymap.set("n", "cs", require("nvim-surround").surround_change)
Both plugins offer similar functionality, but nvim-surround provides a more modern approach with Lua integration and additional features. While vim-surround is a tried-and-true solution, nvim-surround may be more appealing to users looking for enhanced customization and Neovim-specific optimizations. The choice between the two largely depends on personal preference and specific requirements.
repeat.vim: enable repeating supported plugin maps with "."
Pros of vim-repeat
- Enhances Vim's native repeat functionality for custom mappings and plugins
- Works seamlessly with many popular Vim plugins, including vim-surround
- Lightweight and requires minimal configuration
Cons of vim-repeat
- Limited in scope compared to vim-surround's text manipulation features
- May not be as immediately useful for beginners as vim-surround
- Requires plugins to support its functionality for maximum benefit
Code Comparison
vim-repeat:
silent! call repeat#set("\<Plug>MyWonderfulMap", v:count)
vim-surround:
nmap ds <Plug>Dsurround
nmap cs <Plug>Csurround
nmap ys <Plug>Ysurround
Summary
vim-repeat is a utility plugin that enhances Vim's repeat functionality, allowing users to repeat custom mappings and plugin actions. It's particularly useful when combined with other plugins like vim-surround. On the other hand, vim-surround focuses on manipulating surrounding characters (e.g., quotes, parentheses) in text. While vim-repeat is more of a behind-the-scenes enhancer, vim-surround provides direct text manipulation features that are immediately useful to many users. Both plugins are lightweight and well-maintained by the same author, making them excellent additions to any Vim configuration.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
surround.vim
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.
It's easiest to explain with examples. Press cs"'
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 class="important">
.
<p class="important">
<em>Hello</em> 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.
Installation
Install using your favorite package manager, or use Vim's built-in package support:
mkdir -p ~/.vim/pack/tpope/start
cd ~/.vim/pack/tpope/start
git clone https://tpope.io/vim/surround.git
vim -u NONE -c "helptags surround/doc" -c q
FAQ
How do I surround without adding a space?
Only the opening bracketsâ[
, {
, and (
âadd a space. Use a closing
bracket, or the b
((
) and B
({
) aliases.
Contributing
See the contribution guidelines for pathogen.vim.
Self-Promotion
Like surround.vim? Star the repository on GitHub and vote for it on vim.org.
Love surround.vim? Follow tpope on GitHub and Twitter.
License
Copyright (c) Tim Pope. Distributed under the same terms as Vim itself.
See :help license
.
Top Related Projects
Set of operators and textobjects to search/select/edit sandwiched texts.
Add/change/delete surrounding delimiter pairs with ease. Written with :heart: in Lua.
repeat.vim: enable repeating supported plugin maps with "."
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot