albfan / ag.vim

Vim plugin for the_silver_searcher, 'ag', a replacement for the Perl module / CLI script 'ack'

ag.vim

This plugin is a front for ag, A.K.A. the_silver_searcher. Ag can be used as a replacement for 153% of the uses of ack. This plugin will allow you to run ag from vim, and shows the results in a split window.

Installation

See the_silver_searcher's README for its installation instructions (if you haven't installed it already).

You have to first install ag, itself. On Mac+Homebrew, Gentoo Linux, several others, there's package named the_silver_searcher, but if your OS/distro don't have one, the GitHub repo installs fine:

Vim has various ways of installing plugins, the standard way is in the documentation, but most people use a plugin to manage their plugins. If you don't already have a preferred plugin manager plugin, why not try one of the following?

• vim-plug

• vim-pathogen

• Vundle.vim

• Or, if you don't use any sort of Vim plugin management:

  cd ~/.vim/bundle && git clone https://github.com/rking/ag.vim ag && echo "set runtimepath^=~/.vim/bundle/ag" >> ~/.vimrc

  Then open vim and run :helptags ~/.vim/bundle/ag/doc.

Configuration

You can specify a custom ag name and path in your .vimrc like so:

let g:ag.prg="<custom-ag-path-goes-here> --vimgrep"

You can configure ag.vim to always start searching from your project root instead of the cwd

let g:ag.working_path_mode="r"

Usage

:Ag [options] {pattern} [{directory}]

Search recursively in {directory} (which defaults to the current directory) for the {pattern}.

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.

Just like where you use :grep, :grepadd, :lgrep, and :lgrepadd, you can use :Ag, :AgAdd, :LAg, and :LAgAdd respectively. (See doc/ag.txt, or install and :h Ag for more information.)

Shell mimic

For those who like how ag performs on shell use

:[N]AgGroup {pattern} [{directory}]

see this screencast

Gotchas

Some characters have special meaning, and need to be escaped your search pattern. For instance, '#'. You have to escape it like this :Ag '\\\#define foo' to search for #define foo. (From blueyed in issue #5.)

Sometimes git grep is even faster, though in my experience it's not noticeably so.

Keyboard Shortcuts

In any window you can issue

<Leader>ag to search word under cursor, or visual selection

In the quickfix window, you can use:

e    to open file and close the quickfix window
o    to open (same as enter)
go   to preview file (open but maintain focus on ag.vim results)
t    to open in new tab
T    to open in new tab silently
h    to open in horizontal split
H    to open in horizontal split silently
v    to open in vertical split
gv   to open in vertical split silently
q    to close the quickfix window

Acknowledgements

This Vim plugin is derived (and by derived, I mean copied, almost entirely) from milesz's ack.vim, which I also recommend installing since you might be in a situation where you have ack but not ag, and don't want to stop to install ag. Also, ack supports --type, and a few other features.

ag.vim's Issues

Move ag executable existence check

It can be placed:

1. In root function, called on any Ag* cmd execution.
   • + don't disturb user until he will actually call command, don't affect startup time (autoload).
   • - once installed binaries very rarely can (dis)appear between ag calls, excess checks.
2. In the beginning of autoload/ag.vim
   • + also don't effect startup time
   • - echoed message can be ignored/unnoticed
   • - defined commands will be broken
3. In the plugin/ag.vim
   • + most clear way
   • - affects startup time (but can be lazy loaded by package manager)

Do you have your own proc/cons for some specific usecase?
If not, I will change according to 3.

Compress options definition

Make them more DRY, replace by dict and add initialization in cycle.

search with regexp fulls syntax highlight

Although some progress has been done

85a4122

