sponsor Vim development Vim logo Vim Book Ad

Ferret : Enhanced multi-file search for Vim

 script karma  Rating 43/13, Downloaded by 6648  Comments, bugs, improvements  Vim wiki

created by
Greg Hurrell
script type
Ferret improves Vim's multi-file search in four ways:

1. Powerful multi-file search ~

Ferret provides an |:Ack| command for searching across multiple files using
ripgrep (https://github.com/BurntSushi/ripgrep), The Silver Searcher
(https://github.com/ggreer/the_silver_searcher), or Ack
(http://beyondgrep.com/). Support for passing options through to the
underlying search command exists, along with the ability to use full regular
expression syntax without doing special escaping. On modern versions of Vim
(version 8 or higher, or Neovim), searches are performed asynchronously
(without blocking the UI).

Shortcut mappings are provided to start an |:Ack| search (<leader>a) or to
search for the word currently under the cursor (<leader>s).

Results are normally displayed in the |quickfix| window, but Ferret also
provides a |:Lack| command that behaves like |:Ack| but uses the |location-list|
instead, and a <leader>l mapping as a shortcut to |:Lack|.

|:Back| and |:Black| are analogous to |:Ack| and |:Lack|, but scoped to search
within currently open buffers only.

2. Streamlined multi-file replace ~

The companion to |:Ack| is |:Acks| (mnemonic: "Ack substitute", accessible via
shortcut <leader>r), which allows you to run a multi-file replace across all
the files placed in the |quickfix| window by a previous invocation of |:Ack| (or

3. Quickfix listing enhancements ~

The |quickfix| listing itself is enhanced with settings to improve its
usability, and natural mappings that allow quick removal of items from the
list (for example, you can reduce clutter in the listing by removing lines
that you don't intend to make changes to).

Additionally, Vim's |:cn|, |:cp|, |:cnf| and |:cpf| commands are tweaked to make it
easier to immediately identify matches by centering them within the viewport.

4. Easy operations on files in the quickfix listing ~

Finally, Ferret provides a |:Qargs| command that puts the files currently in
the |quickfix| listing into the |:args| list, where they can be operated on in
bulk via the |:argdo| command. This is what's used under the covers on older
versions of Vim by |:Acks| to do its work (on newer versions the built-in
|:cfdo| is used instead).
install details

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
ferret-5.1.zip 5.1 2021-07-10 7.0 Greg Hurrell - Add |g:FerretAckWordWord| setting, to pass `-w` to the underlying search tool when |<Plug>(FerretAckWord)| is pressed (https://github.com/wincent/ferret/issues/66).
- Use `:normal!` instead of |:normal| to avoid running custom mappings (patch from Yoni Weill, https://github.com/wincent/ferret/pull/67).
- Append a trailing slash when autocompleting a directory name (https://github.com/wincent/ferret/issues/69).
- Fixed failure to detect pre-existing mapping to |<Plug>(FerretLack)|.
- Worked around breakage caused by `rg` v13.0.0 (https://github.com/wincent/ferret/issues/78).
ferret-5.0.zip 5.0 2019-06-08 7.0 Greg Hurrell - The |<Plug>(FerretAcks)| mapping now uses |/\v| "very magic" mode by default. This default can be changed using the |g:FerretVeryMagic| option.
- |:Acks| now preferentially uses |:cdo| (rather than |:cfdo|) to make replacements, which means that it no longer operates on a per-file level and instead targets individual entries within the |quickfix| window. This is relevant if you've used Ferrets mappings to delete entries from the window. The old behavior can be restored with the |g:FerretAcksCommand| option.
- Ferret now has a |:Lacks| command, an analog to |:Acks| which applies to the |location-list|.
- Likewise, Ferret now has a |:Largs| command, analogous to |:Qargs|, which applies to the |location-list| instead of the |quickfix| window.
- The Ferret bindings that are set-up in the |quickfix| window when |g:FerretQFMap| is enabled now also apply to the |location-list|.
ferret-4.1.zip 4.1 2019-02-01 7.0 Greg Hurrell - Added |:Quack| command, analogous to |:Ack| but scoped to the files currently listed in the |quickfix| window.
- Fixed option autocompletion.
ferret-4.0.2.zip 4.0.2 2019-01-11 7.0 Greg Hurrell - Restore compatibility with versions of `rg` prior to v0.8 (https://github.com/wincent/ferret/issues/59).
ferret-4.0.1.zip 4.0.1 2019-01-08 7.0 Greg Hurrell - Make |:Acks| behavior the same irrespective of the |'gdefault'| setting.
ferret-4.0.zip 4.0 2018-12-26 7.0 Greg Hurrell - Try to avoid "press ENTER to continue" prompts.
- Put search term in |w:quickfix_title| for use in statuslines
- Add |g:FerretExecutableArguments| and |ferret#get_default_arguments()|
ferret-3.0.2.zip 3.0.2 2017-10-26 7.0 Greg Hurrell - Fix broken |:Back| and |:Black| commands
ferret-3.0.1.zip 3.0.1 2017-08-25 7.0 Greg Hurrell - Fix failure to handle search patterns containing multiple escaped spaces
ferret-3.0.zip 3.0 2017-06-13 7.0 Greg Hurrell - Improve handling of backslash escapes (https://github.com/wincent/ferret/issues/41).
- Add |g:FerretAutojump|.
- Drop support for vim-dispatch.
ferret-2.0.zip 2.0 2017-06-06 7.0 Greg Hurrell - Add support for Neovim, along with |g:FerretNvim| setting.
ferret-1.5.zip 1.5 2017-05-05 7.0 Greg Hurrell - Improvements to the handling of very large result sets (due to wide lines or many results).
- Added |g:FerretLazyInit|.
- Added missing documentation for |g:FerretJob|.
- Added |g:FerretMaxResults|.
- Added feature-detection for `rg` and `ag`, allowing Ferret to gracefully work with older versions of those tools that do not support all desired command-line switches.
ferret-1.4.zip 1.4 2017-01-22 7.0 Greg Hurrell - Drop broken support for `grep`, printing a prompt to install `rg`, `ag`, or
  `ack`/`ack-grep` instead.
- If an `ack` executable is not found, search for `ack-grep`, which is the
  name used on Debian-derived distros.
ferret-1.3.zip 1.3 2017-01-08 7.0 Greg Hurrell - Reset |'errorformat'| before each search (fixes issue #31).
- Added |:Back| and |:Black| commands, analogous to |:Ack| and |:Lack| but scoped to search within currently open buffers only.
- Change |:Acks| to use |:cfdo| when available rather than |:Qargs| and |:argdo|, to avoid polluting the |arglist|.
- Remove superfluous |QuickFixCmdPost| autocommands, resolving clash with Neomake plug-in (patch from Tom Dooner, #36).
- Add support for searching with ripgrep (`rg`).
ferret-1.2a.zip 1.2a 2016-05-16 7.4 Greg Hurrell - Add optional support for running searches asynchronously using Vim's |+job| feature (enabled by default in sufficiently recent versions of Vim); see |g:FerretJob|, |:FerretCancelAsync| and |:FerretPullAsync|.
ferret-1.1.1.zip 1.1.1 2016-03-07 7.0 Greg Hurrell - Fix another edge case when searching for patterns containing "#", only manifesting under dispatch.vim.
ferret-1.1.zip 1.1 2016-03-07 7.0 Greg Hurrell - Fix edge case when searching for strings of the form "<foo>".
- Fix edge case when searching for patterns containing "#" and "%".
- Provide completion for `ag` and `ack` options when using |:Ack| and |:Lack|.
- Fix display of error messages under dispatch.vim.
ferret-1.0.zip 1.0 2015-12-28 7.0 Greg Hurrell - Fix broken |:Qargs| command (patch from Daniel Silva).
- Add |g:FerretQFHandler| and |g:FerretLLHandler| options (patch from Daniel
- Make |<Plug>| mappings accessible even |g:FerretMap| is set to 0.
- Fix failure to report filename when using `ack` and explicitly scoping
  search to a single file (patch from Daniel Silva).
- When using `ag`, report multiple matches per line instead of just the first
  (patch from Daniel Silva).
- Improve content and display of error messages.
ferret-0.3.zip 0.3 2015-07-24 7.0 Greg Hurrell - Added highlighting of search pattern and related |g:FerretHlsearch| option
  (patch from Nelo-Thara Wallus).
- Add better error reporting for failed or incorrect searches.
ferret-0.2.zip 0.2 2015-07-16 7.0 Greg Hurrell - Added |FerretDidWrite| and |FerretWillWrite| autocommands (patch from Joe
- Add |<Plug>(FerretAcks)| mapping (patch from Nelo-Thara Wallus).
ferret-0.1.zip 0.1 2015-07-08 7.0 Greg Hurrell Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
Vim at Github