]> git.wincent.com - docvim.git/blob - tests/fixtures/vim/integration-ferret-plugin.golden
Add parser tests to integration tests
[docvim.git] / tests / fixtures / vim / integration-ferret-plugin.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. Commands               |ferret-commands|
8 4. Mappings               |ferret-mappings|
9 5. Options                |ferret-options|
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 COMMANDS                                                       *ferret-commands*
96
97 :Ack {pattern} {options}                                                  *:Ack*
98
99 Searches for {pattern} in all the files under the current directory (see
100 |:pwd|), unless otherwise overridden via {options}, and displays the results
101 in the |quickfix| listing.
102
103 `ag` (The Silver Searcher) will be used preferentially if present on the
104 system, because it is faster, falling back to `ack` and then `grep` as needed.
105
106 If dispatch.vim is installed the search process will run asynchronously via
107 the |:Make| command, otherwise it will be run synchronously via |:cexpr|.
108 Asynchronous searches are preferred because they do not block, despite the
109 fact that Vim itself is single threaded. The |g:FerretDispatch| option can be
110 used to prevent the use of dispatch.vim.
111
112 The {pattern} is passed through as-is to the underlying search program, and
113 no escaping is required other than preceding spaces by a single backslash.
114 For example, to search for "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style
115 regular expression syntax), you could do:
116 >
117     :Ack \bfoo[0-9]{2}\ bar\b
118 <
119 Likewise, {options} are passed through. In this example, we pass the `-w`
120 option (to search on word boundaries), and scope the search to the "foo" and
121 "bar" subdirectories: >
122 >
123     :Ack -w something foo bar
124 <
125 As a convenience <leader>a is set-up (|<Plug>(FerretAck)|) as a shortcut to
126 enter |Cmdline-mode| with `:Ack` inserted on the |Cmdline|. Likewise <leader>s
127 (|<Plug>(FerretAckWord)|) is a shortcut for running |:Ack| with the word
128 currently under the cursor.
129
130 :Lack {pattern} {options}                                                *:Lack*
131
132 Just like |:Ack|, but instead of using the |quickfix| listing, which is global
133 across an entire Vim instance, it uses the |location-list|, which is a
134 per-window construct.
135
136 Note that |:Lack| always runs synchronously via |:cexpr|, because dispatch.vim
137 doesn't currently support the |location-list|.
138
139 :Acks /{pattern}/{replacement}/                                          *:Acks*
140
141 Takes all of the files currently in the |quickfix| listing and performs a
142 substitution of all instances of {pattern} (a standard Vim search |pattern|)
143 by {replacement}.
144
145 A typical sequence consists of an |:Ack| invocation to populate the |quickfix|
146 listing and then |:Acks| (mnemonic: "Ack substitute") to perform replacements.
147 For example, to replace "foo" with "bar" across all files in the current
148 directory:
149 >
150     :Ack foo
151     :Acks /foo/bar/
152 <
153 :Qargs                                                                  *:Qargs*
154
155 This is a utility function that is used by the |:Acks| command but is also
156 generally useful enough to warrant being exposed publicly.
157
158 It takes the files currently in the |quickfix| listing and sets them as |:args|
159 so that they can be operated on en masse via the |:argdo| command.
160
161 MAPPINGS                                                       *ferret-mappings*
162
163 Circumstances where mappings do not get set up ~
164
165 Note that Ferret will not try to set up the <leader> mappings if any of the
166 following are true:
167
168 - A mapping for already exists.
169 - An alternative mapping for the same functionality has already been set up
170   from a |.vimrc|.
171 - The mapping has been suppressed by setting |g:FerretMap| to 1 in your |.vimrc|.
172
173 Mappings specific to the quickfix window ~
174
175 Additionally, Ferret will set up special mappings in |quickfix| listings,
176 unless prevented from doing so by |g:FerretQFMap|:
177
178 - `d` (|visual-mode|): delete visual selection
179 - `dd` (|Normal-mode|): delete current line
180 - `d`{motion} (|Normal-mode|): delete range indicated by {motion}
181
182
183                                                              *<Plug>(FerretAck)*
184 Ferret maps <leader>a to |<Plug>(FerretAck)|, which triggers the |:Ack| command.
185 To use an alternative mapping instead, create a different one in your |.vimrc|
186 instead using |:nmap|:
187 >
188     " Instead of <leader>a, use <leader>x.
189     nmap <leader>x <Plug>(FerretAck)
190 <
191
192                                                             *<Plug>(FerretLack)*
193 Ferret maps <leader>l to |<Plug>(FerretLack)|, which triggers the |:Lack|
194 command. To use an alternative mapping instead, create a different one in
195 your |.vimrc| instead using |:nmap|:
196 >
197     " Instead of <leader>l, use <leader>y.
198     nmap <leader>y <Plug>(FerretLack)
199 <
200
201                                                          *<Plug>(FerretAckWord)*
202 Ferret maps <leader>s (mnemonix: "selection) to |<Plug>(FerretAckWord)|, which
203 uses |:Ack| to search for the word currently under the cursor. To use an
204 alternative mapping instead, create a different one in your |.vimrc| instead
205 using |:nmap|:
206 >
207     " Instead of <leader>s, use <leader>z.
208     nmap <leader>z <Plug>(FerretAckWord)
209 <
210
211                                                             *<Plug>(FerretAcks)*
212 Ferret maps <leader>r (mnemonic: "replace") to |<Plug>(FerretAcks)|, which
213 triggers the |:Acks| command and fills the prompt with the last search term
214 from Ferret. to use an alternative mapping instead, create a different one
215 in your |.vimrc| instead using |:nmap|:
216 >
217     " Instead of <leader>r, use <leader>u.
218     nmap <leader>u <Plug>(FerretAcks)
219 <
220 OPTIONS                                                         *ferret-options*
221
222
223                                                                 *g:FerretLoaded*
224 |g:FerretLoaded|                                             any (default: none)
225
226 To prevent Ferret from being loaded, set |g:FerretLoaded| to any value in your
227 |.vimrc|. For example:
228 >
229     let g:FerretLoaded=1
230 <
231
232                                                                    *g:FerretMap*
233 |g:FerretMap|                                               boolean (default: 1)
234
235 Controls whether to set up the Ferret mappings, such as |<Plug>(FerretAck)|
236 (see |ferret-mappings| for a full list). To prevent any mapping from being
237 configured, set to 0:
238 >
239     let g:FerretMap=0
240 <
241
242                                                             *g:FerretQFCommands*
243 |g:FerretQFCommands|                                        boolean (default: 1)
244
245 Controls whether to set up custom versions of the |quickfix| commands, |:cn|,
246 |:cnf|, |:cp| an |:cpf|. These overrides vertically center the match within the
247 viewport on each jump. To prevent the custom versions from being configured,
248 set to 0:
249 >
250     let g:FerretQFCommands=0
251 <
252 CUSTOM AUTOCOMMANDS                                 *ferret-custom-autocommands*
253
254
255                                                 *FerretDidWrite* *FerretWillWrite*
256 For maximum compatibility with other plug-ins, Ferret runs the following
257 "User" autocommands before and after running the file writing operations
258 during |:Acks|:
259
260 - FerretWillWrite
261 - FerretDidWrite
262
263 For example, to call a pair of custom functions in response to these events,
264 you might do:
265 >
266     autocmd! User FerretWillWrite
267     autocmd User FerretWillWrite call CustomWillWrite()
268     autocmd! User FerretDidWrite
269     autocmd User FerretDidWrite call CustomDidWrite()
270 <
271 OVERRIDES                                                     *ferret-overrides*
272
273 Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially
274 setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a
275 suitable 'grepformat'.
276
277 Additionally, Ferret includes an |ftplugin| for the |quickfix| listing that
278 adjusts a number of settings to improve the usability of search results.
279
280
281                                                                  *ferret-nolist*
282 'nolist'
283
284 Turned off to reduce visual clutter in the search results, and because
285 'list' is most useful in files that are being actively edited, which is not
286 the case for |quickfix| results.
287
288
289                                                        *ferret-norelativenumber*
290 'norelativenumber'
291
292 Turned off, because it is more useful to have a sense of absolute progress
293 through the results list than to have the ability to jump to nearby results
294 (especially seeing as the most common operations are moving to the next or
295 previous file, which are both handled nicely by |:cnf| and |:cpf| respectively).
296
297
298                                                                  *ferret-nowrap*
299 'nowrap'
300
301 Turned off to avoid ugly wrapping that makes the results list hard to read,
302 and because in search results, the most relevant information is the
303 filename, which is on the left and is usually visible even without wrapping.
304
305
306                                                                  *ferret-number*
307 'number'
308
309 Turned on to give a sense of absolute progress through the results.
310
311
312                                                               *ferret-scrolloff*
313 'scrolloff'
314
315 Set to 0 because the |quickfix| listing is usually small by default, so trying
316 to keep the current line away from the edge of the viewpoint is futile; by
317 definition it is usually near the edge.
318
319
320                                                            *ferret-nocursorline*
321 'nocursorline'
322
323 Turned off to reduce visual clutter.
324
325 To prevent any of these |quickfix|-specific overrides from being set up, you
326 can set |g:FerretQFOptions| to 0 in your |.vimrc|:
327 >
328     let g:FerretQFOptions=0
329 <
330 TROUBLESHOOTING                                         *ferret-troubleshooting*
331
332
333                                                                  *ferret-quotes*
334 Ferret fails to find patterns containing spaces ~
335
336 As described in the documentation for |:Ack|, the search pattern is passed
337 through as-is to the underlying search command, and no escaping is required
338 other than preceding spaces by a single backslash.
339
340 So, to find "foo bar", you would search like:
341 >
342     :Ack foo\ bar
343 <
344 Unescaped spaces in the search are treated as argument separators, so a
345 command like the following means pass the `-w` option through, search for
346 pattern "foo", and limit search to the "bar" directory:
347 >
348     :Ack -w foo bar
349 <
350 Note that including quotes will not do what you intend.
351 >
352      " Search for '"foo' in the 'bar"' directory:
353      :Ack "foo bar"
354
355      " Search for "'foo' in the "bar'" directory:
356      :Ack 'foo bar'
357 <
358 This approach to escaping is taken in order to make it straightfoward to use
359 powerful Perl-compatible regular expression syntax in an unambiguous way
360 without having to worry about shell escaping rules:
361 >
362     :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
363 <
364 FAQ                                                                 *ferret-faq*
365
366 Why do Ferret commands start with "Ack", "Lack" and so on? ~
367
368 Ferret was originally the thinnest of wrappers (7 lines of code in my
369 |.vimrc|) around `ack`. The earliest traces of it can be seen in the initial
370 commit to my dotfiles repo in May, 2009 (https://wt.pe/h).
371
372 So, even though Ferret has a new name now and actually prefers `ag` over `ack`
373 when available, I prefer to keep the command names intact and benefit from
374 years of accumulated muscle-memory.
375
376 RELATED                                                         *ferret-related*
377
378 Just as Ferret aims to improve the multi-file search and replace experience,
379 Loupe does the same for within-file searching:
380
381 https://github.com/wincent/loupe
382
383 WEBSITE                                                         *ferret-website*
384
385 The official Ferret source code repo is at:
386
387 http://git.wincent.com/ferret.git
388
389 A mirror exists at:
390
391 https://github.com/wincent/ferret
392
393 Official releases are listed at:
394
395 http://www.vim.org/scripts/script.php?script_id=5220
396
397 LICENSE                                                         *ferret-license*
398
399 Copyright 2015-present Greg Hurrell. All rights reserved.
400
401 Redistribution and use in source and binary forms, with or without
402 modification, are permitted provided that the following conditions are met:
403
404 1. Redistributions of source code must retain the above copyright notice,
405 this list of conditions and the following disclaimer. 2. Redistributions in
406 binary form must reproduce the above copyright notice, this list of
407 conditions and the following disclaimer in the documentation and/or other
408 materials provided with the distribution.
409
410 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
411 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
412 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
413 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
414 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
415 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
416 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
417 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
418 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
419 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
420 POSSIBILITY OF SUCH DAMAGE.
421
422 DEVELOPMENT                                                 *ferret-development*
423
424 Contributing patches ~
425
426 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
427 at: https://github.com/wincent/ferret/pulls
428
429 Cutting a new release ~
430
431 At the moment the release process is manual:
432
433 - Perform final sanity checks and manual testing
434 - Update the |ferret-history| section of the documentation
435 - Verify clean work tree:
436 >
437     git status
438 <
439 - Tag the release:
440 >
441     git tag -s -m "$VERSION release" $VERSION
442 <
443 - Publish the code:
444 >
445     git push origin master --follow-tags
446     git push github master --follow-tags
447 <
448 - Produce the release archive:
449 >
450     git archive -o ferret-$VERSION.zip HEAD -- .
451 <
452 - Upload to http://www.vim.org/scripts/script.php?script_id=5220
453
454 AUTHORS                                                         *ferret-authors*
455
456 Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
457
458 The idea for vim-dispatch integration was taken from Miles Sterrett's
459 ack.vim plug-in (https://github.com/mileszs/ack.vim).
460
461 Other contributors that have submitted patches include (in alphabetical
462 order):
463
464 - Daniel Silva
465 - Joe Lencioni
466 - Nelo-Thara Wallus
467 - Vaibhav Sagar
468
469 HISTORY                                                         *ferret-history*
470
471 0.3.1 (not yet released)
472
473 - Fix broken |:Qargs| command (patch from Daniel Silva).
474
475 0.3 (24 July 2015)
476
477 - Added highlighting of search pattern and related |g:FerretHlsearch| option
478   (patch from Nelo-Thara Wallus).
479 - Add better error reporting for failed or incorrect searches.
480
481 0.2 (16 July 2015)
482
483 - Added |FerretDidWrite| and |FerretWillWrite| autocommands (patch from Joe
484   Lencioni).
485 - Add |<Plug>(FerretAcks)| mapping (patch from Nelo-Thara Wallus).
486
487 0.1 (8 July 2015)
488
489 - Initial release, extracted from my dotfiles
490   (https://github.com/wincent/wincent).