5.6 KiB
ack.vim
Run your favorite search tool from Vim, with an enhanced results list.
This plugin was designed as a Vim frontend for the programmer's search tool
ack. ack can be used as a replacement for 99% of the uses of grep. The
plugin allows you to search with ack from within Vim and shows the results in a
split window.
But here's a little secret for the Vim-seasoned: it's just a light wrapper for Vim's grepprg and the quickfix window for match results. This makes it easy to integrate with your own Vim configuration and use existing knowledge of core features. It also means the plugin is flexible to use with other search tools.
Installation
ack
You will need ack (>= 2.0), of course. To install it follow the manual.
The Plugin
It is recommended to use one of the popular plugin managers for Vim. There are many and you probably already have a preferred one, but a few examples for your copy-and-paste convenience:
Pathogen
$ git clone https://github.com/mileszs/ack.vim.git ~/.vim/bundle/ack.vim
Vundle
Plugin 'mileszs/ack.vim'
NeoBundle
NeoBundle 'mileszs/ack.vim'
Manual (not recommended)
Download the plugin and extract it in ~/.vim/ (or
%PROGRAMFILES%/Vim/vimfiles on Windows).
Usage
:Ack [options] {pattern} [{directories}]
Search recursively in {directories} (which defaults to the current directory)
for the {pattern}.
Files containing the search term will be listed in the quickfix window, along
with the line number of the occurrence, once for each occurrence. <Enter> on
a line in this window will open the file and place the cursor on the matching
line.
Just like where you use :grep, :grepadd, :lgrep, and :lgrepadd, you can
use :Ack, :AckAdd, :LAck, and :LAckAdd respectively. (See :help Ack
after installing, or doc/ack.txt in the repo, for more information.)
For more ack help see ack documentation.
Keyboard Shortcuts
The quickfix results window is augmented with these convenience mappings:
? a quick summary of these keys, repeat to close
o to open (same as Enter)
O to open and close the quickfix window
go to preview file, open but maintain focus on ack.vim results
t to open in new tab
T to open in new tab without moving to it
h to open in horizontal split
H to open in horizontal split, keeping focus on the results
v to open in vertical split
gv to open in vertical split, keeping focus on the results
q to close the quickfix window
Gotchas
To search for a pattern that contains whitespace, you need to enclose the
pattern in single quotes. For example: :Ack 'foo bar' to search for
'foo bar'.
Some characters have special meaning, and need to be escaped in your search
pattern. For instance, #. You need to escape it with :Ack '\\\#define foo' to search for '#define foo'. See issue #5.
Possibly FAQ
Can I use ag (The Silver Searcher) with this?
Absolutely, and probably other tools if their output is similar or you can
write a pattern match for it--just set g:ackprg. If you like, you can fall
back to Ack in case you use your vimrc on a system without Ag available:
if executable('ag')
let g:ackprg = 'ag --vimgrep'
endif
Since Ack is quite portable you might check a copy of it into your dotfiles
repository in ~/bin so you'll nearly always have it available.
What's the difference from ag.vim?
Well... not a lot really.
Present maintainer, yours truly, kind of wishes they never forked,
contributes to both, and wouldn't mind seeing them merged again. ag.vim got a
nice code clean-up (which ack.vim is now hopefully getting), and ack.vim picked
up a few features that haven't made their way to ag.vim, like :AckWindow,
optional background search execution with vim-dispatch, and auto-previewing.
I don't want to jump to the first result automatically.
Use :Ack!, with bang. If you want this behavior most of the time, you might
like an abbreviation or mapping in your personal config, something like these:
cnoreabbrev Ack Ack!
nnoremap <Leader>a :Ack!<Space>
Most of the :[L]Ack* commands support this. Note that this behavior follows
the convention of Vim's built-in :grep and :make commands.
Changelog
Please see the GitHub releases page.
Credits
This plugin is derived from Antoine Imbert's blog post ack and Vim Integration (in particular, the function in the update to the post). Miles Sterrett packaged it up as a plugin and documented it in Vim's help format, and since then many contributors have submitted enhancements and fixes.
And of course, where would we be without ack. And, you know, Vim.