]> git.wincent.com - docvim.git/blob - tests/fixtures/markdown/integration-ferret-plugin.golden
704cbf7bc35dfd9405909f7f7f8cb4897018bde3
[docvim.git] / tests / fixtures / markdown / integration-ferret-plugin.golden
1 # ferret
2
3 ## Intro
4
5 > "ferret (verb)<br />(ferret something out) search tenaciously for and find something: she had the ability to ferret out the facts."
6
7 <p align="right"><a name="ferret-features" href="#user-content-ferret-features"><code>ferret-features</code></a></p>
8 Ferret improves Vim's multi-file search in four ways:
9
10 ### 1. Powerful multi-file search
11
12 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.
13
14 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).
15
16 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>.
17
18 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.
19
20 ### 2. Streamlined multi-file replace
21
22 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>.
23
24 ### 3. Quickfix listing enhancements
25
26 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).
27
28 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.
29
30 ### 4. Easy operations on files in the quickfix listing
31
32 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.
33
34 ## Installation
35
36 To install Ferret, use your plug-in management system of choice.
37
38 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:
39
40 ```
41 git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
42 ```
43
44 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:
45
46 ```
47 git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
48 git submodule init
49 ```
50
51 To generate help tags under Pathogen, you can do so from inside Vim with:
52
53 ```
54 :call pathogen#helptags()
55 ```
56
57 ## Commands
58
59 <p align="right"><a name="ack" href="#user-content-ack"><code>:Ack</code></a></p>
60 ### `:Ack {pattern} {options}`
61
62 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.
63
64 `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.
65
66 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.
67
68 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:
69
70 ```
71 :Ack \bfoo[0-9]{2}\ bar\b
72 ```
73
74 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: >
75
76 ```
77 :Ack -w something foo bar
78 ```
79
80 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.
81
82 <p align="right"><a name="lack" href="#user-content-lack"><code>:Lack</code></a></p>
83 ### `:Lack {pattern} {options}`
84
85 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.
86
87 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>.
88
89 <p align="right"><a name="acks" href="#user-content-acks"><code>:Acks</code></a></p>
90 ### `:Acks /{pattern}/{replacement}/`
91
92 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}.
93
94 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:
95
96 ```
97 :Ack foo
98 :Acks /foo/bar/
99 ```
100
101 <p align="right"><a name="qargs" href="#user-content-qargs"><code>:Qargs</code></a></p>
102 ### `:Qargs`
103
104 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.
105
106 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.
107
108 ## Mappings
109
110 ### Circumstances where mappings do not get set up
111
112 Note that Ferret will not try to set up the <leader> mappings if any of the following are true:
113
114 - A mapping for already exists.
115 - An alternative mapping for the same functionality has already been set up from a <strong>`.vimrc`</strong>.
116 - The mapping has been suppressed by setting <strong>`g:FerretMap`</strong> to 1 in your <strong>`.vimrc`</strong>.
117
118 ### Mappings specific to the quickfix window
119
120 Additionally, Ferret will set up special mappings in <strong>`quickfix`</strong> listings, unless prevented from doing so by <strong>`g:FerretQFMap`</strong>:
121
122 - `d` (<strong>`visual-mode`</strong>): delete visual selection
123 - `dd` (<strong>`Normal-mode`</strong>): delete current line
124 - `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
125
126 ### `<Plug>(FerretAck)`
127
128 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>:
129
130 ```
131 " Instead of <leader>a, use <leader>x.
132 nmap <leader>x <Plug>(FerretAck)
133 ```
134
135 ### `<Plug>(FerretLack)`
136
137 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>:
138
139 ```
140 " Instead of <leader>l, use <leader>y.
141 nmap <leader>y <Plug>(FerretLack)
142 ```
143
144 ### `<Plug>(FerretAckWord)`
145
146 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>:
147
148 ```
149 " Instead of <leader>s, use <leader>z.
150 nmap <leader>z <Plug>(FerretAckWord)
151 ```
152
153 ### `<Plug>(FerretAcks)`
154
155 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>:
156
157 ```
158 " Instead of <leader>r, use <leader>u.
159 nmap <leader>u <Plug>(FerretAcks)
160 ```
161
162 ## Options
163
164 <p align="right"><a name="gferretloaded" href="#user-content-gferretloaded"><code>g:FerretLoaded</code></a></p>
165 ### `g:FerretLoaded` (any, default: none)
166
167 To prevent Ferret from being loaded, set <strong>`g:FerretLoaded`</strong> to any value in your <strong>`.vimrc`</strong>. For example:
168
169 ```
170 let g:FerretLoaded=1
171 ```
172
173 <p align="right"><a name="gferretmap" href="#user-content-gferretmap"><code>g:FerretMap</code></a></p>
174 ### `g:FerretMap` (boolean, default: 1)
175
176 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:
177
178 ```
179 let g:FerretMap=0
180 ```
181
182 <p align="right"><a name="gferretqfcommands" href="#user-content-gferretqfcommands"><code>g:FerretQFCommands</code></a></p>
183 ### `g:FerretQFCommands` (boolean, default: 1)
184
185 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:
186
187 ```
188 let g:FerretQFCommands=0
189 ```
190
191 ## Custom autocommands
192
193 <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>
194 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>:
195
196 - FerretWillWrite
197 - FerretDidWrite
198
199 For example, to call a pair of custom functions in response to these events, you might do:
200
201 ```
202 autocmd! User FerretWillWrite
203 autocmd User FerretWillWrite call CustomWillWrite()
204 autocmd! User FerretDidWrite
205 autocmd User FerretDidWrite call CustomDidWrite()
206 ```
207
208 ## Overrides
209
210 Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a suitable 'grepformat'.
211
212 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.
213
214 <p align="right"><a name="ferret-nolist" href="#user-content-ferret-nolist"><code>ferret-nolist</code></a></p>
215 'nolist'
216
217 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.
218
219 <p align="right"><a name="ferret-norelativenumber" href="#user-content-ferret-norelativenumber"><code>ferret-norelativenumber</code></a></p>
220 'norelativenumber'
221
222 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).
223
224 <p align="right"><a name="ferret-nowrap" href="#user-content-ferret-nowrap"><code>ferret-nowrap</code></a></p>
225 'nowrap'
226
227 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.
228
229 <p align="right"><a name="ferret-number" href="#user-content-ferret-number"><code>ferret-number</code></a></p>
230 'number'
231
232 Turned on to give a sense of absolute progress through the results.
233
234 <p align="right"><a name="ferret-scrolloff" href="#user-content-ferret-scrolloff"><code>ferret-scrolloff</code></a></p>
235 'scrolloff'
236
237 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.
238
239 <p align="right"><a name="ferret-nocursorline" href="#user-content-ferret-nocursorline"><code>ferret-nocursorline</code></a></p>
240 'nocursorline'
241
242 Turned off to reduce visual clutter.
243
244 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>:
245
246 ```
247 let g:FerretQFOptions=0
248 ```
249
250 ## Troubleshooting
251
252 <p align="right"><a name="ferret-quotes" href="#user-content-ferret-quotes"><code>ferret-quotes</code></a></p>
253 ### Ferret fails to find patterns containing spaces
254
255 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.
256
257 So, to find "foo bar", you would search like:
258
259 ```
260 :Ack foo\ bar
261 ```
262
263 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:
264
265 ```
266 :Ack -w foo bar
267 ```
268
269 Note that including quotes will not do what you intend.
270
271 ```
272  " Search for '"foo' in the 'bar"' directory:
273  :Ack "foo bar"
274
275  " Search for "'foo' in the "bar'" directory:
276  :Ack 'foo bar'
277 ```
278
279 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:
280
281 ```
282 :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
283 ```
284
285 ## FAQ
286
287 ### Why do Ferret commands start with "Ack", "Lack" and so on?
288
289 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).
290
291 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.
292
293 ## Related
294
295 Just as Ferret aims to improve the multi-file search and replace experience, Loupe does the same for within-file searching:
296
297 https://github.com/wincent/loupe
298
299 ## Website
300
301 The official Ferret source code repo is at:
302
303 http://git.wincent.com/ferret.git
304
305 A mirror exists at:
306
307 https://github.com/wincent/ferret
308
309 Official releases are listed at:
310
311 http://www.vim.org/scripts/script.php?script_id=5220
312
313 ## License
314
315 Copyright 2015-present Greg Hurrell. All rights reserved.
316
317 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
318
319 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.
320
321 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.
322
323 ## Development
324
325 ### Contributing patches
326
327 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/ferret/pulls
328
329 ### Cutting a new release
330
331 At the moment the release process is manual:
332
333 - Perform final sanity checks and manual testing
334 - Update the <strong>[`ferret-history`](#user-content-ferret-history)</strong> section of the documentation
335 - Verify clean work tree:
336
337 ```
338 git status
339 ```
340
341 - Tag the release:
342
343 ```
344 git tag -s -m "$VERSION release" $VERSION
345 ```
346
347 - Publish the code:
348
349 ```
350 git push origin master --follow-tags
351 git push github master --follow-tags
352 ```
353
354 - Produce the release archive:
355
356 ```
357 git archive -o ferret-$VERSION.zip HEAD -- .
358 ```
359
360 - Upload to http://www.vim.org/scripts/script.php?script_id=5220
361
362 ## Authors
363
364 Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
365
366 The idea for vim-dispatch integration was taken from Miles Sterrett's ack.vim plug-in (https://github.com/mileszs/ack.vim).
367
368 Other contributors that have submitted patches include (in alphabetical order):
369
370 - Daniel Silva
371 - Joe Lencioni
372 - Nelo-Thara Wallus
373 - Vaibhav Sagar
374
375 ## History
376
377 0.3.1 (not yet released)
378
379 - Fix broken <strong>[`:Qargs`](#user-content-qargs)</strong> command (patch from Daniel Silva).
380
381 0.3 (24 July 2015)
382
383 - Added highlighting of search pattern and related <strong>`g:FerretHlsearch`</strong> option (patch from Nelo-Thara Wallus).
384 - Add better error reporting for failed or incorrect searches.
385
386 0.2 (16 July 2015)
387
388 - Added <strong>[`FerretDidWrite`](#user-content-ferretdidwrite)</strong> and <strong>[`FerretWillWrite`](#user-content-ferretwillwrite)</strong> autocommands (patch from Joe Lencioni).
389 - Add <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong> mapping (patch from Nelo-Thara Wallus).
390
391 0.1 (8 July 2015)
392
393 - Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).