Awesome

Fast and feature-rich surround actions

• Add, delete, replace, find, highlight surrounding (like pair of parenthesis, quotes, etc.).
• Supports dot-repeat, v:count, different search methods, "last"/"next" extended mappings, customization via Lua patterns or functions, and more.
• Has builtins for brackets, function call, tag, user prompt, and any alphanumeric/punctuation/whitespace character.
• Has maintained configuration of setup similar to 'tpope/vim-surround'.

See more details in Features and help file.

⦿ This is a part of mini.nvim library. Please use this link if you want to mention this module.

⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.

⦿ See the repository page to learn about common design principles and configuration recipes.

If you want to help this project grow but don't know where to start, check out contributing guides of 'mini.nvim' or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.

Demo

https://user-images.githubusercontent.com/24854248/173045302-cc4fd421-cc33-4924-a95b-207097973b48.mp4

Features

• Actions (all of them are dot-repeatable out of the box and respect v:count for searching surrounding) with configurable keymappings:
  • Add surrounding with sa (in visual mode or on motion).
  • Delete surrounding with sd.
  • Replace surrounding with sr.
  • Find surrounding with sf or sF (move cursor right or left).
  • Highlight surrounding with sh.
  • Change number of neighbor lines with sn (see |MiniSurround-algorithm|).
• Surrounding is identified by a single character as both "input" (in delete and replace start, find, and highlight) and "output" (in add and replace end):
  • 'f' - function call (string of alphanumeric symbols or '_' or '.' followed by balanced '()'). In "input" finds function call, in "output" prompts user to enter function name.
  • 't' - tag. In "input" finds tag with same identifier, in "output" prompts user to enter tag name.
  • All symbols in brackets '()', '[]', '{}', '<>". In "input' represents balanced brackets (open - with whitespace pad, close - without), in "output" - left and right parts of brackets.
  • '?' - interactive. Prompts user to enter left and right parts.
  • All other alphanumeric, punctuation, or space characters represent surrounding with identical left and right parts.
• Configurable search methods to find not only covering but possibly next, previous, or nearest surrounding. See more in help for MiniSurround.config.
• All actions involving finding surrounding (delete, replace, find, highlight) can be used with suffix that changes search method to find previous/last. See more in help for MiniSurround.config.

Installation

This plugin can be installed as part of 'mini.nvim' library (recommended) or as a standalone Git repository.

There are two branches to install from:

• main (default, recommended) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
• stable will be updated only upon releases with code tested during public beta-testing phase in main branch.

Here are code snippets for some common installation methods (use only one):

Important: don't forget to call require('mini.surround').setup() to enable its functionality.

Note: if you are on Windows, there might be problems with too long file paths (like error: unable to create file <some file name>: Filename too long). Try doing one of the following:

• Enable corresponding git global config value: git config --system core.longpaths true. Then try to reinstall.
• Install plugin in other place with shorter path.

Default config

-- No need to copy this inside `setup()`. Will be used automatically.
{
  -- Add custom surroundings to be used on top of builtin ones. For more
  -- information with examples, see `:h MiniSurround.config`.
  custom_surroundings = nil,

  -- Duration (in ms) of highlight when calling `MiniSurround.highlight()`
  highlight_duration = 500,

  -- Module mappings. Use `''` (empty string) to disable one.
  mappings = {
    add = 'sa', -- Add surrounding in Normal and Visual modes
    delete = 'sd', -- Delete surrounding
    find = 'sf', -- Find surrounding (to the right)
    find_left = 'sF', -- Find surrounding (to the left)
    highlight = 'sh', -- Highlight surrounding
    replace = 'sr', -- Replace surrounding
    update_n_lines = 'sn', -- Update `n_lines`

    suffix_last = 'l', -- Suffix to search with "prev" method
    suffix_next = 'n', -- Suffix to search with "next" method
  },

  -- Number of lines within which surrounding is searched
  n_lines = 20,

  -- Whether to respect selection type:
  -- - Place surroundings on separate lines in linewise mode.
  -- - Place surroundings on each line in blockwise mode.
  respect_selection_type = false,

  -- How to search for surrounding (first inside current line, then inside
  -- neighborhood). One of 'cover', 'cover_or_next', 'cover_or_prev',
  -- 'cover_or_nearest', 'next', 'prev', 'nearest'. For more details,
  -- see `:h MiniSurround.config`.
  search_method = 'cover',

  -- Whether to disable showing non-error feedback
  -- This also affects (purely informational) helper messages shown after
  -- idle time if user input is required.
  silent = false,
}

Similar plugins

• tpope/vim-surround
• kylechui/nvim-surround
• machakann/vim-sandwich