Skip to content

Latest commit

 

History

History
93 lines (73 loc) · 3.52 KB

README.md

File metadata and controls

93 lines (73 loc) · 3.52 KB
Raw

nvim-surround

Surround selections, stylishly 😎

README_demo_3.mp4

✨ Features

  • Add/delete/change surrounding pairs
    • Function calls and HTML tags out-of-the-box
  • Dot-repeat previous actions
  • Set buffer-local mappings and surrounds
  • Jump to the nearest surrounding pair for modification
  • Use a single character as an alias for several text-objects
    • E.g. q is aliased to `,',", so csqb replaces the nearest set of quotes with parentheses
  • Surround using powerful pairs that depend on user input
  • Modify custom surrounds
    • First-class support for Vim motions, Lua patterns, and Tree-sitter nodes
  • Highlight selections for visual feedback

🔒 Requirements

  • Neovim 0.8+
  • [Recommended] If nvim-treesitter is installed, then Tree-sitter nodes may be surrounded and modified, in addition to just Vim motions and Lua patterns
  • [Recommended] If nvim-treesitter-textobjects is installed, then Tree-sitter text-objects can be used to define surrounds, simplifying configuration

📦 Installation

packer.nvim

use({
    "kylechui/nvim-surround",
    tag = "*", -- Use for stability; omit to use `main` branch for the latest features
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
})

🚀 Usage

The three "core" operations of add/delete/change can be done with the keymaps ys{motion}{char}, ds{char}, and cs{target}{replacement}, respectively. For the following examples, * will denote the cursor position:

    Old text                    Command         New text
--------------------------------------------------------------------------------
    surr*ound_words             ysiw)           (surround_words)
    *make strings               ys$"            "make strings"
    [delete ar*ound me!]        ds]             delete around me!
    remove <b>HTML t*ags</b>    dst             remove HTML tags
    'change quot*es'            cs'"            "change quotes"
    <b>or tag* types</b>        csth1<CR>       <h1>or tag types</h1>
    delete(functi*on calls)     dsf             function calls

Detailed information on how to use this plugin can be found in :h nvim-surround.usage.

⚙️ Configuration

The default configuration is found here. Simply call require("nvim-surround").setup or require("nvim-surround").buffer_setup with the desired options.

More information on how to configure this plugin can be found in :h nvim-surround.configuration.

Contributing

See the contributing file.

Shoutouts