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