Increase the speed and amount of vim knowledge at your fingertips with precise searching of vim's items: keys (keybindings), options and commands. vimdb is aware of vim's default items, ones in your vimrc and ones in plugins. vimdb's plugin detection works only if you're using a pathogen-like setup i.e. each plugin has its own directory under ~/.vim/bundle/ (see Configuration below to change the directory). Tested with vim >= 7.2 on mac and windows. Works only on ruby 1.9.x.


$ gem install vimdb


Basic examples searching different vim items:

# List keys with Ctrl

More Usage

As you can see from the last example, vimdb supports options for each command. For a command's listing of options use --help or -h:

$ vimdb keys --help
Usage: vimdb keys [QUERY]

  -a, --all          search all fields
  -f, --field        field to query
  -i, --ignore_case
  -m, --mode         search by mode, multiple modes are ORed
  -n, --not          return non-matching results
  -r, --regexp       query is a regexp
  -R, --reload       reloads items
  -s, --sort         sort by field
  -t, --tab          print tab-delimited table

  List vim keys

As you can see, keys can be searched by keystroke, mode, description or from (default, user or plugin name). Some examples:

# List keys with Ctrl-A combo

Advanced Usage

vimdb can be customized with your own commands thanks to its rc file and command engine, boson. For example, my rc file defines a command that detects conflicts between default keys and plugin keys:

$ vimdb conflict
| key   | mode | from                | desc/action                                                                     |
| C-w o | n    | default             | close all but current window (like |:only|)                                     |
| C-w o | n    | zoomwin plugin      | <Plug>ZoomWin                                                                   |
| *     | n    | default             | search forward for the Nth occurrence of the ident under the cursor             |
| *     | nos  | tcomment_vim plugin | :TCommentRight<CR>                                                              |
| *     | n    | default             | search forward for the Nth occurrence of the ident under the cursor             |
| *     | nos  | tcomment_vim plugin | :TComment<CR>                                                                   |

If you look at conflict's implementation, you see it's only about a dozen lines. Since vimdb stores vim items as array of hashes, you can use these within commands for whatever purpose.

To illustrate creating a command, let's create one that lists the first given number of vim commands. In your ~/.vimdbrc:

class Vimdb::Runner
  desc "Prints first X options"
  def first(num)
    # Set item type we're retrieving
    puts Vimdb.user.items.first(num.to_i).map {|e| e[:name] }

To test drive it:

$ vimdb first 5


Configure vimdb with a ~/.vimdbrc (in ruby), which is loaded before every command request. For example, to configure where plugins are stored:

# plugins stored in ~/.vim/plugins
Vimdb.plugins_dir = 'plugins'

For a more thorough example, see my rc file.

Vim Mappings

Since vimdb runs on ruby 1.9.x, there's a good chance you don't have vim compiled against ruby 1.9.x. No worries, use rvm or rbenv to install a 1.9.x version. Then to invoke vimdb within vim, set up a key to pipe out to vimdb using rvm or rbenv:

map <Leader>v :!rbenv exec vimdb
" or for rvm
map <Leader>v :!rvm 1.9.3 vimdb

Key Modes

Vim's key modes are represented as single letters

  • n: normal
  • c: commandline
  • i: insert
  • o: operation
  • v: visual
  • s: select

If you're unfamiliar with all these modes read about them in vim with ':h :map-modes'.

The following modes from :map were altered to fit into the above modes:

  • ! -> ci
  • l -> ci
  • x -> v
  • v -> vs

How It Works

This gem creates a vimdb database, ~/.vimdb.pstore, by parsing your vim documentation and outputs of vim commands. When an item is first searched it is parsed. Subsequent searches are cached. To reload (and reparse) you database, pass a --reload option to most commands.


Wanted to learn faster than :help would let me.


  • mattn for windows support


See here


  • Add support for more vim items - variables, functions
  • Considering user annotation for vim items