How do I set up substitute.nvim for basic text replacements?

Install with a package manager like Lazy.nvim, then manually map keys such as 's' to require('substitute').operator in Neovim's config. The README provides example mappings for operator, line, and visual modes.

Substitute.nvim vs vim-subversive: which should I use in Neovim?

Substitute.nvim is a Lua rewrite aiming for better maintainability and efficiency, while vim-subversive is VimScript-based. Choose substitute.nvim for modern Neovim setups with Lua preferences, but vim-subversive if you need Vim compatibility or prefer stable VimScript plugins.

Can substitute.nvim work with yanky.nvim for better yank management?

Yes, it integrates seamlessly by setting on_substitute to require('yanky.integration').substitute() in the configuration. This enables swapping yanked content during substitutions, as detailed in the integration section.

What modifiers are available and how do I apply them during substitution?

Modifiers include linewise, reindent, trim, and join. Use them by passing a modifiers table in the operator call, e.g., { modifiers = {'trim', 'reindent'} }, or dynamically with a function based on context like motion type.

How do I exchange two words quickly with substitute.nvim?

Map a key like 'sx' to require('substitute.exchange').operator, then use sxiw on the first word, move to the second, and use sxiw again or dot-repeat. The exchange is dot-repeatable and supports different motions.

Is substitute.nvim good for large files or performance-intensive editing?

Its Lua implementation aims for efficiency, but complex range substitutions or frequent exchanges might impact performance in very large buffers. Benchmarking is advised for heavy use cases compared to native Neovim commands.

How to cancel an exchange operation if I change my mind?

By default, press Esc to cancel, or map a key to require('substitute.exchange').cancel. Configure use_esc_to_cancel in settings if needed, as described in the exchange configuration section.

substitute.nvim — Neovim Text Substitution Plugin

What is substitute.nvim?

substitute.nvim is a Neovim plugin that provides new operator motions for quickly replacing and exchanging text within the editor. It allows users to substitute text objects with yanked content, apply substitutions across ranges, and swap text between locations, streamlining common editing tasks.

Target Audience

Neovim users who frequently perform text substitutions and exchanges, particularly those familiar with Vim plugins like vim-subversive or vim-exchange seeking a Lua-based alternative.

Value Proposition

Developers choose substitute.nvim for its Lua implementation, which aims to be more maintainable and efficient than older VimScript plugins, while offering powerful, dot-repeatable operations and seamless integration with other Neovim plugins.

Neovim plugin introducing a new operators motions to quickly replace and exchange text.

Use Cases

Best For

Replacing words or paragraphs with yanked text using motions
Applying substitutions across multiple lines with range motions
Swapping two text regions like words or lines quickly
Enhancing Neovim editing workflows with dot-repeatable operations
Integrating with yank managers like yanky.nvim for swap functionality
Using text modifiers like reindenting or trimming during substitution

Not Ideal For

Editors who want plugins with pre-configured keybindings and zero setup effort
Teams using Vim or Neovim versions older than 0.8.0
Workflows heavily dependent on mouse-driven or graphical text manipulation tools
Users unfamiliar with Vim motions who might find operator-based editing unintuitive

Pros & Cons

Pros

Lua-Powered Modernization

Rewritten in Lua for improved maintainability and efficiency over VimScript alternatives like vim-subversive, as stated in the README's philosophy section.

Dot-Repeatable Operations

Both substitute and exchange operators support the dot command, allowing quick repetition of edits without re-invoking motions, enhancing editing speed.

Flexible Text Modifiers

Includes built-in modifiers like reindenting, trimming, and joining lines, enabling context-aware substitutions directly during operations without extra steps.

Seamless Plugin Integration

Designed to work with plugins like yanky.nvim and vim-abolish, offering enhanced yank management and substitution capabilities through configurable hooks.

Cons

Manual Key Mapping Required

The plugin provides no default mappings, forcing users to manually set up keybindings, which adds setup overhead and potential for configuration errors.

Key Shadowing Issues

Recommended mappings often use 's', which shadows Neovim's native change character, requiring users to adapt or remap other keys like 'cl' for basic edits.

Neovim Version Dependency

Requires Neovim >= 0.8.0, locking out users on older versions or other editors like Vim, with only a limited compatibility branch for Neovim 0.6.0.

Configuration Complexity

Advanced features like range substitutions and modifiers involve numerous options that can be overwhelming to tune, especially for casual users.

Frequently Asked Questions

What is substitute.nvim?

Target Audience

Neovim users who frequently perform text substitutions and exchanges, particularly those familiar with Vim plugins like vim-subversive or vim-exchange seeking a Lua-based alternative.

Value Proposition

Use Cases

Best For

Replacing words or paragraphs with yanked text using motions
Applying substitutions across multiple lines with range motions
Swapping two text regions like words or lines quickly
Enhancing Neovim editing workflows with dot-repeatable operations
Integrating with yank managers like yanky.nvim for swap functionality
Using text modifiers like reindenting or trimming during substitution

Not Ideal For

Editors who want plugins with pre-configured keybindings and zero setup effort
Teams using Vim or Neovim versions older than 0.8.0
Workflows heavily dependent on mouse-driven or graphical text manipulation tools
Users unfamiliar with Vim motions who might find operator-based editing unintuitive

Pros & Cons

Pros

Lua-Powered Modernization

Rewritten in Lua for improved maintainability and efficiency over VimScript alternatives like vim-subversive, as stated in the README's philosophy section.

Dot-Repeatable Operations

Both substitute and exchange operators support the dot command, allowing quick repetition of edits without re-invoking motions, enhancing editing speed.

Flexible Text Modifiers

Includes built-in modifiers like reindenting, trimming, and joining lines, enabling context-aware substitutions directly during operations without extra steps.

Seamless Plugin Integration

Designed to work with plugins like yanky.nvim and vim-abolish, offering enhanced yank management and substitution capabilities through configurable hooks.

Cons

Manual Key Mapping Required

The plugin provides no default mappings, forcing users to manually set up keybindings, which adds setup overhead and potential for configuration errors.

Key Shadowing Issues

Recommended mappings often use 's', which shadows Neovim's native change character, requiring users to adapt or remap other keys like 'cl' for basic edits.

Neovim Version Dependency

Requires Neovim >= 0.8.0, locking out users on older versions or other editors like Vim, with only a limited compatibility branch for Neovim 0.6.0.

Configuration Complexity

Advanced features like range substitutions and modifiers involve numerous options that can be overwhelming to tune, especially for casual users.

Frequently Asked Questions

substitute.nvim

What is substitute.nvim?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

substitute.nvim

What is substitute.nvim?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?