grug-far.nvim

Find And Replace plugin for neovim

Grug find! Grug replace! Grug happy!

✨ Features

Search using the full power of rg
Replace using almost the full power of rg. Some flags such as --binary and --json, etc. are blacklisted in order to prevent unexpected output. The UI will warn you and prevent replace when using such flags.
Open search results in quickfix list
Goto file/line/column of match when pressing <Enter> in normal mode on lines in the results output (keybind configurable).
Inline edit matched result lines and sync them their originating file locations using a configurable keybinding.

Searching:

Replacing:

Rg teaching you it's ways

Help:

🤔 Philosophy

strives for reduced mental overhead. All actions you can take are in your face. As much help as possible is in your face (some configurable). Grug often forget how to do capture groups or which flag does what.
transparency. Does not try to hide away rg and shows error messages from it which are actually quite friendly when you mess up your regex. You can gradually learn rg flags or use existing knowledge from running it in the CLI. You can even input the --help flag to see the full rg help. Grug like!
reuse muscle memory. Does not try to block any type of buffer edits, such as deleting lines, etc. It's very easy to get such things wrong and when you do, Grug becomes unable to modify text in the middle of writing a large regex. Grug mad!! Only ensures graceful recovery in order to preserve basic UI integrity (possible due to the magic of extmarks). Recovery should be simple undo away.
uniformity. only uses one tool, rg, and does not combine with other tools like sed. One should not have to worry about compatibility differences when writing regexes. Additionally it opens the door to use to many fancy rg flags such as different regex engine that would not be possible in a mixed environment. Replacement is achieved by running rg --replace=... --passthrough on each file with configurable number of parallel workers.

⚡️ Requirements

Neovim >= 0.9.0 (might work with lower versions)
BurntSushi/ripgrep
a Nerd Font (optional)

Run :checkhealth grug-far if you see unexpected issues.

📦 Installation

Using lazy.nvim:

  {
    'MagicDuck/grug-far.nvim',
    config = function()
      require('grug-far').setup({
        ... options, see Configuration section below ...
        ... there are no required options atm...
      });
    end
  },

⚙️ Configuration

grug-far.nvim comes with the following:

🚀 Usage

You can open a new grug-far.nvim vertical split buffer with the :GrugFar command. But possibly best to map a keybind to it for easy triggering. Since it's just a buffer, you can edit in it as you see fit. The UI will try to guide you along and recover gracefully if you do things like ggVGd (delete all lines). Ultimately it leaves the power in your hands, and in any case recovery is just a few u taps away.

Search and replace to your heart's desire. You can create multiple such buffers with potentially different searches, which will reflect in each buffer's title (configurable). The buffers should be visible in the buffers list if you need to toggle to them.

It is also possible to make edits to lines in the results section and have them synced to their originating file lines. Simply make your changes on multiple lines and press <C-s> (by default).

When you are done, it is recommended to close the buffer with the configured keybinding (see Configuration section above) or just :bd in order to save on resources as some search results can be quite beefy in size.

Note that grug-far.nvim buffers will have filetype=grug-far if you need filter/exclude them in any situations.

⚒️ Lua API

For more control, you can programmatically open a grug-far buffer like so:

require('grug-far').grug_far(opts)

where opts will be merged with and override the global plugin options configured at setup time.

See here for all the available options

🥪 Cookbook

Launch with the current word under the cursor as the search string

require('grug-far').grug_far({ prefills = { search = vim.fn.expand("<cword>") } })

Launch with the current file as a flag, which limits search/replace to it

require('grug-far').grug_far({ prefills = { flags = vim.fn.expand("%") } })

📦 Similar Plugins / Inspiration

nvim-spectre: the OG find and replace in a buffer plugin, great inspiration!
telescope.nvim: lifted rg healthcheck from there :P
lazy.nvim: used their beautiful README.md as a template
plugin-template.nvim: super handy template, this plugin is based on it!

miversen33 / grug-far.nvim Goto Github PK

grug-far.nvim's Introduction