greputils : Interface with grep, find and id-utils (not just another grep wrapper)
| script karma
Downloaded by 3938
Comments, bugs, improvements
script versions (upload new version)
|Hari Krishna Dara|
|Derived from my original idutils.vim, this script is a lot more powerful and useful than ever. The commands that make use of Vim built-in grep are especially useful and unique (thanks to Tim Chase for the idea).
- There are many plugins that wrap the Vim built-in :grep command and try
to simplify the usage. However this plugin aims at providing two
- Escape the arguments such that the arguments can be passed to the
external grep/lid/find literally. This avoids unwanted
interpretations by the shell, thus allowing you to concentrate on
the regular expression patterns rather than how to escape them.
This has been tested well on both windows and UNIX with
sh/bash/cmd as command shells.
- Allow you to preview the results before letting Vim handle them as
part of quickfix. This, besides allowing you to further filter the
results, also prevents Vim from adding buffers for files that are
uninteresting and thus help reduce the number of buffers. It also
supports basic quickfix commands that can be used to open a buffer
without needing to convert it to a quickfix window. You can
consider it as a lightweight quickfix window. The preview window
is also great if you just want to take a peak at the results, not
really navigate them (such as to get an estimate of where all a
reference is found).
- Also provides commands to run the Vim built-in :g/re/p on multiple
buffers using :argdo, :bufdo and :windo commands and redirect the
output to the grep-results preview window. You can then convert the
results to a quickfix window, or use the preview window to navigate.
- As a bonus, the plugin also works around Vim problem with creating a
number of unnamed buffers as you close and open quickfix window
several times. This helps keep buffer list uncluttered.
- The command merely wraps the built-in :grep, :grepadd, :cfile and
:cgetfile commands to create the quickfix list. The rest of the quickfix
commands work just like they do on the quickfix results created by using
only the built-in functionality. This also means that the plugin assume
that you have the options such as 'grepprg', 'shellpipe' are properly
set. Read the help on quickfix for the full list of commands and options
that you have.
- Other than the preview functionality which enables filtering, the plugin
also provides an easy way to specify a number of filter commands that
you can chain on the output of the grep/lid/find, each prefixed with
"+f". The arguments to the filter command are themselves escaped, the
same way as the grep command arguments as described above.
- Supports GNU "grep" and MS Windows "findstr" for running "find-in-file"
kind of searches, id-utils "lid" for running index searches, and GNU
"find" to search for file names. If you need to add support for a new
grep command or a grep-like tool, it is just a matter of modifying a few
internal variables and possibly adding a new set of commands.
- On windows, setting multiple ID files for IDPATH doesn't work, so the
plugin provides a workaround by running "lid" separately on each ID file
if there are multiple ID files separated by ";" in the IDPATH.
- Make sure that the 'grepprg' and 'shellpipe' options are properly set
and that the built-in :grep itself works. For GNU id-utils, make sure
IDPATH environmental variable is set or path to the ID file is specified
with the "-f" argument in the g:greputilsLidcmd setting. You can also
specify the "-f ID" arguments to the :IDGrep command.
- Uses EscapeCommand() function from genutils.vim plugin that supports
Cygwin "bash", MS Windows "cmd" and Unix "sh" for shell escaping. Other
environments are untested.
- Defines the following commands:
Grep, GrepAdd, IDGrep, IDGrepAdd, Find, FindAdd
Grepp, GreppAdd, IDGrepp, IDGreppAdd, Findp, FindpAdd
The second set of commands are used to open the results in a preview
window instead of directly in the quickfix window. And those that have a
suffix of "Add" add the new list of results to the existing list,
instead of replacing them (just like in :grepadd). This can be very
useful in combination with the preview commands.
You can open the preview window at anytime using GrepPreview command.
Once you are in the preview window, you can filter the results using the
regular Vim commands, and when you would like to browse the results
using Vim quickfix commands, just use Cfile and Cgetfile commands, which
are functionally equivalent to the built-in cfile and cgetfile commands
respectively, except that they don't take a filename as argument use the
current preview window contents to create the error-list. There are
also, GOpen, GClose and GWindow commands defined on the lines of copen,
cclose and cwindow respectively.
Use the GrepPreviewSetup command to convert an arbitrary buffer
containing :grep output as a preview window. This is useful to take
advantage of the quickfix like functionality that the plugin provides on
grep results generated by your own commands.
If cmdalias.vim is installed, it also creates aliases for the Grep,
GrepAdd, Cfile and Cgetfile commands to the corresponding built-in
commands, i.e., grep, grepadd, cfile and cgetfile respectively.
The preview window supports the following commands:
preview command quickfix command ~
GG [count] cc [count]
[count]GPrev [count]cNext, cprevious
The commands supports [count] argument just like the corresponding
<grep command> [<grep/lid/find options> ...] <regex/keyword>
[<filename patterns>/<more options>]
[+f <filter arguments> ...]
Note that typically you have to pass in at least one filename pattern to
grep/findstr where as you don't pass in any for lid.
- Also defines the following commands:
ArgGrep, ArgGrepAdd, BufGrep, BufGrepAdd, WinGrep, WinGrepAdd
You can use the above commands to run Vim's built-in g/re/p command to
find matches across buffers loaded in the current session, without
needing any external tools. Each of the above commands (and their "Add"
variants), run g/re/p command on a bunch of buffers loaded using one of
:argdo, :bufdo and :windo commands respectively. These commands are
designed to always open the results in the preview window. If you like,
you can convert it to a quickfix result, by using :Cfile or :Cgetfile
If you don't specify a pattern, the current value in search register
(@/) will be used, which essentially means that the last search pattern
will be used. See also g:greputilsVimGrepSepChar setting under
The range, if not specified, defaults to all the lines in all the
applicable buffers. If you explicitly specify a range, please note that
a range such as "%" or "1,$" is translated to the absolute line numbers
with reference to the current buffer by Vim itself, so it is not the
same as not specifying at all. This means, if there are 100 lines in the
current buffer, specifying "%" or "1,$" is equivalent to specifying
"1,100" as the range. The range is more useful with the "GrepBufs"
command mentioned below.
- Also defines "GrepBufs" command that can be used to grep for a Vim
regular expression pattern in the specified set of buffers (or the
current buffer). If no pattern is specified it will default to the
current search pattern. Buffers can be specified by name (see :h
bufname()) or by their number using the #<bufno> notation. You can also
complete the buffer names by using the completion character (<Tab>).
[range]GrepBufs[Add] [pattern] [buffer ...]
This by syntax is very close to the Unix grep command. The main
difference being that it uses Vim regex and it searches the buffers
already loaded instead of those on the file system.
The range has same semantics as for any of the "arg", "buf" or "win" grep
commands, but it is more useful here while limiting the grep for one
The following examples assume that you are using GNU grep for both the
'grepprg' and as the g:greputilsFiltercmd.
- Run GNU grep from the directory of the current file recursively while
limiting the search only for Java files.
Grep -r --include=*.java \<main\> %:h
- Run lid while filtering the lines that are not from Java source.
IDGrep main +f \.java
- Run lid while filtering the lines that contain src.
IDGrep main +f -v src
- Find Java files starting with A and ending with z under src.
Find src -iname A*z.java
- To search for the current word in all the files and filter the results
not containing \.java in the grepped output. This will potentially
return all the occurences in the java files only.
IDGrep <cword> +f \.java
- If any argument contains spaces, then you need to protect them by
prefixing them with a backslash. The following will filter those lines
that don't contain "public static".
IDGrep <cword> +f public\ static
- Run ":bufdo g/public static/p" and show output in preview window:
BufGrep public\ static
Search_key_words: idutils greputils greputil id-utils gnu id grep gid mkid lid windo argdo bufdo Hari Krishna Dara
|- Drop the file in your plugin directory or source it from your vimrc.
- Requires genutils (vimscript#197) and multvals (vimscript #171) plugins
also to be installed.
g:greputilsLidcmd, g:greputilsFindcmd, g:greputilsFiltercmd,
g:greputilsFindMsgFmt, g:greputilsAutoCopen, g:greputilsVimGrepCmd,
- Use g:greputilsLidcmd and g:greputilsFiltercmd to set the path/name to
the lid and GNU or compatible find executable (defaults to "lid").
- Use g:greputilsFiltercmd to set the path/name of the command that you
would like to use as the filter when "+f" option is used (defaults to
- Set g:greputilsFindMsgFmt to change the message (%m) part of the find
results. You can specify anything that is accepted in the argument for
"-printf" find option.
- Use g:greputilsAutoCopen to specify if the error list window should
automatically be opened or closed based on whether there are any
results or not (runs :cwindow command at the end).
- Use g:greputilsVimGrepCmd and g:greputilsVimGrepAddCmd to have the
plugin run a different command than the built-in :grep command to
generate the results. This is mainly useful to use the plugin as a
wrapper to finally invoke another plugin after the arguments are
escaped and 'shellpipe' is properly set. The callee typically can just
run the :grep command on the arguments and do additional setup.
- Use g:greputilsGrepCompMode, g:greputilsLidCompMode and
g:greputilsFindCompMode to change the completion mode for Grep, IDGrep
and Find commands respectively. The default completion mode for Grep
and Find are "file" to match that of the built-in commands, where as
it is set to "tag" for IDGrep (except the -f argument to specify an ID
file, you never need to pass filenam to lid). When completion mode is
"file", Vim automatically expands filename meta-characters such as "%"
and "#" on the command-line, so you still need to escape then. If this
is an issue for you, then you should switch to "tag" or a different
completion mode. When completion mode is not "file", the plugin
expands the filename meta characters in the file arguments anyway, and
this can be considered as an advantage (think about passing patterns
to the command literally). However it is still useful to have
"<cword>" and "<cWORD>" expand inside the patterns, in which case you
can set g:greputilsExpandCurWord setting. Changing this option at
runtime requires you to reload the plugin.
- When completion mode is not set to "file", you can set
g:greputilsExpandCurWord to have the plugin expand "<cword>" and
"<cWORD>" tokens. This essentially gives you all the goodness of file
completion while still being able to do tag completions.
- For Vim built-in grep operations such as :BufGrep, if you want to
change the character sorrounding the pattern from the default '/' to
something else (see |E146|), you can use the
g:greputilsVimGrepSepChar. This is useful if you have a lot of "/"
characters in your pattern.
- The plugin normally preserves the previous results in the preview
window, which you can retrieve by doing an undo immediately after
generating the new results, inside the preview window. If you don't
like this, you can disable this feature by resetting
g:greputilsPreserveLastResults setting. You can instead set the
g:greputilsPreserveAllResults to preserve all the changes done in the
preview window, by user and the plugin itself.
- While using the *pAdd commands (that add results to preview window),
the individual set of results are folded together to be able to
identify them better. You can disable this feature by resetting the
Click on the package to download.
ip used for rating: 188.8.131.52
||Hari Krishna Dara
||- Support for inversing the search pattern. You can pass "!" to built-in grep commands.
- Fixed broken GrepBufs command.
||Hari Krishna Dara
||Fixed broken Cfile command.
||Hari Krishna Dara
||Just added support for specifying range for all the built-in grep commands. Useful mainly for GrepBufs command.
||Hari Krishna Dara
||- Better handling of unsaved and unnamed buffers while doing built-in grep.
- New setting g:greputilsPreserveAllResults to be able to undo over
several search results, as far as Vim allows you to do.
- Better integration with selectbuf so that the built-in grep performs
better, if both plugins are installed (need to get the latest
- Much better handling of opening and closing preview window. Requires
the latest version genutils.vim.
- Misc. bug fixes. Update documentation.
||Hari Krishna Dara
||- Augmented the built-in grep (:WinGrep, :ArgGrep, :BufGrep)
functionality with the new command :GrepBufs to grep specified
buffers only. This is very similar to unix :grep command with given
- New commands :GOpen, :GClose and :GWindow on the lines of :copen,
:cclose and :cwindow to work with the preview window. The existing
commands :GNext, :GPrev and :GG commands now work globally, just like
the :cnext, :cprev and :cc commands.
- Fixed misc. bugs.
||Hari Krishna Dara
|| - Misc. improvements for Grep Preview window.
- The Grep Preview window now implements undo functionality to be able
to undo and recover the previous result set.
- When you add results to the existing results, the results sets are
folded such that you can easily distinguish them.
- Preview window shouldn't be resized if it is already visible.
- The grep commands that utilize the Vim's built-in grep functionality
are refined and are more useful than ever.
- They now have command-line completion enabled to complete tags.
- <cword> and <cWORD> were not being expanded for Vim-grep
- Cleanup the grep window for "pattern not found" error messages and
- The current buffer is restored at the end of the operation.
- Vim event generation is disabled. This provides a significant
improvement in the speed as well as avoid side effects. This along
with the above improvement also makes the grep operation look
- New useful GrepPreviewSetup command.
- On windows, setting multiple ID files in IDPATH doesn't work, as it
does on *NIX. The plugin works around this problem by invoking lid on
individual ID files and gathering all the results.
- If you use findstr on windows, grepping on a single file doesn't
generate the results in the right format (no filename prefix etc.).
The plugin now works around this issue.
- See help on new settings g:greputilsVimGrepSepChar,
g:greputilsPreviewCreateFolds and g:greputilsPreserveLastResults.
||Hari Krishna Dara
||- Added BufGrep, WinGrep and ArgGrep commands that use the Vim's built-in g/re/p command with :bufdo, :windo and :argdo respectively to do search. This is an experimental feature, please try it and give feedback.
- Also fixed a couple or more of minor bugs.
||Hari Krishna Dara
||Requires Vim 6.3
- Added support for running GNU find command and open the files from preview or through quickfix result.
- Basic quickfix like commands have been added to the [Grep Preview] window. This is very useful if you want to quickly reach one or two files by running "find" or "lid" and don't care about the full results.
- The default completion mode for grep has been changed to "file" from "tag", which is what is more useful.
- Fixed :Cfile and :Cgetfile to work correctly if the current directory has changed since the results are generated.
||Hari Krishna Dara
||This is an enhanced version of idutils.vim, made more generic and supports regular :grep command too. See description for information on the new version. Needs Vim 6.3