Find And Replace plugin for neovim
Grug find! Grug replace! Grug happy!
rg
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.<Enter>
in normal mode on lines in the results output (keybind configurable).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!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 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.Run :checkhealth grug-far
if you see unexpected issues.
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
},
grug-far.nvim comes with the following:
Note on the key mappings: By default, grug-far, will use <localleader>
for it's keymaps as that is the vim
recommended way for plugins. See https://learnvimscriptthehardway.stevelosh.com/chapters/11.html#local-leader
So to use that, make sure you have <localleader>
configured. For example, to use ,
as the local leader:
vim.g.maplocalleader = ','
You can open a new grug-far.nvim vertical split buffer with the :GrugFar
command.
Note that command supports the typical command-modifiers
like botright
, aboveleft
, etc. and visual ranges.
In visual mode, the command will pre-fill the search string with the current visual selection.
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.
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.
Search and replace is accomplished by simply typing text on appropriately marked lines. Search will happen in a debounced manner as you type. In the options, you can also specify a minimum number of characters that one has to enter before search is triggered. You can also specify a files filter to narrow down your search and more ripgrep flags to refine it further. Error messages from ripgrep when entering invalid flags and so on are displayed to guide you along.
Note: When replacing matches with the empty string, you will be prompted to confirm, as the change is not
visible in the results area due to UI considering it just a search. If you
would like to see the actual replacement in the results area, add --replace=
to the flags.
It is possible to sync the text of the lines in the results area back to their originating files.
This operation is either done on the current cursor line (Sync Line
), or on all lines (Sync All
).
A sync will happen only if a line has changed in some way compared to the source file, so if there's either a replacement taking place or you have manually edited it.
Deleting result lines will cause them to be excluded from being synced by Sync All
action.
This can be a nice way to refine a replacement in some situations if you want to exclude a particular file
or some particular matches.
If you don't edit the results list, Sync All
and Replace
have equivalent outcomes, except for one case.
When you do multi-line replace with --multiline
and --multiline-dot-all
flags, sync won't work so you
have to use replace. Essentially the difference it that Replace
runs rg --replace=... --passthrough
on
each file and does not depend at all on what's in the results area. Sync All
does a line by line
sync based on what's in the results area.
Note: changing the <line-number>:<column>:
prefix of result lines will disable sync for that line
Note: sync is disabled when doing multiline replacement (--multiline
flag)
Note: if you would like sync to work when doing a replacement with empty string, please add --replace=
to the flags.
When the cursor is placed on a result file path, you can go to that file by pressing <enter>
in normal mode (Goto
action default keybind).
When it's placed over a result match line, you will be taken to the file/line/column of the match. By default, the file buffer
is opened in the last window you were in before opening grug-far, which is typically the other vertical split.
If you would like to do the same thing, but have the cursor stay in place, you can use the Open
action instead.
Result lines can be opened in the quickfix list. Deleting result lines will cause them not to be included.
Note: changing the <line-number>:<column>:
prefix of result lines will remove lines from consideration
Note: quickfix list is disabled when doing multiline replacement (--multiline
flag)
grug-far can keep track of your search history. This is done either by manually adding a history entry with
History Add
action or automatically on certain successful actions like Replace
and Sync All
.
When you would like to pick one of your history entries to reuse, you can use the History Open
action to
open the search history as a buffer. From there you can pick an entry that will be auto-filled in.
Note that you can edit the history buffer and save just like any other buffer if you need to do some cleanup. The format of a history entry is:
<optional comment, ex: My special search>
Search: <text>
Replace: <text>
Files Filter: <text>
Flags: <text>
History entries are separated by one or more empty lines.
Note: grug-far will ignore lines that do not start with the prefixes above
Sometimes, mostly for debug purposes, it's useful to see the full rg
command that gets executed on search. You
can toggle that on with the Toggle Show rg Command
action, and the command will appear as the first thing in the
search results area.
The command is shell-escaped, so you can copy and execute it in a shell manually if you need to.
If you inadvertently launched a wrong search/sync/replace, you can abort early using the Abort
action.
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. The advantage of using the Close
action as opposed to just :bd
is that it
will ask you to confirm if there is a replace/sync in progress, as those would be aborted.
Note that grug-far.nvim buffers will have filetype=grug-far
, history buffers will have filetype=grug-far-history
and help will have filetype=grug-far-help
if you need filter/exclude them in any situations.
Excluding seems to be necessary with copilot at the time of writing this.
For more control, you can programmatically open a grug-far buffer like so:
require('grug-far').grug_far(opts)
If the above is called while in visual mode, it will pre-fill current visual selection as search text.
(note, this will also set --fixed-strings
flag as selection can contain special characters)
Note that if you want to pre-fill current visual selection from command mode, you would have to use:
:lua require('grug-far').with_visual_selection(opts)
where opts
will be merged with and override the global plugin options configured at setup time.
See here for all the available options
For more API, see docs
:lua require('grug-far').grug_far({ prefills = { search = vim.fn.expand("<cword>") } })
:lua require('grug-far').grug_far({ transient = true })
:lua require('grug-far').grug_far({ prefills = { paths = vim.fn.expand("%") } })
:<C-u>lua require('grug-far').with_visual_selection({ prefills = { paths = vim.fn.expand("%") } })
:lua require('grug-far').toggle_instance({ instanceName="far", staticTitle="Find and Replace" })
vim.api.nvim_create_autocmd('FileType', {
group = vim.api.nvim_create_augroup('my-grug-far-custom-keybinds', { clear = true }),
pattern = { 'grug-far' },
callback = function()
vim.keymap.set('n', '<localleader>w', function()
local state = unpack(require('grug-far').toggle_flags({ '--fixed-strings' }))
vim.notify('grug-far: toggled --fixed-strings ' .. (state and 'ON' or 'OFF'))
end, { buffer = true })
end,
})
rg
healthcheck from there :PREADME.md
as a template