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