]> git.wincent.com - docvim.git/blob - tests/fixtures/integration/ferret/golden/markdown.golden
Add additional blank line above headings
[docvim.git] / tests / fixtures / integration / ferret / golden / markdown.golden
1
2 # ferret<a name="ferret-ferret" href="#user-content-ferret-ferret"></a>
3
4
5 ## Intro<a name="ferret-intro" href="#user-content-ferret-intro"></a>
6
7 > "ferret (verb)<br />(ferret something out) search tenaciously for and find something: she had the ability to ferret out the facts."
8
9 <p align="right"><a name="ferret-features" href="#user-content-ferret-features"><code>ferret-features</code></a></p>
10 Ferret improves Vim's multi-file search in four ways:
11
12
13 ### 1. Powerful multi-file search<a name="ferret-1-powerful-multi-file-search" href="#user-content-ferret-1-powerful-multi-file-search"></a>
14
15 Ferret provides an <strong>[`:Ack`](#user-content-ack)</strong> command for searching across multiple files using The Silver Searcher (https://github.com/ggreer/the_silver_searcher), Ack (http://beyondgrep.com/), or Grep (http://www.gnu.org/software/grep/). 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.
16
17 Shortcut mappings are provided to start an <strong>[`:Ack`](#user-content-ack)</strong> search (<leader>a) or to search for the word currently under the cursor (<leader>s).
18
19 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 <leader>l mapping as a shortcut to <strong>[`:Lack`](#user-content-lack)</strong>.
20
21 Finally, Ferret offers integration with dispatch.vim (https://github.com/tpope/vim-dispatch), which enables asynchronous searching despite the fact that Vim itself is single-threaded.
22
23
24 ### 2. Streamlined multi-file replace<a name="ferret-2-streamlined-multi-file-replace" href="#user-content-ferret-2-streamlined-multi-file-replace"></a>
25
26 The companion to <strong>[`:Ack`](#user-content-ack)</strong> is <strong>[`:Acks`](#user-content-acks)</strong> (mnemonic: "Ack substitute", accessible via shortcut <leader>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>.
27
28
29 ### 3. Quickfix listing enhancements<a name="ferret-3-quickfix-listing-enhancements" href="#user-content-ferret-3-quickfix-listing-enhancements"></a>
30
31 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).
32
33 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.
34
35
36 ### 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>
37
38 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 by <strong>[`:Acks`](#user-content-acks)</strong> to do its work.
39
40
41 ## Installation<a name="ferret-installation" href="#user-content-ferret-installation"></a>
42
43 To install Ferret, use your plug-in management system of choice.
44
45 If you don't have a "plug-in management system of choice", 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:
46
47 ```
48 git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
49 ```
50
51 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:
52
53 ```
54 git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
55 git submodule init
56 ```
57
58 To generate help tags under Pathogen, you can do so from inside Vim with:
59
60 ```
61 :call pathogen#helptags()
62 ```
63
64
65 ## Commands<a name="ferret-commands" href="#user-content-ferret-commands"></a>
66
67 <p align="right"><a name="ack" href="#user-content-ack"><code>:Ack</code></a></p>
68
69 ### `:Ack {pattern} {options}`<a name="ferret-ack-pattern-options" href="#user-content-ferret-ack-pattern-options"></a>
70
71 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.
72
73 `ag` (The Silver Searcher) will be used preferentially if present on the system, because it is faster, falling back to `ack` and then `grep` as needed.
74
75 If dispatch.vim is installed the search process will run asynchronously via the <strong>`:Make`</strong> command, otherwise it will be run synchronously via <strong>`:cexpr`</strong>. Asynchronous searches are preferred because they do not block, despite the fact that Vim itself is single threaded. The <strong>`g:FerretDispatch`</strong> option can be used to prevent the use of dispatch.vim.
76
77 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 "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style regular expression syntax), you could do:
78
79 ```
80 :Ack \bfoo[0-9]{2}\ bar\b
81 ```
82
83 Likewise, {options} are passed through. In this example, we pass the `-w` option (to search on word boundaries), and scope the search to the "foo" and "bar" subdirectories: >
84
85 ```
86 :Ack -w something foo bar
87 ```
88
89 As a convenience <leader>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 <leader>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.
90
91 <p align="right"><a name="lack" href="#user-content-lack"><code>:Lack</code></a></p>
92
93 ### `:Lack {pattern} {options}`<a name="ferret-lack-pattern-options" href="#user-content-ferret-lack-pattern-options"></a>
94
95 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.
96
97 Note that <strong>[`:Lack`](#user-content-lack)</strong> always runs synchronously via <strong>`:cexpr`</strong>, because dispatch.vim doesn't currently support the <strong>`location-list`</strong>.
98
99 <p align="right"><a name="acks" href="#user-content-acks"><code>:Acks</code></a></p>
100
101 ### `:Acks /{pattern}/{replacement}/`<a name="ferret-acks-patternreplacement" href="#user-content-ferret-acks-patternreplacement"></a>
102
103 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}.
104
105 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: "Ack substitute") to perform replacements. For example, to replace "foo" with "bar" across all files in the current directory:
106
107 ```
108 :Ack foo
109 :Acks /foo/bar/
110 ```
111
112 <p align="right"><a name="qargs" href="#user-content-qargs"><code>:Qargs</code></a></p>
113
114 ### `:Qargs`<a name="ferret-qargs" href="#user-content-ferret-qargs"></a>
115
116 This is a utility function that is used by the <strong>[`:Acks`](#user-content-acks)</strong> command but is also generally useful enough to warrant being exposed publicly.
117
118 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.
119
120
121 ## Mappings<a name="ferret-mappings" href="#user-content-ferret-mappings"></a>
122
123
124 ### 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>
125
126 Note that Ferret will not try to set up the <leader> mappings if any of the following are true:
127
128 - A mapping for already exists.
129 - An alternative mapping for the same functionality has already been set up from a <strong>`.vimrc`</strong>.
130 - The mapping has been suppressed by setting <strong>`g:FerretMap`</strong> to 1 in your <strong>`.vimrc`</strong>.
131
132
133 ### 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>
134
135 Additionally, Ferret will set up special mappings in <strong>`quickfix`</strong> listings, unless prevented from doing so by <strong>`g:FerretQFMap`</strong>:
136
137 - `d` (<strong>`visual-mode`</strong>): delete visual selection
138 - `dd` (<strong>`Normal-mode`</strong>): delete current line
139 - `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
140
141
142 ### `<Plug>(FerretAck)`<a name="ferret-plugferretack" href="#user-content-ferret-plugferretack"></a>
143
144 Ferret maps <leader>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>:
145
146 ```
147 " Instead of <leader>a, use <leader>x.
148 nmap <leader>x <Plug>(FerretAck)
149 ```
150
151
152 ### `<Plug>(FerretLack)`<a name="ferret-plugferretlack" href="#user-content-ferret-plugferretlack"></a>
153
154 Ferret maps <leader>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>:
155
156 ```
157 " Instead of <leader>l, use <leader>y.
158 nmap <leader>y <Plug>(FerretLack)
159 ```
160
161
162 ### `<Plug>(FerretAckWord)`<a name="ferret-plugferretackword" href="#user-content-ferret-plugferretackword"></a>
163
164 Ferret maps <leader>s (mnemonix: "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>:
165
166 ```
167 " Instead of <leader>s, use <leader>z.
168 nmap <leader>z <Plug>(FerretAckWord)
169 ```
170
171
172 ### `<Plug>(FerretAcks)`<a name="ferret-plugferretacks" href="#user-content-ferret-plugferretacks"></a>
173
174 Ferret maps <leader>r (mnemonic: "replace") 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>:
175
176 ```
177 " Instead of <leader>r, use <leader>u.
178 nmap <leader>u <Plug>(FerretAcks)
179 ```
180
181
182 ## Options<a name="ferret-options" href="#user-content-ferret-options"></a>
183
184 <p align="right"><a name="gferretdispatch" href="#user-content-gferretdispatch"><code>g:FerretDispatch</code></a></p>
185
186 ### `g:FerretDispatch` (boolean, default: 1)<a name="ferret-gferretdispatch-boolean-default-1" href="#user-content-ferret-gferretdispatch-boolean-default-1"></a>
187
188 Controls whether to use vim-dispatch (and specifically, <strong>`:Make`</strong>) to run <strong>[`:Ack`](#user-content-ack)</strong> searches asynchronously, when available. To prevent vim-dispatch from being used, set to 0:
189
190 ```
191 let g:FerretDispatch=0
192 ```
193
194 <p align="right"><a name="gferrethlsearch" href="#user-content-gferrethlsearch"><code>g:FerretHlsearch</code></a></p>
195
196 ### `g:FerretHlsearch` (boolean, default: none)<a name="ferret-gferrethlsearch-boolean-default-none" href="#user-content-ferret-gferrethlsearch-boolean-default-none"></a>
197
198 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`</strong> to 1 (on) or 0 (off):
199
200 ```
201 let g:FerretHlsearch=0
202 ```
203
204 <p align="right"><a name="gferretqfoptions" href="#user-content-gferretqfoptions"><code>g:FerretQFOptions</code></a></p>
205
206 ### `g:FerretQFOptions` (boolean, default: 1)<a name="ferret-gferretqfoptions-boolean-default-1" href="#user-content-ferret-gferretqfoptions-boolean-default-1"></a>
207
208 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.
209
210 A full list of overridden settings can be found in <strong>[`ferret-overrides`](#user-content-ferret-overrides)</strong>.
211
212 To prevent the custom settings from being applied, set <strong>`g:FerretQFOptions`</strong> to 0:
213
214 ```
215 let g:FerretQFOptions=0
216 ```
217
218 <p align="right"><a name="gferretqfmap" href="#user-content-gferretqfmap"><code>g:FerretQFMap</code></a></p>
219
220 ### `g:FerretQFMap` (boolean, default: 1)<a name="ferret-gferretqfmap-boolean-default-1" href="#user-content-ferret-gferretqfmap-boolean-default-1"></a>
221
222 Controls whether to set up mappings in the <strong>`quickfix`</strong> results window for deleting results. The mappings include:
223
224 - `d` (<strong>`visual-mode`</strong>): delete visual selection
225 - `dd` (<strong>`Normal-mode`</strong>): delete current line
226 - `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
227
228 To prevent these mappings from being set up, set to 0:
229
230 ```
231 let g:FerretQFMap=0
232 ```
233
234 <p align="right"><a name="gferretloaded" href="#user-content-gferretloaded"><code>g:FerretLoaded</code></a></p>
235
236 ### `g:FerretLoaded` (any, default: none)<a name="ferret-gferretloaded-any-default-none" href="#user-content-ferret-gferretloaded-any-default-none"></a>
237
238 To prevent Ferret from being loaded, set <strong>`g:FerretLoaded`</strong> to any value in your <strong>`.vimrc`</strong>. For example:
239
240 ```
241 let g:FerretLoaded=1
242 ```
243
244 <p align="right"><a name="gferretmap" href="#user-content-gferretmap"><code>g:FerretMap</code></a></p>
245
246 ### `g:FerretMap` (boolean, default: 1)<a name="ferret-gferretmap-boolean-default-1" href="#user-content-ferret-gferretmap-boolean-default-1"></a>
247
248 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:
249
250 ```
251 let g:FerretMap=0
252 ```
253
254 <p align="right"><a name="gferretqfcommands" href="#user-content-gferretqfcommands"><code>g:FerretQFCommands</code></a></p>
255
256 ### `g:FerretQFCommands` (boolean, default: 1)<a name="ferret-gferretqfcommands-boolean-default-1" href="#user-content-ferret-gferretqfcommands-boolean-default-1"></a>
257
258 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:
259
260 ```
261 let g:FerretQFCommands=0
262 ```
263
264
265 ## Custom autocommands<a name="ferret-custom-autocommands" href="#user-content-ferret-custom-autocommands"></a>
266
267 <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>
268 For maximum compatibility with other plug-ins, Ferret runs the following "User" autocommands before and after running the file writing operations during <strong>[`:Acks`](#user-content-acks)</strong>:
269
270 - FerretWillWrite
271 - FerretDidWrite
272
273 For example, to call a pair of custom functions in response to these events, you might do:
274
275 ```
276 autocmd! User FerretWillWrite
277 autocmd User FerretWillWrite call CustomWillWrite()
278 autocmd! User FerretDidWrite
279 autocmd User FerretDidWrite call CustomDidWrite()
280 ```
281
282
283 ## Overrides<a name="ferret-overrides" href="#user-content-ferret-overrides"></a>
284
285 Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a suitable 'grepformat'.
286
287 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.
288
289 <p align="right"><a name="ferret-nolist" href="#user-content-ferret-nolist"><code>ferret-nolist</code></a></p>
290 'nolist'
291
292 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.
293
294 <p align="right"><a name="ferret-norelativenumber" href="#user-content-ferret-norelativenumber"><code>ferret-norelativenumber</code></a></p>
295 'norelativenumber'
296
297 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).
298
299 <p align="right"><a name="ferret-nowrap" href="#user-content-ferret-nowrap"><code>ferret-nowrap</code></a></p>
300 'nowrap'
301
302 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.
303
304 <p align="right"><a name="ferret-number" href="#user-content-ferret-number"><code>ferret-number</code></a></p>
305 'number'
306
307 Turned on to give a sense of absolute progress through the results.
308
309 <p align="right"><a name="ferret-scrolloff" href="#user-content-ferret-scrolloff"><code>ferret-scrolloff</code></a></p>
310 'scrolloff'
311
312 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.
313
314 <p align="right"><a name="ferret-nocursorline" href="#user-content-ferret-nocursorline"><code>ferret-nocursorline</code></a></p>
315 'nocursorline'
316
317 Turned off to reduce visual clutter.
318
319 To prevent any of these <strong>`quickfix`</strong>-specific overrides from being set up, you can set <strong>`g:FerretQFOptions`</strong> to 0 in your <strong>`.vimrc`</strong>:
320
321 ```
322 let g:FerretQFOptions=0
323 ```
324
325
326 ## Troubleshooting<a name="ferret-troubleshooting" href="#user-content-ferret-troubleshooting"></a>
327
328 <p align="right"><a name="ferret-quotes" href="#user-content-ferret-quotes"><code>ferret-quotes</code></a></p>
329
330 ### 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>
331
332 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.
333
334 So, to find "foo bar", you would search like:
335
336 ```
337 :Ack foo\ bar
338 ```
339
340 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:
341
342 ```
343 :Ack -w foo bar
344 ```
345
346 Note that including quotes will not do what you intend.
347
348 ```
349  " Search for '"foo' in the 'bar"' directory:
350  :Ack "foo bar"
351
352  " Search for "'foo' in the "bar'" directory:
353  :Ack 'foo bar'
354 ```
355
356 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:
357
358 ```
359 :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
360 ```
361
362
363 ## FAQ<a name="ferret-faq" href="#user-content-ferret-faq"></a>
364
365
366 ### 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>
367
368 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://wt.pe/h).
369
370 So, even though Ferret has a new name now and actually prefers `ag` over `ack` when available, I prefer to keep the command names intact and benefit from years of accumulated muscle-memory.
371
372
373 ## Related<a name="ferret-related" href="#user-content-ferret-related"></a>
374
375 Just as Ferret aims to improve the multi-file search and replace experience, Loupe does the same for within-file searching:
376
377 https://github.com/wincent/loupe
378
379
380 ## Website<a name="ferret-website" href="#user-content-ferret-website"></a>
381
382 The official Ferret source code repo is at:
383
384 http://git.wincent.com/ferret.git
385
386 A mirror exists at:
387
388 https://github.com/wincent/ferret
389
390 Official releases are listed at:
391
392 http://www.vim.org/scripts/script.php?script_id=5220
393
394
395 ## License<a name="ferret-license" href="#user-content-ferret-license"></a>
396
397 Copyright 2015-present Greg Hurrell. All rights reserved.
398
399 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
400
401 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
402
403 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.
404
405 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.
406
407
408 ## Development<a name="ferret-development" href="#user-content-ferret-development"></a>
409
410
411 ### Contributing patches<a name="ferret-contributing-patches" href="#user-content-ferret-contributing-patches"></a>
412
413 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/ferret/pulls
414
415
416 ### Cutting a new release<a name="ferret-cutting-a-new-release" href="#user-content-ferret-cutting-a-new-release"></a>
417
418 At the moment the release process is manual:
419
420 - Perform final sanity checks and manual testing
421 - Update the <strong>[`ferret-history`](#user-content-ferret-history)</strong> section of the documentation
422 - Verify clean work tree:
423
424 ```
425 git status
426 ```
427
428 - Tag the release:
429
430 ```
431 git tag -s -m "$VERSION release" $VERSION
432 ```
433
434 - Publish the code:
435
436 ```
437 git push origin master --follow-tags
438 git push github master --follow-tags
439 ```
440
441 - Produce the release archive:
442
443 ```
444 git archive -o ferret-$VERSION.zip HEAD -- .
445 ```
446
447 - Upload to http://www.vim.org/scripts/script.php?script_id=5220
448
449
450 ## Authors<a name="ferret-authors" href="#user-content-ferret-authors"></a>
451
452 Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
453
454 The idea for vim-dispatch integration was taken from Miles Sterrett's ack.vim plug-in (https://github.com/mileszs/ack.vim).
455
456 Other contributors that have submitted patches include (in alphabetical order):
457
458 - Daniel Silva
459 - Joe Lencioni
460 - Nelo-Thara Wallus
461 - Vaibhav Sagar
462
463
464 ## History<a name="ferret-history" href="#user-content-ferret-history"></a>
465
466
467 ### 1.2a (16 May 2016)<a name="ferret-12a-16-may-2016" href="#user-content-ferret-12a-16-may-2016"></a>
468
469 - 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`</strong>, <strong>`:FerretCancelAsync`</strong> and <strong>`:FerretPullAsync`</strong>.
470
471
472 ### 1.1.1 (7 March 2016)<a name="ferret-111-7-march-2016" href="#user-content-ferret-111-7-march-2016"></a>
473
474 - Fix another edge case when searching for patterns containing "#", only manifesting under dispatch.vim.
475
476
477 ### 1.1 (7 March 2016)<a name="ferret-11-7-march-2016" href="#user-content-ferret-11-7-march-2016"></a>
478
479 - Fix edge case when searching for strings of the form "<foo>".
480 - Fix edge case when searching for patterns containing "#" and "%".
481 - Provide completion for `ag` and `ack` options when using <strong>[`:Ack`](#user-content-ack)</strong> and <strong>[`:Lack`](#user-content-lack)</strong>.
482 - Fix display of error messages under dispatch.vim.
483
484
485 ### 1.0 (28 December 2015)<a name="ferret-10-28-december-2015" href="#user-content-ferret-10-28-december-2015"></a>
486
487 - Fix broken <strong>[`:Qargs`](#user-content-qargs)</strong> command (patch from Daniel Silva).
488 - Add <strong>`g:FerretQFHandler`</strong> and <strong>`g:FerretLLHandler`</strong> options (patch from Daniel Silva).
489 - Make <strong>`<Plug>`</strong> mappings accessible even <strong>`g:FerretMap`</strong> is set to 0.
490 - Fix failure to report filename when using `ack` and explicitly scoping search to a single file (patch from Daniel Silva).
491 - When using `ag`, report multiple matches per line instead of just the first (patch from Daniel Silva).
492 - Improve content and display of error messages.
493
494
495 ### 0.3 (24 July 2015)<a name="ferret-03-24-july-2015" href="#user-content-ferret-03-24-july-2015"></a>
496
497 - Added highlighting of search pattern and related <strong>`g:FerretHlsearch`</strong> option (patch from Nelo-Thara Wallus).
498 - Add better error reporting for failed or incorrect searches.
499
500
501 ### 0.2 (16 July 2015)<a name="ferret-02-16-july-2015" href="#user-content-ferret-02-16-july-2015"></a>
502
503 - Added <strong>[`FerretDidWrite`](#user-content-ferretdidwrite)</strong> and <strong>[`FerretWillWrite`](#user-content-ferretwillwrite)</strong> autocommands (patch from Joe Lencioni).
504 - Add <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong> mapping (patch from Nelo-Thara Wallus).
505
506
507 ### 0.1 (8 July 2015)<a name="ferret-01-8-july-2015" href="#user-content-ferret-01-8-july-2015"></a>
508
509 - Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).