315 lines
11 KiB
Text
315 lines
11 KiB
Text
*ack.txt* Plugin that integrates ack with Vim
|
|
|
|
==============================================================================
|
|
Author: Antoine Imbert <antoine.imbert+ackvim@gmail.com> *ack-author*
|
|
License: Same terms as Vim itself (see |license|)
|
|
|
|
This plugin is only available if 'compatible' is not set.
|
|
|
|
{Vi does not have any of this}
|
|
|
|
==============================================================================
|
|
INTRODUCTION *ack*
|
|
|
|
This plugin is a front for the Perl module App::Ack. Ack can be used as a
|
|
replacement for grep. This plugin will allow you to run ack from vim, and
|
|
shows the results in a split window.
|
|
|
|
:Ack[!] [options] {pattern} [{directory}] *:Ack*
|
|
|
|
Search recursively in {directory} (which defaults to the current
|
|
directory) for the {pattern}. Behaves just like the |:grep| command, but
|
|
will open the |Quickfix| window for you. If [!] is not given the first
|
|
occurrence is jumped to.
|
|
|
|
:AckAdd [options] {pattern} [{directory}] *:AckAdd*
|
|
|
|
Just like |:Ack|, but instead of making a new list, the matches are
|
|
appended to the current |quickfix| list.
|
|
|
|
:AckFromSearch [{directory}] *:AckFromSearch*
|
|
|
|
Just like |:Ack| but the pattern is from previous search.
|
|
|
|
:LAck [options] {pattern} [{directory}] *:LAck*
|
|
|
|
Just like |:Ack| but instead of the |quickfix| list, matches are placed in
|
|
the current |location-list|.
|
|
|
|
:LAckAdd [options] {pattern} [{directory}] *:LAckAdd*
|
|
|
|
Just like |:AckAdd| but instead of the |quickfix| list, matches are added
|
|
to the current |location-list|
|
|
|
|
:AckFile [options] {pattern} [{directory}] *:AckFile*
|
|
|
|
Search recursively in {directory} (which defaults to the current
|
|
directory) for filenames matching the {pattern}. Behaves just like the
|
|
|:grep| command, but will open the |Quickfix| window for you.
|
|
|
|
:AckHelp[!] [options] {pattern} *:AckHelp*
|
|
|
|
Search vim documentation files for the {pattern}. Behaves just like the
|
|
|:Ack| command, but searches only vim documentation .txt files
|
|
|
|
:LAckHelp [options] {pattern} *:LAckHelp*
|
|
|
|
Just like |:AckHelp| but instead of the |quickfix| list, matches are placed
|
|
in the current |location-list|.
|
|
|
|
:AckWindow[!] [options] {pattern} *:AckWindow*
|
|
|
|
Search all buffers visible in the screen (current tab page only) files for
|
|
the {pattern}.
|
|
|
|
:LAckWindow [options] {pattern} *:LAckWindow*
|
|
|
|
Just like |:AckWindow| but instead of the |quickfix| list, matches are
|
|
placed in the current |location-list|.
|
|
|
|
Files containing the search term will be listed in the split 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.
|
|
|
|
Note that if you are using Dispatch.vim with |g:ack_use_dispatch|, location
|
|
lists are not supported, because Dispatch does not support them at this time.
|
|
`:LAck` versions of commands above will give a warning and proceed to use the
|
|
quickfix list instead.
|
|
|
|
See http://beyondgrep.com/ for more information on searching with ack.
|
|
|
|
|
|
==============================================================================
|
|
CONFIGURATION *ack-configuration*
|
|
|
|
*g:ackprg*
|
|
g:ackprg
|
|
Default for ubuntu: "ack-grep"
|
|
Default for other systems: "ack"
|
|
|
|
Use this option to specify the search command and its default arguments.
|
|
|
|
Example:
|
|
>
|
|
let g:ackprg = "ag --vimgrep"
|
|
<
|
|
*g:ack_default_options*
|
|
g:ack_default_options
|
|
Default: " -s -H --nocolor --nogroup --column"
|
|
|
|
Use this option to specify the default arguments given to `ack`. This is only
|
|
used if |g:ackprg| has not been customized from the default--if you are using
|
|
a custom search program instead of Ack, set your preferred options in
|
|
|g:ackprg|.
|
|
|
|
NOTE: This option may be deprecated in the future. ~
|
|
|
|
Example:
|
|
>
|
|
let g:ack_default_options =
|
|
\ " -s -H --nocolor --nogroup --column --smart-case --follow"
|
|
<
|
|
*g:ack_apply_qmappings*
|
|
g:ack_apply_qmappings
|
|
Default: 1
|
|
|
|
This option enables mappings on the |quickfix| window.
|
|
|
|
*g:ack_apply_lmappings*
|
|
g:ack_apply_lmappings
|
|
Default: 1
|
|
|
|
This option enables mappings on |location-list| windows.
|
|
|
|
*g:ack_mappings*
|
|
g:ack_mappings
|
|
Default: {
|
|
\ "t": "<C-W><CR><C-W>T",
|
|
\ "T": "<C-W><CR><C-W>TgT<C-W>j",
|
|
\ "o": "<CR>",
|
|
\ "O": "<CR><C-W><C-W>:ccl<CR>",
|
|
\ "go": "<CR><C-W>j",
|
|
\ "h": "<C-W><CR><C-W>K",
|
|
\ "H": "<C-W><CR><C-W>K<C-W>b",
|
|
\ "v": "<C-W><CR><C-W>H<C-W>b<C-W>J<C-W>t",
|
|
\ "gv": "<C-W><CR><C-W>H<C-W>b<C-W>J" }
|
|
|
|
This option list all maps create on quickfix/Location list window.
|
|
|
|
Example, if you want to open the result in the middle of the screen:
|
|
>
|
|
let g:ack_mappings = { "o": "<CR>zz" }
|
|
<
|
|
*g:ack_qhandler*
|
|
g:ack_qhandler
|
|
Default: "botright copen"
|
|
|
|
Command to open the quickview window.
|
|
|
|
If you want to open a quickview window with 30 lines you can do:
|
|
>
|
|
let g:ack_qhandler = "botright copen 30"
|
|
<
|
|
*g:ack_lhandler*
|
|
g:ack_lhandler
|
|
Default: "botright lopen"
|
|
|
|
Command to open the Location list window.
|
|
|
|
If you want to open a Location list window with 30 lines you can do:
|
|
>
|
|
let g:ack_lhandler = "botright lopen 30"
|
|
<
|
|
*g:ackhighlight*
|
|
g:ackhighlight
|
|
Default: 0
|
|
|
|
Use this option to highlight the searched term.
|
|
|
|
Example:
|
|
>
|
|
let g:ackhighlight = 1
|
|
<
|
|
*g:ack_autoclose*
|
|
g:ack_autoclose
|
|
Default: 0
|
|
|
|
Use this option to specify whether to close the quickfix window after
|
|
using any of the shortcuts.
|
|
|
|
Example:
|
|
>
|
|
let g:ack_autoclose = 1
|
|
<
|
|
*g:ack_autofold_results*
|
|
g:ack_autofold_results
|
|
Default: 0
|
|
|
|
Use this option to fold the results in quickfix by file name. Only the current
|
|
fold will be open by default and while you press 'j' and 'k' to move between the
|
|
results if you hit other fold the last one will be closed and the current will
|
|
be open.
|
|
|
|
Example:
|
|
>
|
|
let g:ack_autofold_results = 1
|
|
<
|
|
*g:ackpreview*
|
|
g:ackpreview
|
|
Default: 0
|
|
|
|
Use this option to automagically open the file with 'j' or 'k'.
|
|
|
|
Example:
|
|
>
|
|
let g:ackpreview = 1
|
|
<
|
|
*g:ack_use_dispatch*
|
|
g:ack_use_dispatch
|
|
Default: 0
|
|
|
|
Use this option to use vim-dispatch to run searches in the background, with a
|
|
variety of execution backends for different systems.
|
|
|
|
Due to limitations in Dispatch at this time, location lists are unsupported
|
|
and result windows will appear before results are ready. Still, these may be
|
|
acceptable tradeoffs for very large projects where searches are slow.
|
|
|
|
Example:
|
|
>
|
|
let g:ack_use_dispatch = 1
|
|
<
|
|
*g:ack_use_cword_for_empty_search*
|
|
g:ack_use_cword_for_empty_search
|
|
Default: 1
|
|
|
|
Use this option to enable blank searches to run against the word under the
|
|
cursor. When this option is not set, blank searches will only output an error
|
|
message.
|
|
|
|
Example:
|
|
>
|
|
let g:ack_use_cword_for_empty_search = 0
|
|
<
|
|
==============================================================================
|
|
MAPPINGS *ack-mappings*
|
|
|
|
The following keyboard shortcuts are available in the |quickfix| and
|
|
|location-list| windows:
|
|
|
|
? display a quick summary of these mappings.
|
|
|
|
o open file (same as Enter).
|
|
|
|
O open file and close the quickfix window.
|
|
|
|
go preview file (open but maintain focus on ack.vim results).
|
|
|
|
t open in a new tab.
|
|
|
|
T open in new tab without moving to it.
|
|
|
|
h open in horizontal split.
|
|
|
|
H open in horizontal split, keeping focus on the results.
|
|
|
|
v open in vertical split.
|
|
|
|
gv open in vertical split, keeping focus on the results.
|
|
|
|
q close the quickfix window.
|
|
|
|
To adjust these, see |g:ack_mappings|.
|
|
|
|
==============================================================================
|
|
Ignoring files *ack-ignore*
|
|
|
|
If you're using this plugin with ag, The Silver Searcher, bear in mind that:
|
|
|
|
- It ignores file patterns from your .gitignore and .hgignore.
|
|
|
|
- If there are other files in your source repository you don't wish to
|
|
search, you can add their patterns to an .agignore file.
|
|
|
|
==============================================================================
|
|
ISSUES AND FAQ *ack-issues-and-faq*
|
|
|
|
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.
|
|
|
|
I use NERDTree and opening ack.vim results in a vertical split displacing it.~
|
|
|
|
You are probably using NERDTree with its default alignment at the left
|
|
side of the window. Set these custom mappings in your vimrc to work around
|
|
this:
|
|
>
|
|
let g:ack_mappings = {
|
|
\ 'v': '<C-W><CR><C-W>L<C-W>p<C-W>J<C-W>p',
|
|
\ 'gv': '<C-W><CR><C-W>L<C-W>p<C-W>J' }
|
|
<
|
|
This solution will be improved in the future.
|
|
|
|
Results show a mix of relative and absolute paths, making them hard to read.~
|
|
|
|
This is a quirk of Vim that can happen with plain |:vimgrep| too. You can
|
|
try this in your vimrc to work around it:
|
|
>
|
|
autocmd BufAdd * exe "cd" fnameescape(getcwd())
|
|
<
|
|
but for some users this may be disruptive to their Vim workflow. For more
|
|
details, see:
|
|
|
|
http://vi.stackexchange.com/a/4816/7174
|
|
https://github.com/mileszs/ack.vim/issues/143
|
|
|
|
vim:set et sw=4 ts=4 tw=78:
|