This article is part of the article series "Vim Plugins You Should Know About."
<- previous article next article ->
Vim Plugins, surround.vim

This is the third post in the article series "Vim Plugins You Should Know About". This time I am going to introduce you to a plugin called "matchit.vim".

If you are intrigued by this topic, I suggest that you subscribe to my posts! For the introduction and first post in this article series, follow this link - Vim Plugins You Should Know About, Part I: surround.vim. Part II is here: repeat.vim.

Matchit extends the existing functionality of "%" key (percent key). I'll first briefly remind you what the original "%" does and then explain how matchit.vim enhances it.

The original "%" key allows you to jump between various pairs of characters and some programming constructs. For example, it jumps between pairs of parenthesis ( )'s, { }'s, [ ]'s. It also jumps between opening and closing tags of C style comments /* and */. And it's smart enough to jump between C preprocessor directives - from #if to #endif and match #elif or #else in between.

Here is an example. Suppose you have this code and you press "%", the cursor jumps between { and } parens:

matchit vim plugin example

Matchit.vim extends this functionality. It's written by Benji Fisher and it adds support to cycle between if, else if, else, endif keywords in various programming languages. Another improvement is the ability to find pairs of HTML tags, such as <p> ... </p>. Another handy mapping is "g%" that does "%" in opposite direction (goes from endif to else to else if to if). The plugin also includes several other mappings like "]%", "[%" and "a%" but I could not figure out how to effectively use them in real life code, so I don't use them at all.

Here is another example. Suppose you are editing this HTML and you quickly want to go to the corresponding closing tag of <body>. Just press "%":

matchit vim html example

Overall it's a great plugin to have in your inventory!

How to install matchit.vim?

Matchit.vim has been included in vim since version 6.0. However there are newer versions of the script available with bug fixes and enhancements.

To get the latest version:

  • 1. Download
  • 2. Extract to ~/.vim (on Unix/Linux) or ~\vimfiles (on Windows).
  • 3. Run :helptags ~/.vim/doc (on Unix/Linux) or :helptags ~/vimfiles/doc (on Windows) to rebuild the tags file (so that you can read :help %, :help g%, etc.)
  • 4. Restart Vim or source matchit.vim with ":so ~/.vim/plugin/matchit.vim" on Unix or ":so ~/vimfiles/plugin/matchit.vim" on Windows).
  • 5. Use '%' to find corresponding

For Python programmers: Turns out the original matchit.vim plugin does not match if / elif / else. Benji extended matchit.vim itself and created "python_matchit.vim". This extension allows us to use the "%" key to cycle through if/elif/else, try/except/catch, for/continue/break, and while/continue/break structures. The script also defines g% to cycle in the opposite direction, and it defines two other motions, [% and ]%, go to the start and end of the current block, respectively.

How to install python_matchit.vim?

Python_matchit.vim is a filetype plugin. It has to be installed in "ftplugin" directory. Follow these steps to get it installed:

  • 1. Download python_matchit.vim.
  • 2. Put it in ~/.vim/ftplugin (on Unix/Linux) or ~\vimfiles\ftplugin (on Windows).
  • 3. Restart Vim or source matchit.vim with ":so ~/.vim/ftplugin/python_matchit.vim" on Unix or ":so ~/vimfiles/ftplugin/python_matchit.vim" on Windows).

The same steps can be taken to install matchit for Ruby.

Have Fun!

Happy matching with matchit.vim!

This article is part of the article series "Vim Plugins You Should Know About."
<- previous article next article ->


February 05, 2009, 23:24

Excellent series. Please keep 'em coming.

February 06, 2009, 06:01

Hey, there. I found your blog through Technorati, and my attention was grabbed!

I've never much used Vim except when I had no other choice in some university programming courses, but this series of articles is making me take a second thought about it. I may just try it out again for old time's sake. :D

Nice articles.

February 06, 2009, 09:48

Thanxs I was just looking for that kind of plugin. Always very annoying if you can't find the closing "" or are not sure where the missing tag is!

Daniel Permalink
February 06, 2009, 10:41

Regarding the python file type plugin:
It's better tp put it into '~/.vim/after/ftplugin/'.

Thus it's loaded after the default python file
type plugin. Otherwise you're replacing the default
file type plugin.

Vincent Wang Permalink
February 06, 2009, 14:49

for me, 'a%' is very useful, for example, when cursor is in the middle of a if-else-endif block, you can use 'va%' to make the whole block selected in visual mode for further operation.

Art Permalink
February 06, 2009, 15:14


can you add a link to part II next to the link to the part III for everyone's convenience?


Gabriel Permalink
February 11, 2009, 05:45

According to the plugin's page, it should be working in vim 7.x

I tried matchit.vim with both vim 7.2.079 and 7.1.314 but I never got it working.

Gabriel Permalink
February 11, 2009, 10:12

I've finally found it!
I needed to add the following line somewhere in my .vimrc file:

filetype plugin on

without this, the ftplugins would not set the proper match_words variable.

now that it works, I can begin to do some real working around.

p.s. : also found this handy plugin :

May 05, 2010, 13:11

@Gabriel: Useful comment. Saved me from a lot of debugging.

ix8 Permalink
February 22, 2009, 00:02

Great articles Peter! I'm on arch and I can't get workin' these plugins. I put them in the plugins' directory, but they don't work... I try also doing :source *pluginspath/plugin.vim*... Error E492 It's not a vim command... (:cs' ...) Can u help me?
Thanks a lot!

Irha Permalink
April 06, 2009, 23:41

you don't need to place the python_matchit.vim in the after plugin as it is not a replacement for the regular ftplugin (and thus doesn't set the loaded_ftplugin variable).

reader Permalink
April 30, 2009, 13:01

1 Thanks for this knowledge sharing site
2 Care to share how you schedule your time?

Tyler Permalink
September 14, 2011, 23:18

The HTML tag matching ruins the normal JavaScript brace matching for embedded scripts. Most of the time you can get to closing tag with * unless you have many layers of the same tag type.

Leave a new comment

(why do I need your e-mail?)

(Your twitter handle, if you have one.)

Type the word "cloud_121": (just to make sure you're a human)

Please preview the comment before submitting to make sure it's OK.