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