]> git.wincent.com - docvim.git/blob - tests/fixtures/integration/ferret/golden/plaintext.golden
Add Vim help integration tests
[docvim.git] / tests / fixtures / integration / ferret / golden / plaintext.golden
1 *ferret.txt*    Ferret plug-in for Vim      *ferret*
2
3 CONTENTS                                                       *ferret-contents*
4
5 1. Intro                  |ferret-intro|
6 2. Installation           |ferret-installation|
7 3. Options                |ferret-options|
8 4. Commands               |ferret-commands|
9 5. Mappings               |ferret-mappings|
10 6. Custom autocommands    |ferret-custom-autocommands|
11 7. Overrides              |ferret-overrides|
12 8. Troubleshooting        |ferret-troubleshooting|
13 9. FAQ                    |ferret-faq|
14 10. Related               |ferret-related|
15 11. Website               |ferret-website|
16 12. License               |ferret-license|
17 13. Development           |ferret-development|
18 14. Authors               |ferret-authors|
19 15. History               |ferret-history|
20
21 INTRO                                                             *ferret-intro*
22
23     "ferret (verb)
24     (ferret something out) search tenaciously for and find something: she
25     had the ability to ferret out the facts."
26
27
28                                                                *ferret-features*
29 Ferret improves Vim's multi-file search in four ways:
30
31 1. Powerful multi-file search ~
32
33 Ferret provides an |:Ack| command for searching across multiple files using
34 The Silver Searcher (https://github.com/ggreer/the_silver_searcher), Ack
35 (http://beyondgrep.com/), or Grep (http://www.gnu.org/software/grep/).
36 Support for passing options through to the underlying search command exists,
37 along with the ability to use full regular expression syntax without doing
38 special escaping.
39
40 Shortcut mappings are provided to start an |:Ack| search (<leader>a) or to
41 search for the word currently under the cursor (<leader>s).
42
43 Results are normally displayed in the |quickfix| window, but Ferret also
44 provides a |:Lack| command that behaves like |:Ack| but uses the |location-list|
45 instead, and a <leader>l mapping as a shortcut to |:Lack|.
46
47 Finally, Ferret offers integration with dispatch.vim
48 (https://github.com/tpope/vim-dispatch), which enables asynchronous
49 searching despite the fact that Vim itself is single-threaded.
50
51 2. Streamlined multi-file replace ~
52
53 The companion to |:Ack| is |:Acks| (mnemonic: "Ack substitute", accessible via
54 shortcut <leader>r), which allows you to run a multi-file replace across all
55 the files placed in the |quickfix| window by a previous invocation of |:Ack|.
56
57 3. Quickfix listing enhancements ~
58
59 The |quickfix| listing itself is enhanced with settings to improve its
60 usability, and natural mappings that allow quick removal of items from the
61 list (for example, you can reduce clutter in the listing by removing lines
62 that you don't intend to make changes to).
63
64 Additionally, Vim's |:cn|, |:cp|, |:cnf| and |:cpf| commands are tweaked to make it
65 easier to immediately identify matches by centering them within the viewport.
66
67 4. Easy operations on files in the quickfix listing ~
68
69 Finally, Ferret provides a |:Qargs| command that puts the files currently in
70 the |quickfix| listing into the |:args| list, where they can be operated on in
71 bulk via the |:argdo| command. This is what's used under the covers by |:Acks|
72 to do its work.
73
74 INSTALLATION                                               *ferret-installation*
75
76 To install Ferret, use your plug-in management system of choice.
77
78 If you don't have a "plug-in management system of choice", I recommend
79 Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
80 robustness. Assuming that you have Pathogen installed and configured, and
81 that you want to install Ferret into `~/.vim/bundle`, you can do so with:
82 >
83     git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
84 <
85 Alternatively, if you use a Git submodule for each Vim plug-in, you could do
86 the following after `cd`-ing into the top-level of your Git superproject:
87 >
88     git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
89     git submodule init
90 <
91 To generate help tags under Pathogen, you can do so from inside Vim with:
92 >
93     :call pathogen#helptags()
94 <
95 OPTIONS                                                         *ferret-options*
96
97 COMMANDS                                                       *ferret-commands*
98
99 :Ack {pattern} {options}                                                  *:Ack*
100
101 Searches for {pattern} in all the files under the current directory (see
102 |:pwd|), unless otherwise overridden via {options}, and displays the results
103 in the |quickfix| listing.
104
105 `ag` (The Silver Searcher) will be used preferentially if present on the
106 system, because it is faster, falling back to `ack` and then `grep` as needed.
107
108 If dispatch.vim is installed the search process will run asynchronously via
109 the |:Make| command, otherwise it will be run synchronously via |:cexpr|.
110 Asynchronous searches are preferred because they do not block, despite the
111 fact that Vim itself is single threaded. The |g:FerretDispatch| option can be
112 used to prevent the use of dispatch.vim.
113
114 The {pattern} is passed through as-is to the underlying search program, and
115 no escaping is required other than preceding spaces by a single backslash.
116 For example, to search for "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style
117 regular expression syntax), you could do:
118 >
119     :Ack \bfoo[0-9]{2}\ bar\b
120 <
121 Likewise, {options} are passed through. In this example, we pass the `-w`
122 option (to search on word boundaries), and scope the search to the "foo" and
123 "bar" subdirectories: >
124 >
125     :Ack -w something foo bar
126 <
127 As a convenience <leader>a is set-up (|<Plug>(FerretAck)|) as a shortcut to
128 enter |Cmdline-mode| with `:Ack` inserted on the |Cmdline|. Likewise <leader>s
129 (|<Plug>(FerretAckWord)|) is a shortcut for running |:Ack| with the word
130 currently under the cursor.
131
132 :Lack {pattern} {options}                                                *:Lack*
133
134 Just like |:Ack|, but instead of using the |quickfix| listing, which is global
135 across an entire Vim instance, it uses the |location-list|, which is a
136 per-window construct.
137
138 Note that |:Lack| always runs synchronously via |:cexpr|, because dispatch.vim
139 doesn't currently support the |location-list|.
140
141 :Acks /{pattern}/{replacement}/                                          *:Acks*
142
143 Takes all of the files currently in the |quickfix| listing and performs a
144 substitution of all instances of {pattern} (a standard Vim search |pattern|)
145 by {replacement}.
146
147 A typical sequence consists of an |:Ack| invocation to populate the |quickfix|
148 listing and then |:Acks| (mnemonic: "Ack substitute") to perform replacements.
149 For example, to replace "foo" with "bar" across all files in the current
150 directory:
151 >
152     :Ack foo
153     :Acks /foo/bar/
154 <
155 :Qargs                                                                  *:Qargs*
156
157 This is a utility function that is used by the |:Acks| command but is also
158 generally useful enough to warrant being exposed publicly.
159
160 It takes the files currently in the |quickfix| listing and sets them as |:args|
161 so that they can be operated on en masse via the |:argdo| command.
162
163 MAPPINGS                                                       *ferret-mappings*
164
165 Circumstances where mappings do not get set up ~
166
167 Note that Ferret will not try to set up the <leader> mappings if any of the
168 following are true:
169
170 - A mapping for already exists.
171 - An alternative mapping for the same functionality has already been set up
172   from a |.vimrc|.
173 - The mapping has been suppressed by setting |g:FerretMap| to 1 in your |.vimrc|.
174
175 Mappings specific to the quickfix window ~
176
177 Additionally, Ferret will set up special mappings in |quickfix| listings,
178 unless prevented from doing so by |g:FerretQFMap|:
179
180 - `d` (|visual-mode|): delete visual selection
181 - `dd` (|Normal-mode|): delete current line
182 - `d`{motion} (|Normal-mode|): delete range indicated by {motion}
183
184
185                                                              *<Plug>(FerretAck)*
186 Ferret maps <leader>a to |<Plug>(FerretAck)|, which triggers the |:Ack| command.
187 To use an alternative mapping instead, create a different one in your |.vimrc|
188 instead using |:nmap|:
189 >
190     " Instead of <leader>a, use <leader>x.
191     nmap <leader>x <Plug>(FerretAck)
192 <
193
194                                                             *<Plug>(FerretLack)*
195 Ferret maps <leader>l to |<Plug>(FerretLack)|, which triggers the |:Lack|
196 command. To use an alternative mapping instead, create a different one in
197 your |.vimrc| instead using |:nmap|:
198 >
199     " Instead of <leader>l, use <leader>y.
200     nmap <leader>y <Plug>(FerretLack)
201 <
202
203                                                          *<Plug>(FerretAckWord)*
204 Ferret maps <leader>s (mnemonix: "selection) to |<Plug>(FerretAckWord)|, which
205 uses |:Ack| to search for the word currently under the cursor. To use an
206 alternative mapping instead, create a different one in your |.vimrc| instead
207 using |:nmap|:
208 >
209     " Instead of <leader>s, use <leader>z.
210     nmap <leader>z <Plug>(FerretAckWord)
211 <
212
213                                                             *<Plug>(FerretAcks)*
214 Ferret maps <leader>r (mnemonic: "replace") to |<Plug>(FerretAcks)|, which
215 triggers the |:Acks| command and fills the prompt with the last search term
216 from Ferret. to use an alternative mapping instead, create a different one
217 in your |.vimrc| instead using |:nmap|:
218 >
219     " Instead of <leader>r, use <leader>u.
220     nmap <leader>u <Plug>(FerretAcks)
221 <
222
223                                                               *g:FerretDispatch*
224 |g:FerretDispatch|                                          boolean (default: 1)
225
226 Controls whether to use vim-dispatch (and specifically, |:Make|) to run |:Ack|
227 searches asynchronously, when available. To prevent vim-dispatch from being
228 used, set to 0:
229 >
230     let g:FerretDispatch=0
231 <
232
233                                                               *g:FerretHlsearch*
234 |g:FerretHlsearch|                                       boolean (default: none)
235
236 Controls whether Ferret should attempt to highlight the search pattern when
237 running |:Ack| or |:Lack|. If left unset, Ferret will respect the current
238 'hlsearch' setting. To force highlighting on or off irrespective of
239 'hlsearch', set |g:FerretHlsearch| to 1 (on) or 0 (off):
240 >
241     let g:FerretHlsearch=0
242 <
243
244                                                              *g:FerretQFOptions*
245 |g:FerretQFOptions|                                         boolean (default: 1)
246
247 Controls whether to set up setting overrides for |quickfix| windows. These are
248 various settings, such as |norelativenumber|, |nolist| and |nowrap|, that are
249 intended to make the |quickfix| window, which is typically very small relative
250 to other windows, more usable.
251
252 A full list of overridden settings can be found in |ferret-overrides|.
253
254 To prevent the custom settings from being applied, set |g:FerretQFOptions| to
255 0:
256 >
257     let g:FerretQFOptions=0
258 <
259
260                                                                  *g:FerretQFMap*
261 |g:FerretQFMap|                                             boolean (default: 1)
262
263 Controls whether to set up mappings in the |quickfix| results window for
264 deleting results. The mappings include:
265
266 - `d` (|visual-mode|): delete visual selection
267 - `dd` (|Normal-mode|): delete current line
268 - `d`{motion} (|Normal-mode|): delete range indicated by {motion}
269
270 To prevent these mappings from being set up, set to 0:
271 >
272     let g:FerretQFMap=0
273 <
274
275                                                                 *g:FerretLoaded*
276 |g:FerretLoaded|                                             any (default: none)
277
278 To prevent Ferret from being loaded, set |g:FerretLoaded| to any value in your
279 |.vimrc|. For example:
280 >
281     let g:FerretLoaded=1
282 <
283
284                                                                    *g:FerretMap*
285 |g:FerretMap|                                               boolean (default: 1)
286
287 Controls whether to set up the Ferret mappings, such as |<Plug>(FerretAck)|
288 (see |ferret-mappings| for a full list). To prevent any mapping from being
289 configured, set to 0:
290 >
291     let g:FerretMap=0
292 <
293
294                                                             *g:FerretQFCommands*
295 |g:FerretQFCommands|                                        boolean (default: 1)
296
297 Controls whether to set up custom versions of the |quickfix| commands, |:cn|,
298 |:cnf|, |:cp| an |:cpf|. These overrides vertically center the match within the
299 viewport on each jump. To prevent the custom versions from being configured,
300 set to 0:
301 >
302     let g:FerretQFCommands=0
303 <
304 CUSTOM AUTOCOMMANDS                                 *ferret-custom-autocommands*
305
306
307                                                 *FerretDidWrite* *FerretWillWrite*
308 For maximum compatibility with other plug-ins, Ferret runs the following
309 "User" autocommands before and after running the file writing operations
310 during |:Acks|:
311
312 - FerretWillWrite
313 - FerretDidWrite
314
315 For example, to call a pair of custom functions in response to these events,
316 you might do:
317 >
318     autocmd! User FerretWillWrite
319     autocmd User FerretWillWrite call CustomWillWrite()
320     autocmd! User FerretDidWrite
321     autocmd User FerretDidWrite call CustomDidWrite()
322 <
323 OVERRIDES                                                     *ferret-overrides*
324
325 Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially
326 setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a
327 suitable 'grepformat'.
328
329 Additionally, Ferret includes an |ftplugin| for the |quickfix| listing that
330 adjusts a number of settings to improve the usability of search results.
331
332
333                                                                  *ferret-nolist*
334 'nolist'
335
336 Turned off to reduce visual clutter in the search results, and because
337 'list' is most useful in files that are being actively edited, which is not
338 the case for |quickfix| results.
339
340
341                                                        *ferret-norelativenumber*
342 'norelativenumber'
343
344 Turned off, because it is more useful to have a sense of absolute progress
345 through the results list than to have the ability to jump to nearby results
346 (especially seeing as the most common operations are moving to the next or
347 previous file, which are both handled nicely by |:cnf| and |:cpf| respectively).
348
349
350                                                                  *ferret-nowrap*
351 'nowrap'
352
353 Turned off to avoid ugly wrapping that makes the results list hard to read,
354 and because in search results, the most relevant information is the
355 filename, which is on the left and is usually visible even without wrapping.
356
357
358                                                                  *ferret-number*
359 'number'
360
361 Turned on to give a sense of absolute progress through the results.
362
363
364                                                               *ferret-scrolloff*
365 'scrolloff'
366
367 Set to 0 because the |quickfix| listing is usually small by default, so trying
368 to keep the current line away from the edge of the viewpoint is futile; by
369 definition it is usually near the edge.
370
371
372                                                            *ferret-nocursorline*
373 'nocursorline'
374
375 Turned off to reduce visual clutter.
376
377 To prevent any of these |quickfix|-specific overrides from being set up, you
378 can set |g:FerretQFOptions| to 0 in your |.vimrc|:
379 >
380     let g:FerretQFOptions=0
381 <
382 TROUBLESHOOTING                                         *ferret-troubleshooting*
383
384
385                                                                  *ferret-quotes*
386 Ferret fails to find patterns containing spaces ~
387
388 As described in the documentation for |:Ack|, the search pattern is passed
389 through as-is to the underlying search command, and no escaping is required
390 other than preceding spaces by a single backslash.
391
392 So, to find "foo bar", you would search like:
393 >
394     :Ack foo\ bar
395 <
396 Unescaped spaces in the search are treated as argument separators, so a
397 command like the following means pass the `-w` option through, search for
398 pattern "foo", and limit search to the "bar" directory:
399 >
400     :Ack -w foo bar
401 <
402 Note that including quotes will not do what you intend.
403 >
404      " Search for '"foo' in the 'bar"' directory:
405      :Ack "foo bar"
406
407      " Search for "'foo' in the "bar'" directory:
408      :Ack 'foo bar'
409 <
410 This approach to escaping is taken in order to make it straightfoward to use
411 powerful Perl-compatible regular expression syntax in an unambiguous way
412 without having to worry about shell escaping rules:
413 >
414     :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
415 <
416 FAQ                                                                 *ferret-faq*
417
418 Why do Ferret commands start with "Ack", "Lack" and so on? ~
419
420 Ferret was originally the thinnest of wrappers (7 lines of code in my
421 |.vimrc|) around `ack`. The earliest traces of it can be seen in the initial
422 commit to my dotfiles repo in May, 2009 (https://wt.pe/h).
423
424 So, even though Ferret has a new name now and actually prefers `ag` over `ack`
425 when available, I prefer to keep the command names intact and benefit from
426 years of accumulated muscle-memory.
427
428 RELATED                                                         *ferret-related*
429
430 Just as Ferret aims to improve the multi-file search and replace experience,
431 Loupe does the same for within-file searching:
432
433 https://github.com/wincent/loupe
434
435 WEBSITE                                                         *ferret-website*
436
437 The official Ferret source code repo is at:
438
439 http://git.wincent.com/ferret.git
440
441 A mirror exists at:
442
443 https://github.com/wincent/ferret
444
445 Official releases are listed at:
446
447 http://www.vim.org/scripts/script.php?script_id=5220
448
449 LICENSE                                                         *ferret-license*
450
451 Copyright 2015-present Greg Hurrell. All rights reserved.
452
453 Redistribution and use in source and binary forms, with or without
454 modification, are permitted provided that the following conditions are met:
455
456 1. Redistributions of source code must retain the above copyright notice,
457 this list of conditions and the following disclaimer.
458
459 2. Redistributions in binary form must reproduce the above copyright notice,
460 this list of conditions and the following disclaimer in the documentation
461 and/or other materials provided with the distribution.
462
463 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
464 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
465 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
466 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
467 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
468 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
469 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
470 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
471 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
472 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
473 POSSIBILITY OF SUCH DAMAGE.
474
475 DEVELOPMENT                                                 *ferret-development*
476
477 Contributing patches ~
478
479 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
480 at: https://github.com/wincent/ferret/pulls
481
482 Cutting a new release ~
483
484 At the moment the release process is manual:
485
486 - Perform final sanity checks and manual testing
487 - Update the |ferret-history| section of the documentation
488 - Verify clean work tree:
489 >
490     git status
491 <
492 - Tag the release:
493 >
494     git tag -s -m "$VERSION release" $VERSION
495 <
496 - Publish the code:
497 >
498     git push origin master --follow-tags
499     git push github master --follow-tags
500 <
501 - Produce the release archive:
502 >
503     git archive -o ferret-$VERSION.zip HEAD -- .
504 <
505 - Upload to http://www.vim.org/scripts/script.php?script_id=5220
506
507 AUTHORS                                                         *ferret-authors*
508
509 Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
510
511 The idea for vim-dispatch integration was taken from Miles Sterrett's
512 ack.vim plug-in (https://github.com/mileszs/ack.vim).
513
514 Other contributors that have submitted patches include (in alphabetical
515 order):
516
517 - Daniel Silva
518 - Joe Lencioni
519 - Nelo-Thara Wallus
520 - Vaibhav Sagar
521
522 HISTORY                                                         *ferret-history*
523
524 1.2a (16 May 2016) ~
525
526 - Add optional support for running searches asynchronously using Vim's |+job|
527   feature (enabled by default in sufficiently recent versions of Vim); see
528   |g:FerretJob|, |:FerretCancelAsync| and |:FerretPullAsync|.
529
530 1.1.1 (7 March 2016) ~
531
532 - Fix another edge case when searching for patterns containing "#", only
533   manifesting under dispatch.vim.
534
535 1.1 (7 March 2016) ~
536
537 - Fix edge case when searching for strings of the form "<foo>".
538 - Fix edge case when searching for patterns containing "#" and "%".
539 - Provide completion for `ag` and `ack` options when using |:Ack| and |:Lack|.
540 - Fix display of error messages under dispatch.vim.
541
542 1.0 (28 December 2015) ~
543
544 - Fix broken |:Qargs| command (patch from Daniel Silva).
545 - Add |g:FerretQFHandler| and |g:FerretLLHandler| options (patch from Daniel
546   Silva).
547 - Make |<Plug>| mappings accessible even |g:FerretMap| is set to 0.
548 - Fix failure to report filename when using `ack` and explicitly scoping
549   search to a single file (patch from Daniel Silva).
550 - When using `ag`, report multiple matches per line instead of just the first
551   (patch from Daniel Silva).
552 - Improve content and display of error messages.
553
554 0.3 (24 July 2015) ~
555
556 - Added highlighting of search pattern and related |g:FerretHlsearch| option
557   (patch from Nelo-Thara Wallus).
558 - Add better error reporting for failed or incorrect searches.
559
560 0.2 (16 July 2015) ~
561
562 - Added |FerretDidWrite| and |FerretWillWrite| autocommands (patch from Joe
563   Lencioni).
564 - Add |<Plug>(FerretAcks)| mapping (patch from Nelo-Thara Wallus).
565
566 0.1 (8 July 2015) ~
567
568 - Initial release, extracted from my dotfiles
569   (https://github.com/wincent/wincent).