ervandew / ag

vim plugin to search using the silver searcher (ag)

Overview

ag.vim is a plugin for vim which allows you to search over files using the silver searcher (ag).

Usage

:Ag [options] [pattern] [directory]

Note: When no arguments are supplied, the the word under the cursor is searched, honoring the case of that word.

The :Ag command provides several features to make running ag easier:

• :Ag supports command completion of:

  • patterns from your vim search history: You can hit <tab> when starting to run :Ag and you can choose from a list of 10 of your most recent vim searches. A common use case while editing code could be running /something to search for occurrences in the current file, then running :Ag <tab> to search for the pattern across all files.
  • ag options: If you type - and then hit <tab>, you can scroll through all the ag.vim supported ag options.
  • file/directory name to search in: Once you've supplied a search pattern, the next argument to :Ag is an optional directory or file to search in and you can make use of <tab> completion to choose that file or directory.

  Note: I highly recommend turning on vim's wildmenu support to get the most out of vim's command completion:

  set wildmenu
  set wildmode=longest:full,full
  

• Some vim based regex atoms in the supplied pattern will be converted to their PCRE equivalent so that you can do something like hit * on a word in vim, then run :Ag <tab> or :Ag <c-r>/ to search for that word with ag without having to convert the pattern yourself:

  • Word boundaries: \<Word\> will be converted to \bWord\b
  • Non-greedy matches: foo.\{-}bar will be converted to foo.*?bar

• The directory argument supplied to :Ag supports simple glob patterns. To simplify filtering of your search by file extension, you can pass a glob pattern to :Ag and it will convert it to a file search regex for ag. For example, to limit your search to only python files starting in some directory, you could run:

  :Ag FooBar foo/*.py
  

  Which will search all .py files directly in the 'foo' directory.

  To search .py files in all the nested sub-directories of 'foo' as well as those .py files directly under 'foo' you can use:

  :Ag FooBar foo/***.py
  

  If you want to search all the sub-directories but skip .py files directly under 'foo' you can use:

  :Ag FooBar foo/**/*.py
  

• If you use :Ag -g with no other arguments, then it will attempt to extract a file name from under the cursor and search for that and either:

  • Open the file in the current window if there is only 1 result.

    Note: If you supply a bang (:Ag! -g), then the result will be opened in a new split window.

  • Open the quickfix window if there are multiple results.

  You can replace the built in vim mappings to go to a file by adding the following to your .vimrc:

  nmap gf :Ag -g<cr>
  nmap gF :Ag! -g<cr>
  

The :AgPrompt command provides a prompt from which you can perform a fuzzy search on file names.

:AgPrompt

From the prompt you can start typing portions of a file name you are looking for and results will be populated in another window.

The following keybindings are available from the prompt:

• <esc> - close the ag prompt + results
• <tab>, <down> - select the next file
• <s-tab>, <up> - select the previous file
• <cr> - open selected file w/ default action
• <c-e> - open with :edit
• <c-s> - open in a split window
• <c-t> - open in a new tab
• <c-h> - toggle help buffer

Note: To use <c-s> in vim running in a terminal, you may need to add the following to your vimrc to prevent the terminal from suspending display updates:

silent !stty -ixon

Configuration

• :Ag
  • g:AgSmartCase (default: 0) - When set to a non-0 value, :Ag will run ag with the --smart-case option.
• :AgPrompt
  • g:AgPromptDefaultAction (default: 'edit') - The default command used to open the selected file.
  • g:AgPromptCaseInsensitive (default: 'lower') - Sets under what condition will the search be case insensitive, one of:
    • lower: when the pattern is all lower case
    • never: never case insensitive
    • always: aways case insensitive

Extras

ag#search#FindFile(path, cmd) - A globally available function that other scripts can use to find a file and open it with the supplied command. This can be useful for custom mappings that need to first translate a file name from a finally artifact to the source file (Eg. a .css file to the .scss source).