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