]> git.wincent.com - docvim.git/blob - tests/fixtures/integration/ferret/golden/markdown.golden
fix: add extra space after images
[docvim.git] / tests / fixtures / integration / ferret / golden / markdown.golden
1 <p align="center">
2   <img src="https://raw.githubusercontent.com/wincent/ferret/media/ferret.jpg" />
3 </p>
4
5 <p align="center">
6   <img src="https://raw.githubusercontent.com/wincent/ferret/media/ferret.gif" />
7 </p>
8
9 # ferret<a name="ferret-ferret" href="#user-content-ferret-ferret"></a>
10
11 ## Intro<a name="ferret-intro" href="#user-content-ferret-intro"></a>
12
13 > &quot;ferret (verb)<br />(ferret something out) search tenaciously for and find something: she had the ability to ferret out the facts.&quot;
14
15 <p align="right"><a name="ferret-features" href="#user-content-ferret-features"><code>ferret-features</code></a></p>
16
17 Ferret improves Vim's multi-file search in four ways:
18
19 ### 1. Powerful multi-file search<a name="ferret-1-powerful-multi-file-search" href="#user-content-ferret-1-powerful-multi-file-search"></a>
20
21 Ferret provides an <strong>[`:Ack`](#user-content-ack)</strong> 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).
22
23 Shortcut mappings are provided to start an <strong>[`:Ack`](#user-content-ack)</strong> search (&lt;leader&gt;a) or to search for the word currently under the cursor (&lt;leader&gt;s).
24
25 Results are normally displayed in the <strong>`quickfix`</strong> window, but Ferret also provides a <strong>[`:Lack`](#user-content-lack)</strong> command that behaves like <strong>[`:Ack`](#user-content-ack)</strong> but uses the <strong>`location-list`</strong> instead, and a &lt;leader&gt;l mapping as a shortcut to <strong>[`:Lack`](#user-content-lack)</strong>.
26
27 <strong>[`:Back`](#user-content-back)</strong> and <strong>[`:Black`](#user-content-black)</strong> are analogous to <strong>[`:Ack`](#user-content-ack)</strong> and <strong>[`:Lack`](#user-content-lack)</strong>, but scoped to search within currently open buffers only. <strong>[`:Quack`](#user-content-quack)</strong> is scoped to search among the files currently in the <strong>`quickfix`</strong> list.
28
29 ### 2. Streamlined multi-file replace<a name="ferret-2-streamlined-multi-file-replace" href="#user-content-ferret-2-streamlined-multi-file-replace"></a>
30
31 The companion to <strong>[`:Ack`](#user-content-ack)</strong> is <strong>[`:Acks`](#user-content-acks)</strong> (mnemonic: &quot;Ack substitute&quot;, accessible via shortcut &lt;leader&gt;r), which allows you to run a multi-file replace across all the files placed in the <strong>`quickfix`</strong> window by a previous invocation of <strong>[`:Ack`](#user-content-ack)</strong> (or <strong>[`:Back`](#user-content-back)</strong>, or <strong>[`:Quack`](#user-content-quack)</strong>).
32
33 Correspondingly, results obtained by <strong>[`:Lack`](#user-content-lack)</strong> can be targeted for replacement with <strong>[`:Lacks`](#user-content-lacks)</strong>.
34
35 ### 3. Quickfix listing enhancements<a name="ferret-3-quickfix-listing-enhancements" href="#user-content-ferret-3-quickfix-listing-enhancements"></a>
36
37 The <strong>`quickfix`</strong> 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).
38
39 Additionally, Vim's <strong>`:cn`</strong>, <strong>`:cp`</strong>, <strong>`:cnf`</strong> and <strong>`:cpf`</strong> commands are tweaked to make it easier to immediately identify matches by centering them within the viewport.
40
41 ### 4. Easy operations on files in the quickfix listing<a name="ferret-4-easy-operations-on-files-in-the-quickfix-listing" href="#user-content-ferret-4-easy-operations-on-files-in-the-quickfix-listing"></a>
42
43 Finally, Ferret provides a <strong>[`:Qargs`](#user-content-qargs)</strong> command that puts the files currently in the <strong>`quickfix`</strong> listing into the <strong>`:args`</strong> list, where they can be operated on in bulk via the <strong>`:argdo`</strong> command. This is what's used under the covers on older versions of Vim by <strong>[`:Acks`](#user-content-acks)</strong> to do its work (on newer versions the built-in <strong>`:cdo`</strong> or <strong>`:cfdo`</strong> are used instead).
44
45 Ferret also provides a <strong>[`:Largs`](#user-content-largs)</strong> command, which is a <strong>`location-list`</strong> analog for <strong>[`:Qargs`](#user-content-qargs)</strong>.
46
47 ## Installation<a name="ferret-installation" href="#user-content-ferret-installation"></a>
48
49 To install Ferret, use your plug-in management system of choice.
50
51 If you don't have a &quot;plug-in management system of choice&quot;, I recommend Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and robustness. Assuming that you have Pathogen installed and configured, and that you want to install Ferret into `~/.vim/bundle`, you can do so with:
52
53 ```
54 git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
55 ```
56
57 Alternatively, if you use a Git submodule for each Vim plug-in, you could do the following after `cd`-ing into the top-level of your Git superproject:
58
59 ```
60 git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
61 git submodule init
62 ```
63
64 To generate help tags under Pathogen, you can do so from inside Vim with:
65
66 ```
67 :call pathogen#helptags()
68 ```
69
70 ## Commands<a name="ferret-commands" href="#user-content-ferret-commands"></a>
71
72 <p align="right"><a name="ack" href="#user-content-ack"><code>:Ack</code></a></p>
73
74 ### `:Ack {pattern} {options}`<a name="ferret-ack-pattern-options" href="#user-content-ferret-ack-pattern-options"></a>
75
76 Searches for {pattern} in all the files under the current directory (see <strong>`:pwd`</strong>), unless otherwise overridden via {options}, and displays the results in the <strong>`quickfix`</strong> listing.
77
78 `rg` (ripgrep) then `ag` (The Silver Searcher) will be used preferentially if present on the system, because they are faster, falling back to `ack`/`ack-grep` as needed.
79
80 On newer versions of Vim (version 8 and above), the search process runs asynchronously in the background and does not block the UI.
81
82 Asynchronous searches are preferred because they do not block, despite the fact that Vim itself is single threaded.
83
84 The {pattern} is passed through as-is to the underlying search program, and no escaping is required other than preceding spaces by a single backslash. For example, to search for &quot;\bfoo[0-9]{2} bar\b&quot; (ie. using `ag`'s Perl-style regular expression syntax), you could do:
85
86 ```
87 :Ack \bfoo[0-9]{2}\ bar\b
88 ```
89
90 Likewise, {options} are passed through. In this example, we pass the `-w` option (to search on word boundaries), and scope the search to the &quot;foo&quot; and &quot;bar&quot; subdirectories:
91
92 ```
93 :Ack -w something foo bar
94 ```
95
96 As a convenience &lt;leader&gt;a is set-up (<strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong>) as a shortcut to enter <strong>`Cmdline-mode`</strong> with `:Ack` inserted on the <strong>`Cmdline`</strong>. Likewise &lt;leader&gt;s (<strong>[`<Plug>(FerretAckWord)`](#user-content-plugferretackword)</strong>) is a shortcut for running <strong>[`:Ack`](#user-content-ack)</strong> with the word currently under the cursor.
97
98 <p align="right"><a name="ack" href="#user-content-ack"><code>:Ack!</code></a></p>
99
100 ### `:Ack! {pattern} {options}`<a name="ferret-ack-pattern-options" href="#user-content-ferret-ack-pattern-options"></a>
101
102 Like <strong>[`:Ack`](#user-content-ack)</strong>, but returns all results irrespective of the value of <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
103
104 <p align="right"><a name="lack" href="#user-content-lack"><code>:Lack</code></a></p>
105
106 ### `:Lack {pattern} {options}`<a name="ferret-lack-pattern-options" href="#user-content-ferret-lack-pattern-options"></a>
107
108 Just like <strong>[`:Ack`](#user-content-ack)</strong>, but instead of using the <strong>`quickfix`</strong> listing, which is global across an entire Vim instance, it uses the <strong>`location-list`</strong>, which is a per-window construct.
109
110 Note that <strong>[`:Lack`](#user-content-lack)</strong> always runs synchronously via <strong>`:cexpr`</strong>.
111
112 <p align="right"><a name="lack" href="#user-content-lack"><code>:Lack!</code></a></p>
113
114 ### `:Lack! {pattern} {options}`<a name="ferret-lack-pattern-options" href="#user-content-ferret-lack-pattern-options"></a>
115
116 Like <strong>[`:Lack`](#user-content-lack)</strong>, but returns all results irrespective of the value of <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
117
118 <p align="right"><a name="back" href="#user-content-back"><code>:Back</code></a></p>
119
120 ### `:Back {pattern} {options}`<a name="ferret-back-pattern-options" href="#user-content-ferret-back-pattern-options"></a>
121
122 Like <strong>[`:Ack`](#user-content-ack)</strong>, but searches only listed buffers. Note that the search is still delegated to the underlying <strong>`'grepprg'`</strong> (`rg`, `ag`, `ack` or `ack-grep`), which means that only buffers written to disk will be searched. If no buffers are written to disk, then <strong>[`:Back`](#user-content-back)</strong> behaves exactly like <strong>[`:Ack`](#user-content-ack)</strong> and will search all files in the current directory.
123
124 <p align="right"><a name="back" href="#user-content-back"><code>:Back!</code></a></p>
125
126 ### `:Back! {pattern} {options}`<a name="ferret-back-pattern-options" href="#user-content-ferret-back-pattern-options"></a>
127
128 Like <strong>[`:Back`](#user-content-back)</strong>, but returns all results irrespective of the value of <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
129
130 <p align="right"><a name="black" href="#user-content-black"><code>:Black</code></a></p>
131
132 ### `:Black {pattern} {options}`<a name="ferret-black-pattern-options" href="#user-content-ferret-black-pattern-options"></a>
133
134 Like <strong>[`:Lack`](#user-content-lack)</strong>, but searches only listed buffers. As with <strong>[`:Back`](#user-content-back)</strong>, the search is still delegated to the underlying <strong>`'grepprg'`</strong> (`rg`, `ag`, `ack` or `ack-grep`), which means that only buffers written to disk will be searched. Likewise, If no buffers are written to disk, then <strong>[`:Black`](#user-content-black)</strong> behaves exactly like <strong>[`:Lack`](#user-content-lack)</strong> and will search all files in the current directory.
135
136 <p align="right"><a name="black" href="#user-content-black"><code>:Black!</code></a></p>
137
138 ### `:Black! {pattern} {options}`<a name="ferret-black-pattern-options" href="#user-content-ferret-black-pattern-options"></a>
139
140 Like <strong>[`:Black`](#user-content-black)</strong>, but returns all results irrespective of the value of <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
141
142 <p align="right"><a name="quack" href="#user-content-quack"><code>:Quack</code></a></p>
143
144 ### `:Quack {pattern} {options}`<a name="ferret-quack-pattern-options" href="#user-content-ferret-quack-pattern-options"></a>
145
146 Like <strong>[`:Ack`](#user-content-ack)</strong>, but searches only among files currently in the <strong>`quickfix`</strong> listing. Note that the search is still delegated to the underlying <strong>`'grepprg'`</strong> (`rg`, `ag`, `ack` or `ack-grep`), which means that only buffers written to disk will be searched. If no buffers are written to disk, then <strong>[`:Quack`](#user-content-quack)</strong> behaves exactly like <strong>[`:Ack`](#user-content-ack)</strong> and will search all files in the current directory.
147
148 <p align="right"><a name="quack" href="#user-content-quack"><code>:Quack!</code></a></p>
149
150 ### `:Quack! {pattern} {options}`<a name="ferret-quack-pattern-options" href="#user-content-ferret-quack-pattern-options"></a>
151
152 Like <strong>[`:Quack`](#user-content-quack)</strong>, but returns all results irrespective of the value of <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
153
154 <p align="right"><a name="acks" href="#user-content-acks"><code>:Acks</code></a></p>
155
156 ### `:Acks /{pattern}/{replacement}/`<a name="ferret-acks-patternreplacement" href="#user-content-ferret-acks-patternreplacement"></a>
157
158 Takes all of the files currently in the <strong>`quickfix`</strong> listing and performs a substitution of all instances of {pattern} (a standard Vim search <strong>`pattern`</strong>) by {replacement}.
159
160 A typical sequence consists of an <strong>[`:Ack`](#user-content-ack)</strong> invocation to populate the <strong>`quickfix`</strong> listing and then <strong>[`:Acks`](#user-content-acks)</strong> (mnemonic: &quot;Ack substitute&quot;) to perform replacements. For example, to replace &quot;foo&quot; with &quot;bar&quot; across all files in the current directory:
161
162 ```
163 :Ack foo
164 :Acks /foo/bar/
165 ```
166
167 The pattern and replacement are passed through literally to Vim's <strong>`:substitute`</strong> command, preserving all characters and escapes, including references to matches in the pattern. For example, the following could be used to swap the order of &quot;foo123&quot; and &quot;bar&quot;:
168
169 ```
170 :Acks /\v(foo\d+)(bar)/\2\1/
171 ```
172
173 <p align="right"><a name="lacks" href="#user-content-lacks"><code>:Lacks</code></a></p>
174
175 ### `:Lacks /{pattern}/{replacement}/`<a name="ferret-lacks-patternreplacement" href="#user-content-ferret-lacks-patternreplacement"></a>
176
177 Takes all of the files in the current <strong>`location-list`</strong> and performs a substitution of all instances of {pattern} by {replacement}. This is an analog of the <strong>[`:Acks`](#user-content-acks)</strong> command, but operates on the <strong>`location-list`</strong> instead of the <strong>`quickfix`</strong> listing.
178
179 <p align="right"><a name="ferretcancelasync" href="#user-content-ferretcancelasync"><code>:FerretCancelAsync</code></a></p>
180
181 ### `:FerretCancelAsync`<a name="ferret-ferretcancelasync" href="#user-content-ferret-ferretcancelasync"></a>
182
183 Cancels any asynchronous search that may be in progress in the background.
184
185 <p align="right"><a name="ferretpullasync" href="#user-content-ferretpullasync"><code>:FerretPullAsync</code></a></p>
186
187 ### `:FerretPullAsync`<a name="ferret-ferretpullasync" href="#user-content-ferret-ferretpullasync"></a>
188
189 Eagerly populates the <strong>`quickfix`</strong> (or <strong>`location-list`</strong>) window with any results that may have been produced by a long-running asynchronous search in progress in the background.
190
191 <p align="right"><a name="qargs" href="#user-content-qargs"><code>:Qargs</code></a></p>
192
193 ### `:Qargs`<a name="ferret-qargs" href="#user-content-ferret-qargs"></a>
194
195 This is a utility function that is used internally when running on older versions of Vim (prior to version 8) but is also generally useful enough to warrant being exposed publicly.
196
197 It takes the files currently in the <strong>`quickfix`</strong> listing and sets them as <strong>`:args`</strong> so that they can be operated on en masse via the <strong>`:argdo`</strong> command.
198
199 <p align="right"><a name="largs" href="#user-content-largs"><code>:Largs</code></a></p>
200
201 ### `:Largs`<a name="ferret-largs" href="#user-content-ferret-largs"></a>
202
203 Just like <strong>[`:Qargs`](#user-content-qargs)</strong>, but applies to the current <strong>`location-list`</strong>.
204
205 It takes the files in the current <strong>`location-list`</strong> and sets them as <strong>`:args`</strong> so that they can be operated on en masse via the <strong>`:argdo`</strong> command.
206
207 ## Mappings<a name="ferret-mappings" href="#user-content-ferret-mappings"></a>
208
209 ### Circumstances where mappings do not get set up<a name="ferret-circumstances-where-mappings-do-not-get-set-up" href="#user-content-ferret-circumstances-where-mappings-do-not-get-set-up"></a>
210
211 Note that Ferret will not try to set up the &lt;leader&gt; mappings if any of the following are true:
212
213 - A mapping with the same <strong>`{lhs}`</strong> already exists.
214 - An alternative mapping for the same functionality has already been set up from a <strong>`.vimrc`</strong>.
215 - The mapping has been suppressed by setting <strong>[`g:FerretMap`](#user-content-gferretmap)</strong> to 0 in your <strong>`.vimrc`</strong>.
216
217 ### Mappings specific to the quickfix window<a name="ferret-mappings-specific-to-the-quickfix-window" href="#user-content-ferret-mappings-specific-to-the-quickfix-window"></a>
218
219 Additionally, Ferret will set up special mappings in <strong>`quickfix`</strong> listings, unless prevented from doing so by <strong>[`g:FerretQFMap`](#user-content-gferretqfmap)</strong>:
220
221 - `d` (<strong>`visual-mode`</strong>): delete visual selection
222 - `dd` (<strong>`Normal-mode`</strong>): delete current line
223 - `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
224
225 ### `<Plug>(FerretAck)`<a name="ferret-plugferretack" href="#user-content-ferret-plugferretack"></a>
226
227 Ferret maps &lt;leader&gt;a to <strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong>, which triggers the <strong>[`:Ack`](#user-content-ack)</strong> command. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
228
229 ```
230 " Instead of <leader>a, use <leader>x.
231 nmap <leader>x <Plug>(FerretAck)
232 ```
233
234 ### `<Plug>(FerretLack)`<a name="ferret-plugferretlack" href="#user-content-ferret-plugferretlack"></a>
235
236 Ferret maps &lt;leader&gt;l to <strong>[`<Plug>(FerretLack)`](#user-content-plugferretlack)</strong>, which triggers the <strong>[`:Lack`](#user-content-lack)</strong> command. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
237
238 ```
239 " Instead of <leader>l, use <leader>y.
240 nmap <leader>y <Plug>(FerretLack)
241 ```
242
243 ### `<Plug>(FerretAckWord)`<a name="ferret-plugferretackword" href="#user-content-ferret-plugferretackword"></a>
244
245 Ferret maps &lt;leader&gt;s (mnemonix: &quot;selection) to <strong>[`<Plug>(FerretAckWord)`](#user-content-plugferretackword)</strong>, which uses <strong>[`:Ack`](#user-content-ack)</strong> to search for the word currently under the cursor. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
246
247 ```
248 " Instead of <leader>s, use <leader>z.
249 nmap <leader>z <Plug>(FerretAckWord)
250 ```
251
252 ### `<Plug>(FerretAcks)`<a name="ferret-plugferretacks" href="#user-content-ferret-plugferretacks"></a>
253
254 Ferret maps &lt;leader&gt;r (mnemonic: &quot;replace&quot;) to <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong>, which triggers the <strong>[`:Acks`](#user-content-acks)</strong> command and fills the prompt with the last search term from Ferret. to use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
255
256 ```
257 " Instead of <leader>r, use <leader>u.
258 nmap <leader>u <Plug>(FerretAcks)
259 ```
260
261 ## Options<a name="ferret-options" href="#user-content-ferret-options"></a>
262
263 <p align="right"><a name="gferretnvim" href="#user-content-gferretnvim"><code>g:FerretNvim</code></a></p>
264
265 ### `g:FerretNvim` (boolean, default: 1)<a name="ferret-gferretnvim-boolean-default-1" href="#user-content-ferret-gferretnvim-boolean-default-1"></a>
266
267 Controls whether to use Neovim's <strong>`job-control`</strong> 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 <strong>[`g:FerretJob`](#user-content-gferretjob)</strong> -- which are typically not available in Neovim, so will then fall back to the next available method).
268
269 ```
270 let g:FerretNvim=0
271 ```
272
273 <p align="right"><a name="gferretjob" href="#user-content-gferretjob"><code>g:FerretJob</code></a></p>
274
275 ### `g:FerretJob` (boolean, default: 1)<a name="ferret-gferretjob-boolean-default-1" href="#user-content-ferret-gferretjob-boolean-default-1"></a>
276
277 Controls whether to use Vim's <strong>`+job`</strong> feature, when available, to run searches asynchronously. To prevent <strong>`+job`</strong> from being used, set to 0, in which case Ferret will fall back to the next available method.
278
279 ```
280 let g:FerretJob=0
281 ```
282
283 <p align="right"><a name="gferrethlsearch" href="#user-content-gferrethlsearch"><code>g:FerretHlsearch</code></a></p>
284
285 ### `g:FerretHlsearch` (boolean, default: none)<a name="ferret-gferrethlsearch-boolean-default-none" href="#user-content-ferret-gferrethlsearch-boolean-default-none"></a>
286
287 Controls whether Ferret should attempt to highlight the search pattern when running <strong>[`:Ack`](#user-content-ack)</strong> or <strong>[`:Lack`](#user-content-lack)</strong>. If left unset, Ferret will respect the current 'hlsearch' setting. To force highlighting on or off irrespective of 'hlsearch', set <strong>[`g:FerretHlsearch`](#user-content-gferrethlsearch)</strong> to 1 (on) or 0 (off):
288
289 ```
290 let g:FerretHlsearch=0
291 ```
292
293 <p align="right"><a name="gferretackscommand" href="#user-content-gferretackscommand"><code>g:FerretAcksCommand</code></a></p>
294
295 ### `g:FerretAcksCommand` (string, default: "cdo")<a name="ferret-gferretackscommand-string-default-cdo" href="#user-content-ferret-gferretackscommand-string-default-cdo"></a>
296
297 Controls the underlying Vim command that <strong>[`:Acks`](#user-content-acks)</strong> uses to peform substitutions. On versions of Vim that have it, defaults to <strong>`:cdo`</strong>, which means that substitutions will apply to the specific lines currently in the <strong>`quickfix`</strong> listing. Can be set to &quot;cfdo&quot; to instead use <strong>`:cfdo`</strong> (if available), which means that the substitutions will be applied on a per-file basis to all the files in the <strong>`quickfix`</strong> listing. This distinction is important if you have used Ferret's bindings to delete entries from the listing.
298
299 ```
300 let g:FerretAcksCommand='cfdo'
301 ```
302
303 <p align="right"><a name="gferretlackscommand" href="#user-content-gferretlackscommand"><code>g:FerretLacksCommand</code></a></p>
304
305 ### `g:FerretLacksCommand` (string, default: "ldo")<a name="ferret-gferretlackscommand-string-default-ldo" href="#user-content-ferret-gferretlackscommand-string-default-ldo"></a>
306
307 Controls the underlying Vim command that <strong>[`:Lacks`](#user-content-lacks)</strong> uses to peform substitutions. On versions of Vim that have it, defaults to <strong>`:ldo`</strong>, which means that substitutions will apply to the specific lines currently in the <strong>`location-list`</strong>. Can be set to &quot;lfdo&quot; to instead use <strong>`:lfdo`</strong> (if available), which means that the substitutions will be applied on a per-file basis to all the files in the <strong>`location-list`</strong>. This distinction is important if you have used Ferret's bindings to delete entries from the listing.
308
309 ```
310 let g:FerretLacksCommand='lfdo'
311 ```
312
313 <p align="right"><a name="gferretverymagic" href="#user-content-gferretverymagic"><code>g:FerretVeryMagic</code></a></p>
314
315 ### `g:FerretVeryMagic` (boolean, default: 1)<a name="ferret-gferretverymagic-boolean-default-1" href="#user-content-ferret-gferretverymagic-boolean-default-1"></a>
316
317 Controls whether the <strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong> mapping should populate the command line with the <strong>`/\v`</strong> &quot;very magic&quot; marker. Given that the argument passed to <strong>[`:Acks`](#user-content-acks)</strong> is handed straight to Vim, using &quot;very magic&quot; 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.
318
319 To prevent the automatic use of <strong>`/\v`</strong>, set this option to 0:
320
321 ```
322 let g:FerretVeryMagic=0
323 ```
324
325 <p align="right"><a name="gferretexecutable" href="#user-content-gferretexecutable"><code>g:FerretExecutable</code></a></p>
326
327 ### `g:FerretExecutable` (string, default: "rg,ag,ack,ack-grep")<a name="ferret-gferretexecutable-string-default-rgagackack-grep" href="#user-content-ferret-gferretexecutable-string-default-rgagackack-grep"></a>
328
329 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 <strong>`.vimrc`</strong>. Valid values are a comma-separated list of &quot;rg&quot;, &quot;ag&quot;, &quot;ack&quot; or &quot;ack-grep&quot;. If no requested executable exists, Ferret will fall-back to the next in the default list.
330
331 Example:
332
333 ```
334 " Prefer `ag` over `rg`.
335 let g:FerretExecutable='ag,rg'
336 ```
337
338 <p align="right"><a name="gferretexecutablearguments" href="#user-content-gferretexecutablearguments"><code>g:FerretExecutableArguments</code></a></p>
339
340 ### `g:FerretExecutableArguments` (dict, default: {})<a name="ferret-gferretexecutablearguments-dict-default-" href="#user-content-ferret-gferretexecutablearguments-dict-default-"></a>
341
342 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`):
343
344 ```
345 let g:FerretExecutableArguments = {
346   \   'ack': '--column --with-filename -s'
347   \ }
348 ```
349
350 To find out the default arguments for a given executable, see <strong>[`ferret#get_default_arguments()`](#user-content-ferretgetdefaultarguments)</strong>.
351
352 <p align="right"><a name="gferretmaxresults" href="#user-content-gferretmaxresults"><code>g:FerretMaxResults</code></a></p>
353
354 ### `g:FerretMaxResults` (number, default: 100000)<a name="ferret-gferretmaxresults-number-default-100000" href="#user-content-ferret-gferretmaxresults-number-default-100000"></a>
355
356 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 <strong>`+job`</strong> support and when <strong>[`g:FerretJob`](#user-content-gferretjob)</strong> is not set to 0.
357
358 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 &quot;test&quot; inside a <strong>`$HOME`</strong> directory containing millions of files) from locking up Vim.
359
360 In the event that Ferret aborts a search that has hit the <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong> limit, a message will be printed prompting users to run the search again with <strong>[`:Ack!`](#user-content-ack)</strong> or <strong>[`:Lack!`](#user-content-lack)</strong> if they want to bypass the limit.
361
362 <p align="right"><a name="gferretautojump" href="#user-content-gferretautojump"><code>g:FerretAutojump</code></a></p>
363
364 ### `g:FerretAutojump` (number, default: 1)<a name="ferret-gferretautojump-number-default-1" href="#user-content-ferret-gferretautojump-number-default-1"></a>
365
366 Controls whether Ferret will automatically jump to the first found match.
367
368 - Set to 0, Ferret will show the search results but perform no jump.
369 - Set to 1 (the default), Ferret will show the search results and focus the result listing.
370 - Set to 2, Ferret will show the search results and jump to the first found match.
371
372 Example override:
373
374 ```
375 let g:FerretAutojump=2
376 ```
377
378 <p align="right"><a name="gferretqfhandler" href="#user-content-gferretqfhandler"><code>g:FerretQFHandler</code></a></p>
379
380 ### `g:FerretQFHandler` (string, default: "botright copen")<a name="ferret-gferretqfhandler-string-default-botright-copen" href="#user-content-ferret-gferretqfhandler-string-default-botright-copen"></a>
381
382 Allows you to override the mechanism that opens the <strong>`quickfix`</strong> window to display search results.
383
384 <p align="right"><a name="gferretllhandler" href="#user-content-gferretllhandler"><code>g:FerretLLHandler</code></a></p>
385
386 ### `g:FerretLLHandler` (string, default: "lopen")<a name="ferret-gferretllhandler-string-default-lopen" href="#user-content-ferret-gferretllhandler-string-default-lopen"></a>
387
388 Allows you to override the mechanism that opens the <strong>`location-list`</strong> window to display search results.
389
390 <p align="right"><a name="gferretqfoptions" href="#user-content-gferretqfoptions"><code>g:FerretQFOptions</code></a></p>
391
392 ### `g:FerretQFOptions` (boolean, default: 1)<a name="ferret-gferretqfoptions-boolean-default-1" href="#user-content-ferret-gferretqfoptions-boolean-default-1"></a>
393
394 Controls whether to set up setting overrides for <strong>`quickfix`</strong> windows. These are various settings, such as <strong>`norelativenumber`</strong>, <strong>`nolist`</strong> and <strong>`nowrap`</strong>, that are intended to make the <strong>`quickfix`</strong> window, which is typically very small relative to other windows, more usable.
395
396 A full list of overridden settings can be found in <strong>[`ferret-overrides`](#user-content-ferret-overrides)</strong>.
397
398 To prevent the custom settings from being applied, set <strong>[`g:FerretQFOptions`](#user-content-gferretqfoptions)</strong> to 0:
399
400 ```
401 let g:FerretQFOptions=0
402 ```
403
404 <p align="right"><a name="gferretqfmap" href="#user-content-gferretqfmap"><code>g:FerretQFMap</code></a></p>
405
406 ### `g:FerretQFMap` (boolean, default: 1)<a name="ferret-gferretqfmap-boolean-default-1" href="#user-content-ferret-gferretqfmap-boolean-default-1"></a>
407
408 Controls whether to set up mappings in the <strong>`quickfix`</strong> results window and <strong>`location-list`</strong> for deleting results. The mappings include:
409
410 - `d` (<strong>`visual-mode`</strong>): delete visual selection
411 - `dd` (<strong>`Normal-mode`</strong>): delete current line
412 - `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
413
414 To prevent these mappings from being set up, set to 0:
415
416 ```
417 let g:FerretQFMap=0
418 ```
419
420 <p align="right"><a name="gferretloaded" href="#user-content-gferretloaded"><code>g:FerretLoaded</code></a></p>
421
422 ### `g:FerretLoaded` (any, default: none)<a name="ferret-gferretloaded-any-default-none" href="#user-content-ferret-gferretloaded-any-default-none"></a>
423
424 To prevent Ferret from being loaded, set <strong>[`g:FerretLoaded`](#user-content-gferretloaded)</strong> to any value in your <strong>`.vimrc`</strong>. For example:
425
426 ```
427 let g:FerretLoaded=1
428 ```
429
430 <p align="right"><a name="gferretlazyinit" href="#user-content-gferretlazyinit"><code>g:FerretLazyInit</code></a></p>
431
432 ### `g:FerretLazyInit` (boolean, default: 1)<a name="ferret-gferretlazyinit-boolean-default-1" href="#user-content-ferret-gferretlazyinit-boolean-default-1"></a>
433
434 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 <strong>`'grepprg'`</strong> and <strong>`'grepformat'`</strong> to be set as soon as Vim launches), then set <strong>[`g:FerretLazyInit`](#user-content-gferretlazyinit)</strong> to 0 in your <strong>`.vimrc`</strong>:
435
436 ```
437 let g:FerrerLazyInit=0
438 ```
439
440 <p align="right"><a name="gferretmap" href="#user-content-gferretmap"><code>g:FerretMap</code></a></p>
441
442 ### `g:FerretMap` (boolean, default: 1)<a name="ferret-gferretmap-boolean-default-1" href="#user-content-ferret-gferretmap-boolean-default-1"></a>
443
444 Controls whether to set up the Ferret mappings, such as <strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong> (see <strong>[`ferret-mappings`](#user-content-ferret-mappings)</strong> for a full list). To prevent any mapping from being configured, set to 0:
445
446 ```
447 let g:FerretMap=0
448 ```
449
450 <p align="right"><a name="gferretqfcommands" href="#user-content-gferretqfcommands"><code>g:FerretQFCommands</code></a></p>
451
452 ### `g:FerretQFCommands` (boolean, default: 1)<a name="ferret-gferretqfcommands-boolean-default-1" href="#user-content-ferret-gferretqfcommands-boolean-default-1"></a>
453
454 Controls whether to set up custom versions of the <strong>`quickfix`</strong> commands, <strong>`:cn`</strong>, <strong>`:cnf`</strong>, <strong>`:cp`</strong> an <strong>`:cpf`</strong>. These overrides vertically center the match within the viewport on each jump. To prevent the custom versions from being configured, set to 0:
455
456 ```
457 let g:FerretQFCommands=0
458 ```
459
460 <p align="right"><a name="gferretformat" href="#user-content-gferretformat"><code>g:FerretFormat</code></a></p>
461
462 ### `g:FerretFormat` (string, default: "%f:%l:%c:%m")<a name="ferret-gferretformat-string-default-flcm" href="#user-content-ferret-gferretformat-string-default-flcm"></a>
463
464 Sets the '<strong>`grepformat`</strong>' used by Ferret.
465
466 ## Functions<a name="ferret-functions" href="#user-content-ferret-functions"></a>
467
468 <p align="right"><a name="ferretgetdefaultarguments" href="#user-content-ferretgetdefaultarguments"><code>ferret#get_default_arguments()</code></a></p>
469
470 ### `ferret#get_default_arguments()`<a name="ferret-ferretgetdefaultarguments" href="#user-content-ferret-ferretgetdefaultarguments"></a>
471
472 Call this with an executable name to find out the default arguments that will be passed when invoking that executable. For example:
473
474 ```
475 echo ferret#get_default_arguments('rg')
476 ```
477
478 This may be useful if you wish to extend or otherwise modify the arguments by setting <strong>[`g:FerretExecutableArguments`](#user-content-gferretexecutablearguments)</strong>.
479
480 ## Custom autocommands<a name="ferret-custom-autocommands" href="#user-content-ferret-custom-autocommands"></a>
481
482 <p align="right"><a name="ferretdidwrite" href="#user-content-ferretdidwrite"><code>FerretDidWrite</code></a> <a name="ferretwillwrite" href="#user-content-ferretwillwrite"><code>FerretWillWrite</code></a></p>
483
484 For maximum compatibility with other plug-ins, Ferret runs the following &quot;User&quot; autocommands before and after running the file writing operations during <strong>[`:Acks`](#user-content-acks)</strong> or <strong>[`:Lacks`](#user-content-lacks)</strong>:
485
486 - FerretWillWrite
487 - FerretDidWrite
488
489 For example, to call a pair of custom functions in response to these events, you might do:
490
491 ```
492 autocmd! User FerretWillWrite
493 autocmd User FerretWillWrite call CustomWillWrite()
494 autocmd! User FerretDidWrite
495 autocmd User FerretDidWrite call CustomDidWrite()
496 ```
497
498 ## Overrides<a name="ferret-overrides" href="#user-content-ferret-overrides"></a>
499
500 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'.
501
502 Additionally, Ferret includes an <strong>`ftplugin`</strong> for the <strong>`quickfix`</strong> listing that adjusts a number of settings to improve the usability of search results.
503
504 <p align="right"><a name="ferret-nolist" href="#user-content-ferret-nolist"><code>ferret-nolist</code></a></p>
505
506 ### 'nolist'<a name="ferret-nolist" href="#user-content-ferret-nolist"></a>
507
508 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 <strong>`quickfix`</strong> results.
509
510 <p align="right"><a name="ferret-norelativenumber" href="#user-content-ferret-norelativenumber"><code>ferret-norelativenumber</code></a></p>
511
512 ### 'norelativenumber'<a name="ferret-norelativenumber" href="#user-content-ferret-norelativenumber"></a>
513
514 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 <strong>`:cnf`</strong> and <strong>`:cpf`</strong> respectively).
515
516 <p align="right"><a name="ferret-nowrap" href="#user-content-ferret-nowrap"><code>ferret-nowrap</code></a></p>
517
518 ### 'nowrap'<a name="ferret-nowrap" href="#user-content-ferret-nowrap"></a>
519
520 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.
521
522 <p align="right"><a name="ferret-number" href="#user-content-ferret-number"><code>ferret-number</code></a></p>
523
524 ### 'number'<a name="ferret-number" href="#user-content-ferret-number"></a>
525
526 Turned on to give a sense of absolute progress through the results.
527
528 <p align="right"><a name="ferret-scrolloff" href="#user-content-ferret-scrolloff"><code>ferret-scrolloff</code></a></p>
529
530 ### 'scrolloff'<a name="ferret-scrolloff" href="#user-content-ferret-scrolloff"></a>
531
532 Set to 0 because the <strong>`quickfix`</strong> 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.
533
534 <p align="right"><a name="ferret-nocursorline" href="#user-content-ferret-nocursorline"><code>ferret-nocursorline</code></a></p>
535
536 ### 'nocursorline'<a name="ferret-nocursorline" href="#user-content-ferret-nocursorline"></a>
537
538 Turned off to reduce visual clutter.
539
540 To prevent any of these <strong>`quickfix`</strong>-specific overrides from being set up, you can set <strong>[`g:FerretQFOptions`](#user-content-gferretqfoptions)</strong> to 0 in your <strong>`.vimrc`</strong>:
541
542 ```
543 let g:FerretQFOptions=0
544 ```
545
546 ## Troubleshooting<a name="ferret-troubleshooting" href="#user-content-ferret-troubleshooting"></a>
547
548 <p align="right"><a name="ferret-quotes" href="#user-content-ferret-quotes"><code>ferret-quotes</code></a></p>
549
550 ### Ferret fails to find patterns containing spaces<a name="ferret-ferret-fails-to-find-patterns-containing-spaces" href="#user-content-ferret-ferret-fails-to-find-patterns-containing-spaces"></a>
551
552 As described in the documentation for <strong>[`:Ack`](#user-content-ack)</strong>, 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.
553
554 So, to find &quot;foo bar&quot;, you would search like:
555
556 ```
557 :Ack foo\ bar
558 ```
559
560 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 &quot;foo&quot;, and limit search to the &quot;bar&quot; directory:
561
562 ```
563 :Ack -w foo bar
564 ```
565
566 Note that including quotes will not do what you intend.
567
568 ```
569  " Search for '"foo' in the 'bar"' directory:
570  :Ack "foo bar"
571
572  " Search for "'foo' in the "bar'" directory:
573  :Ack 'foo bar'
574 ```
575
576 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:
577
578 ```
579 :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
580 ```
581
582 ## FAQ<a name="ferret-faq" href="#user-content-ferret-faq"></a>
583
584 ### Why do Ferret commands start with "Ack", "Lack" and so on?<a name="ferret-why-do-ferret-commands-start-with-ack-lack-and-so-on" href="#user-content-ferret-why-do-ferret-commands-start-with-ack-lack-and-so-on"></a>
585
586 Ferret was originally the thinnest of wrappers (7 lines of code in my <strong>`.vimrc`</strong>) 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).
587
588 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.
589
590 ## Related<a name="ferret-related" href="#user-content-ferret-related"></a>
591
592 Just as Ferret aims to improve the multi-file search and replace experience, Loupe does the same for within-file searching:
593
594 https://github.com/wincent/loupe
595
596 ## Website<a name="ferret-website" href="#user-content-ferret-website"></a>
597
598 The official Ferret source code repo is at:
599
600 http://git.wincent.com/ferret.git
601
602 A mirror exists at:
603
604 https://github.com/wincent/ferret
605
606 Official releases are listed at:
607
608 http://www.vim.org/scripts/script.php?script_id=5220
609
610 ## License<a name="ferret-license" href="#user-content-ferret-license"></a>
611
612 Copyright 2015-present Greg Hurrell. All rights reserved.
613
614 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
615
616 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
617
618 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.
619
620 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS IS&quot; 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.
621
622 ## Development<a name="ferret-development" href="#user-content-ferret-development"></a>
623
624 ### Contributing patches<a name="ferret-contributing-patches" href="#user-content-ferret-contributing-patches"></a>
625
626 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/ferret/pulls
627
628 ### Cutting a new release<a name="ferret-cutting-a-new-release" href="#user-content-ferret-cutting-a-new-release"></a>
629
630 At the moment the release process is manual:
631
632 - Perform final sanity checks and manual testing
633 - Update the <strong>[`ferret-history`](#user-content-ferret-history)</strong> section of the documentation
634 - Verify clean work tree:
635
636 ```
637 git status
638 ```
639
640 - Tag the release:
641
642 ```
643 git tag -s -m "$VERSION release" $VERSION
644 ```
645
646 - Publish the code:
647
648 ```
649 git push origin master --follow-tags
650 git push github master --follow-tags
651 ```
652
653 - Produce the release archive:
654
655 ```
656 git archive -o ferret-$VERSION.zip HEAD -- .
657 ```
658
659 - Upload to http://www.vim.org/scripts/script.php?script_id=5220
660
661 ## Authors<a name="ferret-authors" href="#user-content-ferret-authors"></a>
662
663 Ferret is written and maintained by Greg Hurrell &lt;greg@hurrell.net&gt;.
664
665 Other contributors that have submitted patches include (in alphabetical order):
666
667 - Daniel Silva
668 - Filip SzymaƄski
669 - Joe Lencioni
670 - Jon Parise
671 - Nelo-Thara Wallus
672 - Tom Dooner
673 - Vaibhav Sagar
674
675 ## History<a name="ferret-history" href="#user-content-ferret-history"></a>
676
677 ### 5.0 (8 June 2019)<a name="ferret-50-8-june-2019" href="#user-content-ferret-50-8-june-2019"></a>
678
679 - The <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong> mapping now uses <strong>`/\v`</strong> &quot;very magic&quot; mode by default. This default can be changed using the <strong>[`g:FerretVeryMagic`](#user-content-gferretverymagic)</strong> option.
680 - <strong>[`:Acks`](#user-content-acks)</strong> now preferentially uses <strong>`:cdo`</strong> (rather than <strong>`:cfdo`</strong>) to make replacements, which means that it no longer operates on a per-file level and instead targets individual entries within the <strong>`quickfix`</strong> window. This is relevant if you've used Ferrets mappings to delete entries from the window. The old behavior can be restored with the <strong>[`g:FerretAcksCommand`](#user-content-gferretackscommand)</strong> option.
681 - Ferret now has a <strong>[`:Lacks`](#user-content-lacks)</strong> command, an analog to <strong>[`:Acks`](#user-content-acks)</strong> which applies to the <strong>`location-list`</strong>.
682 - Likewise, Ferret now has a <strong>[`:Largs`](#user-content-largs)</strong> command, analogous to <strong>[`:Qargs`](#user-content-qargs)</strong>, which applies to the <strong>`location-list`</strong> instead of the <strong>`quickfix`</strong> window.
683 - The Ferret bindings that are set-up in the <strong>`quickfix`</strong> window when <strong>[`g:FerretQFMap`](#user-content-gferretqfmap)</strong> is enabled now also apply to the <strong>`location-list`</strong>.
684
685 ### 4.1 (31 January 2019)<a name="ferret-41-31-january-2019" href="#user-content-ferret-41-31-january-2019"></a>
686
687 - Added <strong>[`:Quack`](#user-content-quack)</strong> command, analogous to <strong>[`:Ack`](#user-content-ack)</strong> but scoped to the files currently listed in the <strong>`quickfix`</strong> window.
688 - Fixed option autocompletion.
689
690 ### 4.0.2 (11 January 2019)<a name="ferret-402-11-january-2019" href="#user-content-ferret-402-11-january-2019"></a>
691
692 - Restore compatibility with versions of `rg` prior to v0.8 (https://github.com/wincent/ferret/issues/59).
693
694 ### 4.0.1 (8 January 2019)<a name="ferret-401-8-january-2019" href="#user-content-ferret-401-8-january-2019"></a>
695
696 - Make <strong>[`:Acks`](#user-content-acks)</strong> behavior the same irrespective of the <strong>`'gdefault'`</strong> setting.
697
698 ### 4.0 (25 December 2018)<a name="ferret-40-25-december-2018" href="#user-content-ferret-40-25-december-2018"></a>
699
700 - Try to avoid &quot;press ENTER to continue&quot; prompts.
701 - Put search term in <strong>`w:quickfix_title`</strong> for use in statuslines (https://github.com/wincent/ferret/pull/57).
702 - Add <strong>[`g:FerretExecutableArguments`](#user-content-gferretexecutablearguments)</strong> and <strong>[`ferret#get_default_arguments()`](#user-content-ferretgetdefaultarguments)</strong> (https://github.com/wincent/ferret/pull/46).
703
704 ### 3.0.3 (23 March 2018)<a name="ferret-303-23-march-2018" href="#user-content-ferret-303-23-march-2018"></a>
705
706 - Fix for <strong>[`:Lack`](#user-content-lack)</strong> results opening in quickfix listing in Neovim (https://github.com/wincent/ferret/issues/47).
707
708 ### 3.0.2 (25 October 2017)<a name="ferret-302-25-october-2017" href="#user-content-ferret-302-25-october-2017"></a>
709
710 - Fix broken <strong>[`:Back`](#user-content-back)</strong> and <strong>[`:Black`](#user-content-black)</strong> commands (https://github.com/wincent/ferret/issues/48).
711
712 ### 3.0.1 (24 August 2017)<a name="ferret-301-24-august-2017" href="#user-content-ferret-301-24-august-2017"></a>
713
714 - Fix failure to handle search patterns containing multiple escaped spaces (https://github.com/wincent/ferret/issues/49).
715
716 ### 3.0 (13 June 2017)<a name="ferret-30-13-june-2017" href="#user-content-ferret-30-13-june-2017"></a>
717
718 - Improve handling of backslash escapes (https://github.com/wincent/ferret/issues/41).
719 - Add <strong>[`g:FerretAutojump`](#user-content-gferretautojump)</strong>.
720 - Drop support for vim-dispatch.
721
722 ### 2.0 (6 June 2017)<a name="ferret-20-6-june-2017" href="#user-content-ferret-20-6-june-2017"></a>
723
724 - Add support for Neovim, along with <strong>[`g:FerretNvim`](#user-content-gferretnvim)</strong> setting.
725
726 ### 1.5 "Cinco de Cuatro" (4 May 2017)<a name="ferret-15-cinco-de-cuatro-4-may-2017" href="#user-content-ferret-15-cinco-de-cuatro-4-may-2017"></a>
727
728 - Improvements to the handling of very large result sets (due to wide lines or many results).
729 - Added <strong>[`g:FerretLazyInit`](#user-content-gferretlazyinit)</strong>.
730 - Added missing documentation for <strong>[`g:FerretJob`](#user-content-gferretjob)</strong>.
731 - Added <strong>[`g:FerretMaxResults`](#user-content-gferretmaxresults)</strong>.
732 - 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.
733
734 ### 1.4 (21 January 2017)<a name="ferret-14-21-january-2017" href="#user-content-ferret-14-21-january-2017"></a>
735
736 - Drop broken support for `grep`, printing a prompt to install `rg`, `ag`, or `ack`/`ack-grep` instead.
737 - If an `ack` executable is not found, search for `ack-grep`, which is the name used on Debian-derived distros.
738
739 ### 1.3 (8 January 2017)<a name="ferret-13-8-january-2017" href="#user-content-ferret-13-8-january-2017"></a>
740
741 - Reset <strong>`'errorformat'`</strong> before each search (fixes issue #31).
742 - Added <strong>[`:Back`](#user-content-back)</strong> and <strong>[`:Black`](#user-content-black)</strong> commands, analogous to <strong>[`:Ack`](#user-content-ack)</strong> and <strong>[`:Lack`](#user-content-lack)</strong> but scoped to search within currently open buffers only.
743 - Change <strong>[`:Acks`](#user-content-acks)</strong> to use <strong>`:cfdo`</strong> when available rather than <strong>[`:Qargs`](#user-content-qargs)</strong> and <strong>`:argdo`</strong>, to avoid polluting the <strong>`arglist`</strong>.
744 - Remove superfluous <strong>`QuickFixCmdPost`</strong> autocommands, resolving clash with Neomake plug-in (patch from Tom Dooner, #36).
745 - Add support for searching with ripgrep (`rg`).
746
747 ### 1.2a (16 May 2016)<a name="ferret-12a-16-may-2016" href="#user-content-ferret-12a-16-may-2016"></a>
748
749 - Add optional support for running searches asynchronously using Vim's <strong>`+job`</strong> feature (enabled by default in sufficiently recent versions of Vim); see <strong>[`g:FerretJob`](#user-content-gferretjob)</strong>, <strong>[`:FerretCancelAsync`](#user-content-ferretcancelasync)</strong> and <strong>[`:FerretPullAsync`](#user-content-ferretpullasync)</strong>.
750
751 ### 1.1.1 (7 March 2016)<a name="ferret-111-7-march-2016" href="#user-content-ferret-111-7-march-2016"></a>
752
753 - Fix another edge case when searching for patterns containing &quot;#&quot;, only manifesting under dispatch.vim.
754
755 ### 1.1 (7 March 2016)<a name="ferret-11-7-march-2016" href="#user-content-ferret-11-7-march-2016"></a>
756
757 - Fix edge case when searching for strings of the form &quot;&lt;foo&gt;&quot;.
758 - Fix edge case when searching for patterns containing &quot;#&quot; and &quot;%&quot;.
759 - Provide completion for `ag` and `ack` options when using <strong>[`:Ack`](#user-content-ack)</strong> and <strong>[`:Lack`](#user-content-lack)</strong>.
760 - Fix display of error messages under dispatch.vim.
761
762 ### 1.0 (28 December 2015)<a name="ferret-10-28-december-2015" href="#user-content-ferret-10-28-december-2015"></a>
763
764 - Fix broken <strong>[`:Qargs`](#user-content-qargs)</strong> command (patch from Daniel Silva).
765 - Add <strong>[`g:FerretQFHandler`](#user-content-gferretqfhandler)</strong> and <strong>[`g:FerretLLHandler`](#user-content-gferretllhandler)</strong> options (patch from Daniel Silva).
766 - Make <strong>`<Plug>`</strong> mappings accessible even <strong>[`g:FerretMap`](#user-content-gferretmap)</strong> is set to 0.
767 - Fix failure to report filename when using `ack` and explicitly scoping search to a single file (patch from Daniel Silva).
768 - When using `ag`, report multiple matches per line instead of just the first (patch from Daniel Silva).
769 - Improve content and display of error messages.
770
771 ### 0.3 (24 July 2015)<a name="ferret-03-24-july-2015" href="#user-content-ferret-03-24-july-2015"></a>
772
773 - Added highlighting of search pattern and related <strong>[`g:FerretHlsearch`](#user-content-gferrethlsearch)</strong> option (patch from Nelo-Thara Wallus).
774 - Add better error reporting for failed or incorrect searches.
775
776 ### 0.2 (16 July 2015)<a name="ferret-02-16-july-2015" href="#user-content-ferret-02-16-july-2015"></a>
777
778 - Added <strong>[`FerretDidWrite`](#user-content-ferretdidwrite)</strong> and <strong>[`FerretWillWrite`](#user-content-ferretwillwrite)</strong> autocommands (patch from Joe Lencioni).
779 - Add <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong> mapping (patch from Nelo-Thara Wallus).
780
781 ### 0.1 (8 July 2015)<a name="ferret-01-8-july-2015" href="#user-content-ferret-01-8-july-2015"></a>
782
783 - Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).