search for ( which must be escaped in ag which search with regexp by default do not highlight all results

A function to escape unscaped chars is needed

"(\(|:)" --> "\((\|:\)"
"function (foo|bar)\(\)"  --> "function \(foo\|bar\)()"

Use /tmp for temporary files of testsuite

I don't know which goal you carried when chose to clone vader.vim and create temp.XXX in ag.vim/t. If you have reasons, clarify them please.
For me /tmp is placed completely in RAM, is predefined place for such tasks, etc, etc...
As I switch between branches frequently it's much better option to clone there, instead of current directory.
I will provide appropriate changes to suite.sh. Portable for Windows too.

Add posfilter processor

Except for sparse searches, many times a search has an underliying pattern.

e.g. When searching "Foo" relating "function Foo" you may want to include only matches with "function" (search function definition) or exclude them (search function calls)

detect failed search

avoid open an empty buffer when there's no results or error

Operate on normal an visual mode

Typing is cool, no typing is even cooler

<Leader>ag search word under cursor (anywhere)
<Leader>ag serarch visual selection
<Leader>ra (Repeat last ag search or refine after editing)

hide line/col numbers

for a first look line and col numbers only adds noise. Allow to hide without disable navigation

Propose: fixture as list of corner-cases w/o specified syntax

Maybe you fondly attached to *.vim so you used that format for fixtures, but it's overcumbered for testing purposes, introducing unnecessary complexity in Expect (...) block and hampering overall covering.

I propose to change format of each fixture to next:

• Plain list with only corner-cases, each one on separate line -- then each "Expect" becomes clear
• No additional text before/after actual corner-case, beside where it matters -- we already assumed ag itself works correct!
• Text content is derived from actual corner-case -- it will clarify their purpose. Examples:
  • "quotedword"
  • raw multi word
  • escaped\ multi\ word
  • 'squoted multi word'
  • (re[ge]x|)
• Text inside parenthesis of Execute (...) / Do (...) blocks must repeat text content above -- then we will be able to see what was tested in log of non-failed tests -- which is great. No necessity to specify long sentences as you did -- smart splitting all tests in files will do this work better than you could.
• All searches on that fixture must return only one result -- K.I.S.S
• Multiple results in one search -- it's separate corner-case with its own testfile.
• Same for testing right highlighting -- separate dir + testfile only for this purpose.

Now about structural organization for all this (Edit):

• One individual fixture for each *.vader (as you proposed) -- one dir with identical name directly in same dir, like ag.vim/t/<test-name>
• Script suits.sh will copy appropriate fixtures into temporary dir of launched tests as before.
• Move suites.sh and helper.vim into ag.vim/scripts (prefered) or ag.vim (root) to decouple heterogeneous stuff. (That dir can be used for other scripts in future)
• Create makefile with target make tests -- possible only after introducing -es

Complaints, please

slow down on test suite

Using --verbose mode is faster than normal (silent) mode.

All is related with vim warning about ouput is not a terminal

Vim: Warning: Output is not to a terminal

Some folks resolve it using ex mode silent

https://en.wikibooks.org/wiki/Learning_the_vi_Editor/Vim/Modes#Ex-mode

but in my tries, ex-mode exit status is 1 when all is ok and 2 when test fails.

Navigate to exact line

When search with context, add a parameter to enable navigate to exact line selected

Test results delusiveness

In testing suite we use options to enable default vim behaviour and disable any influence from divergent user configs. It's great for reproducibility of tests results, but bad overall -- because we lose integration errors, caused by user environment with many interfering plugins.
Of course I will add one more option to suite.sh to run tests in user env on demand.

But it reveals deeper problem -- all such tests became manual labour of independent individuals instead of automated checking on CI server.

unfold line selected

When destination line is inside a fold it should be open

Open selection on appropriate window

Select last accessed window (avoiding special ones -see NERDTree-) to open selection. Split if there is no avaliable window

file filter `-G` hides smartcase

related issue ggreer/the_silver_searcher#744

Enh: use cabbrev instead of Agg command

You introduced renamed command Agg and deprecated AgGroup to be able type it easier.
It's as always good idea, bad suggestion.
Explicit command name is more clear than obscured one -- see bad practice of NrrwRgn.
If you want to resolve it, vim community already developed another practice: cabbrev.

cabbrev Agg AgGroup
" Or even simpler
cabbrev agg AgGroup
cabbrev aggf AgGroupFile

Then if you type it and press enter all will work as expected.
If you type it and press <Space> -- command will be expanded and clarified.

Define GetArgs/Repeat abilities

Referring to AgGroupLast renaming question there have arised necessity to reconcile default behaviour for all functions, as them will use GetArgs.

• ¿ no arguments -- cword | or repeat-last? == which one really must have separate function?
• selection 'v' one-/multiline -- search as-is -Q (agreed).
• ¿ selection 'V' -- is it has sense to search whole lines?
• ¿ selection 'C-v' one-line -- search as regex (w/o -Q)?
• ¿ selection 'C-v' multi-line -- feature? -- do consequtive searches | search for any of lines?
• using c[wW]ord for searching?
• ... is there any other cases I missed?

Improve travis cfg

If I understand correctly, we can't make PR to add travis support into rking branch with no efforts?
Because it requires manual labour from rking itself.
However we could try to PR template configs and write issue with instructions?

Also, try to migrate your travis config to dockers (container) architecture, which runs much faster, but can't use sudo. Because sudo isn't actually necessary for this plugin testing.

grow/shrink context without loose actual selection

Now there's g:ag.last, one can compare search args to decide if search is the same. if g:ag.count grows or shrink, just remember cursor position on search results. If it is on context line position can be loose (just move to search match). Remember to open/closed searches.

map to +/ -

Integration with environment

I have been using my simplistic script ag-vim to show results of searches from shell directly in vim. If it has sense, it could be improved and bundled with vim plugin. Then symlinked somewhere like $HOME/.bin whichever you added to $PATH.

• ag-vim -:<L><[bfhg]> -- can be aliased in shell to agv, agb, agf, ..., aglv, aglb, ..., agg
• open qf/loc/group window in fullscreen on vim start, resize to default on choosing result
• possible additional settings for vim when working in exploration w/o intention to edit.

Add shorcut search to command line history

Is useful to reuse old searches, but nowadays it is not stored in command line history

open AgGroup in quickfix

adhere to standard quickfix for searches
Allow search on new buffer with a function

Add split windows shorcut

horizontal opens above search window
vertical opens above left search window (but without get full height)

Erratic aggroup highlighting behaviour

Go to some dir. Lets t/fixture. Call there vim and make search in it AgGroup s.
Group line highlight can disappear after second. Then move down -- and it will re-appear.
When we stop on :3 -- it will disappear again and returns after moving to :4.
Moreover, if we move up from there, on :3-:2 highlight again disappears, but when moving in contrary direction :1-:2 -- it's not. Xxx?

Fix: escaping repairing and unifying for cmdline

Unifies discussion at #27 and #28.
I have created fail-test. Need more.
Next I will commit appropriate piece of feature_args_derive.
Will be kept open for all not fixed aspects, described in natural order.

UI: Unite integration

Think of a possibility to combine Unite interface with AgGroup and their potential.

Qs: escape -> shellescape

If we call external ag command, maybe using shellescape() is more appropriate?

Propose to add hooks

As we rewrite history more-less frequently, I propose to add git hook at least onto push in master.
I think it can be helpful, to run tests on your own machine before actually pushing into master (other branches we allow to be broken).
See one of links how to do it:
http://blog.ittybittyapps.com/blog/2013/09/03/git-pre-push/

Global mappings wrapper/guards

See enhancement inside 81be809.
Added <Plug> and guards for user mappings.

Planned: extend shortcuts list after #25.

Add fallback sequence (ack, grep, etc)

Working in embedded with legacy code I'm often attached to chroot with old kernel and only minimal set of packages. Switching in/out chroot dozens times a day, I setted up somewhat compatible environment to not interrupt workflow. But ag, of course, is absent.

It wasn't big problem earlier, as ag.vim only provided simple wrapper plus several features, most of which I disabled anyways. But now I would like to treat plugin as general search interface, which can work as is. Though such feature somewhat more wide than original plugin name, but splitting UI and core isn't such a bad idea?

After all we anyway make separate command composition, launching, results processing and interaction with them.
(P.S. Launching must be separate to introduce neovim jobs or vim-dispatch tasks).

Move options definition in appropriate place

Defining them in autoload/ag.vim don't work anymore, after splitting into autoload/ag/*.vim.

• Like idea to create separate file autoload/opts.vim and then rename all options as g:ag#opts#<name>. But then all names will became obsolete.
• Temporarily moved into plugin/ag.vim -- longer startup, but more compatible with old configurations.
  If then it will be agreed, we return to first case and add echom deprecated guards to old options.

Merging with rking (workflow)

Do you plan to merge your undoubtedly fascinating additions into current trunk of rking, or continue to maintain this work as separate fork? If latter, could you please update your repo by merging with rking?

Add operator-pending mappings, if available

Using word under cursor is cool, but I used to search highly messed symbol combinations.
Visual highlight is good option for this, but... one key less is even better?
With guards it would look like in vim-quickhl.
However, there already exist plugins for something similar, so need some discussion. You can use them for copypast/inspiration or to conclude this best to be standalone. I considered to implement this myself, but those irritative slow reactions on pull requests in main fork... vim-operator-gsearch and vim-operator-search

Task: decomposition

After all, I started to do this. Because this task blocks multiple others at current moment.

• distribute functions through files and rename api accordingly
• split long functions in shorter ones
• slight refactoring of var names / visibility scopes, due to splitting
• no new changes / no re-working of mechanisms

navigate through results

Open sequentially folds from result

based on rking#87 comments

Fix: right buftype for each type of search results viewing

Currently all code in ag.vim is intermingled and partially duplicated.
I don't want similar thing in tests.
Each Ag* command must provide it's own view interface, but not whole core, as it is now.
LAg is wrapper for Ag, therefore there is no necessity in separate tests.
But we must check opening right interface on search and focusing on its window:

• The same viewer, only one window.
• Different viewers one-by-one, but only one window opened at the same time.
• Different viewers, multiple windows at once -- like after Ag and AgGroup.
  Need to enhance current testcase and fix window opening problems.

Current problem of buftype -- getqflist() isn't empty after window closing.

Troubles with -completion=file

Seems like by using -completion=file and it's family we ressurect bug with escaping # %.
But now we can't intercept and escape command properly, because expansion takes place before argument will be supplied into our functions.
As alternative I propose to use something like

fun! ListFilesRegex(arg, line, pos)
  return systemlist("ag -S -g '".shellescape(a:arg)."' ")
endfun
command! -bang -nargs=* -complete=customlist,ListFilesRegex ...

This way it will also allow us to supply name or regex to search possible name/path patterns recursively. If it will be somewhat slow, we always can introduce option and fallback to vim's glob(...).
Or, of cource, we can simply disable completion at all, to fix this issue. You thoughts?

Refactoring of suite.sh

There are manu obsolete/bloated constructions inherited from intermix of sh and old bash.
All code simply refactored, keeping old logic.
But need thoroughly testing in all previously used usecases.
Merged into master to test on travis in f064aa0.

Idea: incremental search in searched

Unite can fuzzy-filter matching -- as example opening line buffer and typing chars, we can filter lines on-the-fly. If we create sources from ag, we can apply same filtering process to found matches. As alternative we could use quickfix-reflector to filter matches in similar way. But there is the end of what it can.
Alternative:

• Search in dir patt A then in only found files search which contain patt B and in only that list (twice filtered) show matches for patt C
• Search wherever matches A, than amongst them search (for same lines) all matches B (similar to Unite) or by using additional zero-matching -- in context of +/-N lines
• ...

Any other usecases, please. It will be welcomed heartily and included into help, once implemented.

Fix: wayward g:ag_highlight

Works as expected only in hothouse conditions.

• Enables highlight even if search was broken and there is no search results -- like when non-escaped #% are there. Then highlights first part of search, even when there no results.
• Doesn't respect ag options like -w / -Q / ...

Make space shorcut cyclic

Allow to go to first search after reach the end

configurable shortcuts for AgGroup

maybe not everybody would use ag as shortcut.

https://github.com/albfan/ag.vim/tree/shortcuts

Make configurable and merge

Fix: make completely silent execution of Ag* commands in vim/nvim.

Currently on exec there is once blinking shell before showing output.
Investigate is it possible to suppress such behaviour.

Avoid parse command for config

commands starting with l means location list, ending with -g File search. Avoid that use a real flag config mechanishm

Expand target selection to other Ag commands

You introduced auto-select function ag#GetArgs.
It has sense to expand its usage to other ag#... functions, to introduce more useful <Plug>(ag-... mappings.

hide/show results

Sometimes results undesired are hard to filter from AgGroup. It will be helpful to be able to hide particular results from an existing AgGroup output

highlight errors

when moving aroung highlight fails intermittently

Manage smartcase in syntax highlight

Respect lowercase search do case insensitive search (so highligth must do)
Allowing parameters in Ag arguments will hide this (-G would seem no lowercase search)

Smarter args to ag

Consider using arguments -w with <cword> to eliminate partial matchings
and -Q with visual -- to treat visual selection as is and not like pattern.

Allow to filter filenames

It's handy to shrink the scope of files searched

• search only *.c files
• search only blabla*.blabla