ctrlsf.vim
An ack/ag powered code search and view tool, in an intuitive way with fairly more context.
Installation
-
An easy way to install CtrlSF is using a package manager, like pathogen, vundle or neobundle.
In vundle:
Bundle 'dyng/ctrlsf.vim'
-
Read Basic Usage for more.
Basic Usage
-
Run
:CtrlSF [pattern]
, it will split a new window to show search result. -
Press
Enter
if you wanna jump to that file, or pressq
to quit. -
Press
p
to explore file in a preview window if you only want a glance. -
Running
:CtrlSFOpen
can reopen CtrlSF window if you are interested in other matches. It is free because it won't invoke a same but new search. -
You can pass arguments like
-i
,-C
or path directly to ack/ag backend in:CtrlSF
command.CtrlSF -i -C 1 [pattern] /restrict/to/some/dir
Key Maps
In CtrlSF window:
o
,Enter
- Jump to file that contains the line under cursor.t
- Likeo
but open file in a new tab.p
- Likeo
but open file in a preview window.O
- Likeo
but always leave CtrlSF window opening.T
- Lkiet
but focus CtrlSF window instead of opened new tab.q
- Quit CtrlSF window.<C-J>
- Move cursor to next match.<C-K>
- Move cursor to previous match.
In preview window:
q
- Close preview window.
Use Your Own Map
Besides the commands, there are also some useful maps.
-
<Plug>CtrlSFPrompt
Input
:CtrlSF
in command line for you, just a handy alias. -
<Plug>CtrlSFVwordPath
Input
:CtrlSF foo
in command line wherefoo
is the current visual selected word, waiting for further input. -
<Plug>CtrlSFVwordExec
Similar to above, but execute it for you.
-
<Plug>CtrlSFCwordPath
Input
:CtrlSF foo
in command line wherefoo
is the word under cursor. -
<Plug>CtrlSFPwordPath
Input
:CtrlSF foo
in command line wherefoo
is the last search pattern of vim.
For a detail list of all maps, please refer to the document file.
I strongly recommend you should do some maps for a nicer user experience, because 8 keystrokes for every single search are really boring even pain experience. Another reason is that one of the most useful feature 'Search Current Visual Selection' can be accessed by map only.
Example:
nmap <C-F>f <Plug>CtrlSFPrompt
vmap <C-F>f <Plug>CtrlSFVwordPath
vmap <C-F>F <Plug>CtrlSFVwordExec
nmap <C-F>n <Plug>CtrlSFCwordPath
nmap <C-F>p <Plug>CtrlSFPwordPath
nnoremap <C-F>o :CtrlSFOpen<CR>
Configuration
-
g:ctrlsf_ackprg
defines the external ack-like program which CtrlSF uses as source. If nothing is specified, CtrlSF will try ag first and fallback to ack if ag is not available. You can also explicitly define it bylet g:ctrlsf_ackprg = 'ag'
-
g:ctrlsf_position
defines where CtrlSf places its window. Possible values areleft
,right
,top
andbottom
. If nothing specified, the default value isleft
.let g:ctrlsf_position = 'bottom'
-
g:ctrlsf_winsize
defines the width (if CtrlSF opens vertically) or height (if CtrlSF opens horizontally) of CtrlSF main window. You can specify it with percent value or absolute value.let g:ctrlsf_winsize = '30%' " or let g:ctrlsf_winsize = '100'
-
g:ctrlsf_auto_close
defines the behavior of CtrlSF window after you press theEnter
. By default CtrlSF window will automatically be closed if you jump to some file, you can prevent it by settingg:ctrlsf_auto_close
to 0.let g:ctrlsf_auto_close = 0
-
g:ctrlsf_context
defines how to print lines around the matching line (refer toack
's manual). It is default to be-C 3
, you can overwrite it bylet g:ctrlsf_context = '-B 5 -A 3'
A full doc about options can be found in :help ctrlsf-options
.
Why not ack.vim or ag.vim ?
- ack.vim depends on vim's builtin
:grep
command, so you can't custom output format. What makes me to write this plugin is that I find reading lines with no highlight and no context is totally a pain. (Using:cnext
and:cprevious
can relieve it, yes.) - Fix a misescape bug in ack.vim (and also ag.vim), it lets you can use literal '#' and '%' without annoying escape now. For more information, check manual of ack.vim.
- ag.vim is actually a fork of ack.vim with minor change.