(FerretAcks)
```
## Options
g:FerretNvim
### `g:FerretNvim` (boolean, default: 1)
Controls whether to use Neovim's `job-control` features, when available, to run searches asynchronously. To prevent this from being used, set to 0, in which case Ferret will fall back to the next method in the list (Vim's built-in async primitives -- see [`g:FerretJob`](#user-content-gferretjob) -- which are typically not available in Neovim, so will then fall back to the next available method).
```
let g:FerretNvim=0
```
g:FerretJob
### `g:FerretJob` (boolean, default: 1)
Controls whether to use Vim's `+job` feature, when available, to run searches asynchronously. To prevent `+job` from being used, set to 0, in which case Ferret will fall back to the next available method.
```
let g:FerretJob=0
```
g:FerretHlsearch
### `g:FerretHlsearch` (boolean, default: none)
Controls whether Ferret should attempt to highlight the search pattern when running [`:Ack`](#user-content-ack) or [`:Lack`](#user-content-lack). If left unset, Ferret will respect the current 'hlsearch' setting. To force highlighting on or off irrespective of 'hlsearch', set [`g:FerretHlsearch`](#user-content-gferrethlsearch) to 1 (on) or 0 (off):
```
let g:FerretHlsearch=0
```
g:FerretAcksCommand
### `g:FerretAcksCommand` (string, default: "cdo")
Controls the underlying Vim command that [`:Acks`](#user-content-acks) uses to peform substitutions. On versions of Vim that have it, defaults to `:cdo`, which means that substitutions will apply to the specific lines currently in the `quickfix` listing. Can be set to "cfdo" to instead use `:cfdo` (if available), which means that the substitutions will be applied on a per-file basis to all the files in the `quickfix` listing. This distinction is important if you have used Ferret's bindings to delete entries from the listing.
```
let g:FerretAcksCommand='cfdo'
```
g:FerretLacksCommand
### `g:FerretLacksCommand` (string, default: "ldo")
Controls the underlying Vim command that [`:Lacks`](#user-content-lacks) uses to peform substitutions. On versions of Vim that have it, defaults to `:ldo`, which means that substitutions will apply to the specific lines currently in the `location-list`. Can be set to "lfdo" to instead use `:lfdo` (if available), which means that the substitutions will be applied on a per-file basis to all the files in the `location-list`. This distinction is important if you have used Ferret's bindings to delete entries from the listing.
```
let g:FerretLacksCommand='lfdo'
```
g:FerretVeryMagic
### `g:FerretVeryMagic` (boolean, default: 1)
Controls whether the [`(FerretAck)`](#user-content-plugferretack) mapping should populate the command line with the `/\v` "very magic" marker. Given that the argument passed to [`:Acks`](#user-content-acks) is handed straight to Vim, using "very magic" makes it more likely that the (probably Perl-compatible) regular expression used in the initial search can be used directly with Vim's (famously not-Perl-compatible) regular expression engine.
To prevent the automatic use of `/\v`, set this option to 0:
```
let g:FerretVeryMagic=0
```
g:FerretExecutable
### `g:FerretExecutable` (string, default: "rg,ag,ack,ack-grep")
Ferret will preferentially use `rg`, `ag` and finally `ack`/`ack-grep` (in that order, using the first found executable), however you can force your preference for a specific tool to be used by setting an override in your `.vimrc`. Valid values are a comma-separated list of "rg", "ag", "ack" or "ack-grep". If no requested executable exists, Ferret will fall-back to the next in the default list.
Example:
```
" Prefer `ag` over `rg`.
let g:FerretExecutable='ag,rg'
```
g:FerretExecutableArguments
### `g:FerretExecutableArguments` (dict, default: {})
Allows you to override the default arguments that get passed to the underlying search executables. For example, to add `-s` to the default arguments passed to `ack` (`--column --with-filename`):
```
let g:FerretExecutableArguments = {
\ 'ack': '--column --with-filename -s'
\ }
```
To find out the default arguments for a given executable, see [`ferret#get_default_arguments()`](#user-content-ferretgetdefaultarguments).
g:FerretMaxResults
### `g:FerretMaxResults` (number, default: 100000)
Controls the maximum number of results Ferret will attempt to gather before displaying the results. Note that this only applies when searching asynchronously; that is, on recent versions of Vim with `+job` support and when [`g:FerretJob`](#user-content-gferretjob) is not set to 0.
The intent of this option is to prevent runaway search processes that produce huge volumes of output (for example, searching for a common string like "test" inside a `$HOME` directory containing millions of files) from locking up Vim.
In the event that Ferret aborts a search that has hit the [`g:FerretMaxResults`](#user-content-gferretmaxresults) limit, a message will be printed prompting users to run the search again with [`:Ack!`](#user-content-ack) or [`:Lack!`](#user-content-lack) if they want to bypass the limit.
g:FerretAutojump
### `g:FerretAutojump` (number, default: 1)
Controls whether Ferret will automatically jump to the first found match.
- Set to 0, Ferret will show the search results but perform no jump.
- Set to 1 (the default), Ferret will show the search results and focus the result listing.
- Set to 2, Ferret will show the search results and jump to the first found match.
Example override:
```
let g:FerretAutojump=2
```
g:FerretQFHandler
### `g:FerretQFHandler` (string, default: "botright copen")
Allows you to override the mechanism that opens the `quickfix` window to display search results.
g:FerretLLHandler
### `g:FerretLLHandler` (string, default: "lopen")
Allows you to override the mechanism that opens the `location-list` window to display search results.
g:FerretQFOptions
### `g:FerretQFOptions` (boolean, default: 1)
Controls whether to set up setting overrides for `quickfix` windows. These are various settings, such as `norelativenumber`, `nolist` and `nowrap`, that are intended to make the `quickfix` window, which is typically very small relative to other windows, more usable.
A full list of overridden settings can be found in [`ferret-overrides`](#user-content-ferret-overrides).
To prevent the custom settings from being applied, set [`g:FerretQFOptions`](#user-content-gferretqfoptions) to 0:
```
let g:FerretQFOptions=0
```
g:FerretQFMap
### `g:FerretQFMap` (boolean, default: 1)
Controls whether to set up mappings in the `quickfix` results window and `location-list` for deleting results. The mappings include:
- `d` (`visual-mode`): delete visual selection
- `dd` (`Normal-mode`): delete current line
- `d`{motion} (`Normal-mode`): delete range indicated by {motion}
To prevent these mappings from being set up, set to 0:
```
let g:FerretQFMap=0
```
g:FerretLoaded
### `g:FerretLoaded` (any, default: none)
To prevent Ferret from being loaded, set [`g:FerretLoaded`](#user-content-gferretloaded) to any value in your `.vimrc`. For example:
```
let g:FerretLoaded=1
```
g:FerretLazyInit
### `g:FerretLazyInit` (boolean, default: 1)
In order to minimize impact on Vim start-up time Ferret will initialize itself lazily on first use by default. If you wish to force immediate initialization (for example, to cause `'grepprg'` and `'grepformat'` to be set as soon as Vim launches), then set [`g:FerretLazyInit`](#user-content-gferretlazyinit) to 0 in your `.vimrc`:
```
let g:FerrerLazyInit=0
```
g:FerretMap
### `g:FerretMap` (boolean, default: 1)
Controls whether to set up the Ferret mappings, such as [`(FerretAck)`](#user-content-plugferretack) (see [`ferret-mappings`](#user-content-ferret-mappings) for a full list). To prevent any mapping from being configured, set to 0:
```
let g:FerretMap=0
```
g:FerretQFCommands
### `g:FerretQFCommands` (boolean, default: 1)
Controls whether to set up custom versions of the `quickfix` commands, `:cn`, `:cnf`, `:cp` an `:cpf`. These overrides vertically center the match within the viewport on each jump. To prevent the custom versions from being configured, set to 0:
```
let g:FerretQFCommands=0
```
g:FerretFormat
### `g:FerretFormat` (string, default: "%f:%l:%c:%m")
Sets the '`grepformat`' used by Ferret.
## Functions
ferret#get_default_arguments()
### `ferret#get_default_arguments()`
Call this with an executable name to find out the default arguments that will be passed when invoking that executable. For example:
```
echo ferret#get_default_arguments('rg')
```
This may be useful if you wish to extend or otherwise modify the arguments by setting [`g:FerretExecutableArguments`](#user-content-gferretexecutablearguments).
## Custom autocommands
FerretDidWrite FerretWillWrite
For maximum compatibility with other plug-ins, Ferret runs the following "User" autocommands before and after running the file writing operations during [`:Acks`](#user-content-acks) or [`:Lacks`](#user-content-lacks):
- FerretWillWrite
- FerretDidWrite
For example, to call a pair of custom functions in response to these events, you might do:
```
autocmd! User FerretWillWrite
autocmd User FerretWillWrite call CustomWillWrite()
autocmd! User FerretDidWrite
autocmd User FerretDidWrite call CustomDidWrite()
```
## Overrides
Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially setting `rg`, `ag`, `ack` or `ack-grep` as the 'grepprg' (in that order) and configuring a suitable 'grepformat'.
Additionally, Ferret includes an `ftplugin` for the `quickfix` listing that adjusts a number of settings to improve the usability of search results.
ferret-nolist
### 'nolist'
Turned off to reduce visual clutter in the search results, and because 'list' is most useful in files that are being actively edited, which is not the case for `quickfix` results.
ferret-norelativenumber
### 'norelativenumber'
Turned off, because it is more useful to have a sense of absolute progress through the results list than to have the ability to jump to nearby results (especially seeing as the most common operations are moving to the next or previous file, which are both handled nicely by `:cnf` and `:cpf` respectively).
ferret-nowrap
### 'nowrap'
Turned off to avoid ugly wrapping that makes the results list hard to read, and because in search results, the most relevant information is the filename, which is on the left and is usually visible even without wrapping.
ferret-number
### 'number'
Turned on to give a sense of absolute progress through the results.
ferret-scrolloff
### 'scrolloff'
Set to 0 because the `quickfix` listing is usually small by default, so trying to keep the current line away from the edge of the viewpoint is futile; by definition it is usually near the edge.
ferret-nocursorline
### 'nocursorline'
Turned off to reduce visual clutter.
To prevent any of these `quickfix`-specific overrides from being set up, you can set [`g:FerretQFOptions`](#user-content-gferretqfoptions) to 0 in your `.vimrc`:
```
let g:FerretQFOptions=0
```
## Troubleshooting
ferret-quotes
### Ferret fails to find patterns containing spaces
As described in the documentation for [`:Ack`](#user-content-ack), the search pattern is passed through as-is to the underlying search command, and no escaping is required other than preceding spaces by a single backslash.
So, to find "foo bar", you would search like:
```
:Ack foo\ bar
```
Unescaped spaces in the search are treated as argument separators, so a command like the following means pass the `-w` option through, search for pattern "foo", and limit search to the "bar" directory:
```
:Ack -w foo bar
```
Note that including quotes will not do what you intend.
```
" Search for '"foo' in the 'bar"' directory:
:Ack "foo bar"
" Search for "'foo' in the "bar'" directory:
:Ack 'foo bar'
```
This approach to escaping is taken in order to make it straightfoward to use powerful Perl-compatible regular expression syntax in an unambiguous way without having to worry about shell escaping rules:
```
:Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
```
## FAQ
### Why do Ferret commands start with "Ack", "Lack" and so on?
Ferret was originally the thinnest of wrappers (7 lines of code in my `.vimrc`) around `ack`. The earliest traces of it can be seen in the initial commit to my dotfiles repo in May, 2009 (https://wincent.com/h).
So, even though Ferret has a new name now and actually prefers `rg` then `ag` over `ack`/`ack-grep` when available, I prefer to keep the command names intact and benefit from years of accumulated muscle-memory.
## Related
Just as Ferret aims to improve the multi-file search and replace experience, Loupe does the same for within-file searching:
https://github.com/wincent/loupe
## Website
The official Ferret source code repo is at:
http://git.wincent.com/ferret.git
A mirror exists at:
https://github.com/wincent/ferret
Official releases are listed at:
http://www.vim.org/scripts/script.php?script_id=5220
## License
Copyright 2015-present Greg Hurrell. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
## Development
### Contributing patches
Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/ferret/pulls
### Cutting a new release
At the moment the release process is manual:
- Perform final sanity checks and manual testing
- Update the [`ferret-history`](#user-content-ferret-history) section of the documentation
- Verify clean work tree:
```
git status
```
- Tag the release:
```
git tag -s -m "$VERSION release" $VERSION
```
- Publish the code:
```
git push origin master --follow-tags
git push github master --follow-tags
```
- Produce the release archive:
```
git archive -o ferret-$VERSION.zip HEAD -- .
```
- Upload to http://www.vim.org/scripts/script.php?script_id=5220
## Authors
Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
Other contributors that have submitted patches include (in alphabetical order):
- Daniel Silva
- Filip Szymański
- Joe Lencioni
- Jon Parise
- Nelo-Thara Wallus
- Tom Dooner
- Vaibhav Sagar
## History
### 5.0 (8 June 2019)
- The [`(FerretAcks)`](#user-content-plugferretacks) mapping now uses `/\v` "very magic" mode by default. This default can be changed using the [`g:FerretVeryMagic`](#user-content-gferretverymagic) option.
- [`:Acks`](#user-content-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`](#user-content-gferretackscommand) option.
- Ferret now has a [`:Lacks`](#user-content-lacks) command, an analog to [`:Acks`](#user-content-acks) which applies to the `location-list`.
- Likewise, Ferret now has a [`:Largs`](#user-content-largs) command, analogous to [`:Qargs`](#user-content-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`](#user-content-gferretqfmap) is enabled now also apply to the `location-list`.
### 4.1 (31 January 2019)
- Added [`:Quack`](#user-content-quack) command, analogous to [`:Ack`](#user-content-ack) but scoped to the files currently listed in the `quickfix` window.
- Fixed option autocompletion.
### 4.0.2 (11 January 2019)
- Restore compatibility with versions of `rg` prior to v0.8 (https://github.com/wincent/ferret/issues/59).
### 4.0.1 (8 January 2019)
- Make [`:Acks`](#user-content-acks) behavior the same irrespective of the `'gdefault'` setting.
### 4.0 (25 December 2018)
- Try to avoid "press ENTER to continue" prompts.
- Put search term in `w:quickfix_title` for use in statuslines (https://github.com/wincent/ferret/pull/57).
- Add [`g:FerretExecutableArguments`](#user-content-gferretexecutablearguments) and [`ferret#get_default_arguments()`](#user-content-ferretgetdefaultarguments) (https://github.com/wincent/ferret/pull/46).
### 3.0.3 (23 March 2018)
- Fix for [`:Lack`](#user-content-lack) results opening in quickfix listing in Neovim (https://github.com/wincent/ferret/issues/47).
### 3.0.2 (25 October 2017)
- Fix broken [`:Back`](#user-content-back) and [`:Black`](#user-content-black) commands (https://github.com/wincent/ferret/issues/48).
### 3.0.1 (24 August 2017)
- Fix failure to handle search patterns containing multiple escaped spaces (https://github.com/wincent/ferret/issues/49).
### 3.0 (13 June 2017)
- Improve handling of backslash escapes (https://github.com/wincent/ferret/issues/41).
- Add [`g:FerretAutojump`](#user-content-gferretautojump).
- Drop support for vim-dispatch.
### 2.0 (6 June 2017)
- Add support for Neovim, along with [`g:FerretNvim`](#user-content-gferretnvim) setting.
### 1.5 "Cinco de Cuatro" (4 May 2017)
- Improvements to the handling of very large result sets (due to wide lines or many results).
- Added [`g:FerretLazyInit`](#user-content-gferretlazyinit).
- Added missing documentation for [`g:FerretJob`](#user-content-gferretjob).
- Added [`g:FerretMaxResults`](#user-content-gferretmaxresults).
- 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.
### 1.4 (21 January 2017)
- 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.
### 1.3 (8 January 2017)
- Reset `'errorformat'` before each search (fixes issue #31).
- Added [`:Back`](#user-content-back) and [`:Black`](#user-content-black) commands, analogous to [`:Ack`](#user-content-ack) and [`:Lack`](#user-content-lack) but scoped to search within currently open buffers only.
- Change [`:Acks`](#user-content-acks) to use `:cfdo` when available rather than [`:Qargs`](#user-content-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`).
### 1.2a (16 May 2016)
- Add optional support for running searches asynchronously using Vim's `+job` feature (enabled by default in sufficiently recent versions of Vim); see [`g:FerretJob`](#user-content-gferretjob), [`:FerretCancelAsync`](#user-content-ferretcancelasync) and [`:FerretPullAsync`](#user-content-ferretpullasync).
### 1.1.1 (7 March 2016)
- Fix another edge case when searching for patterns containing "#", only manifesting under dispatch.vim.
### 1.1 (7 March 2016)
- 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`](#user-content-ack) and [`:Lack`](#user-content-lack).
- Fix display of error messages under dispatch.vim.
### 1.0 (28 December 2015)
- Fix broken [`:Qargs`](#user-content-qargs) command (patch from Daniel Silva).
- Add [`g:FerretQFHandler`](#user-content-gferretqfhandler) and [`g:FerretLLHandler`](#user-content-gferretllhandler) options (patch from Daniel Silva).
- Make `` mappings accessible even [`g:FerretMap`](#user-content-gferretmap) 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.
### 0.3 (24 July 2015)
- Added highlighting of search pattern and related [`g:FerretHlsearch`](#user-content-gferrethlsearch) option (patch from Nelo-Thara Wallus).
- Add better error reporting for failed or incorrect searches.
### 0.2 (16 July 2015)
- Added [`FerretDidWrite`](#user-content-ferretdidwrite) and [`FerretWillWrite`](#user-content-ferretwillwrite) autocommands (patch from Joe Lencioni).
- Add [`(FerretAcks)`](#user-content-plugferretacks) mapping (patch from Nelo-Thara Wallus).
### 0.1 (8 July 2015)
- Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).
