ack.txt

*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: