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

==============================================================================
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
    occurence 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 enable mappings on quickview window.

                                                       *g:ack_apply_lmappings*
g:ack_apply_lmappings
Default: 1

This option enable mappings on Location list window.

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

==============================================================================
MAPPINGS                                                        *ack-mappings*

The following keyboard shortcuts are available in the quickfix window:

o                   open file (same as enter).

O                   open file and close quickfix window.

go                  preview file (open but maintain focus on ack.vim results).

t                   open in a new tab.

T                   open in new tab silently.

h                   open in horizontal split.

H                  open in horizontal split silently.

v                   open in vertical split.

gv                  open in vertical split silently.

q                   close the quickfix window.
