/vim-side-search

Search context in Vim in a sidebar using `ag` output

Primary LanguageVim ScriptMIT LicenseMIT

Overview

The quickfix window is great, but it would be nice to get some context around our searches. This plugin adds ag output to a side buffer with quick navigation mappings using comfortable Vim conventions.

Simple Demo

Features

  • step through ag output instead of quickfix output
  • syntax highlighting of ag output
  • mappable to search current word under cursor
  • configurable g:side_search_prg similar to grepprg
  • vertical or horizontal split output via g:side_search_splitter

Buffer Mappings

n/N         - Cursor to next/prev result
<C-n>/<C-p> - Open next/prev in largest window
<CR>        - Open location at cursor in largest window
<C-w><CR>   - Open and jump to window
qf          - :grep! to Quickfix

Prerequisites

We rely on The Silver Searcher to perform our file/text searches for us. Theoretically any program which has the same output could also work, but that we only test using ag output.

To install ag command on OSX:

brew install the_silver_searcher

For refer to The Silver Searcher for more instructions.

Global Configuration

" How should we execute the search?
" --heading and --stats are required!
let g:side_search_prg = 'ag --word-regexp'
  \. " --ignore='*.js.map'"
  \. " --heading --stats -B 1 -A 4"

" Can use `vnew` or `new`
let g:side_search_splitter = 'vnew'

" I like 40% splits, change it if you don't
let g:side_search_split_pct = 0.4

Suggested Mapping

" SideSearch current word and return to original window
nnoremap <Leader>ss :SideSearch <C-r><C-w><CR> | wincmd p

" Create an shorter `SS` command
command! -complete=file -nargs=+ SS execute 'SideSearch <args>'

" or command abbreviation
cabbrev SS SideSearch

FAQ

How to search for multi-word terms?

Escape spaces with a slash:

:SideSearch cats\ and\ dogs