sponsor Vim development Vim logo Vim Book Ad

greputils : Interface with grep, find and id-utils (not just another grep wrapper)

 script karma  Rating 60/30, Downloaded by 5236  Comments, bugs, improvements  Vim wiki

created by
Hari Krishna Dara
script type
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
    specific features:
        - 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.
      :h quickfix
  - 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]GNext        [count]cnext
      [count]GPrev        [count]cNext, cprevious
      <CR>                <CR>
      <2-LeftMouse>       <2-LeftMouse>
    The commands supports [count] argument just like the corresponding
    quickfix command.
  General Syntax:
      <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
  General Syntax:
      [range]<Arg|Buf|Win>Grep[Add] [<pattern>]
    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
    installation section.
    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>).
  General Syntax:
      [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
    buffer alone.
  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
install details
- 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.
Optional Settings:
    g:greputilsLidcmd, g:greputilsFindcmd, g:greputilsFiltercmd,
    g:greputilsFindMsgFmt, g:greputilsAutoCopen, g:greputilsVimGrepCmd,
    g:greputilsVimGrepAddCmd, g:greputilsGrepCompMode,
    g:greputilsLidCompMode, g:greputilsFindCompMode,
    g:greputilsExpandCurWord, g:greputilsVimGrepSepChar,
    g:greputilsPreserveLastResults, g:greputilsPreserveAllResults,
  - 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
    g:greputilsPreviewCreateFolds setting.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
greputils.vim 2.8 2005-07-14 6.0 Hari Krishna Dara - Support for inversing the search pattern. You can pass "!" to built-in grep commands.
- Fixed broken GrepBufs command.
greputils.vim 2.7 2005-07-14 6.0 Hari Krishna Dara Fixed broken Cfile command.
greputils.vim 2.6 2005-07-14 6.0 Hari Krishna Dara Just added support for specifying range for all the built-in grep commands. Useful mainly for GrepBufs command.
greputils.vim 2.5 2005-03-16 6.0 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.
greputils.vim 2.4 2004-10-18 6.0 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.
greputils.vim 2.3 2004-08-20 6.0 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
    completely tranparent.
- 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.
greputils.vim 6.2 2004-08-20 6.0 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.
greputils.vim 2.1 2004-08-20 6.0 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.
greputils.vim 2.0 2004-08-20 6.0 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
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.