Overview

Supertab is a vim plugin which allows you to use <Tab> for all your insert completion needs (:help ins-completion).

Features

• Configurable to suit your needs:
  • Default completion type to use.
  • Prevent <Tab> from completing after/before defined patterns.
  • Close vim's completion preview window when code completion is finished.
  • When using other completion types, you can configure how long to 'remember' the current completion type before returning to the default.
  • Don't like using <Tab>? You can also configure a different pair of keys to scroll forwards and backwards through completion results.
• Optional improved 'longest' completion support (after typing some characters, hitting <Tab> will highlight the next longest match).
• Built in 'context' completion option which chooses the appropriate completion type based on the text preceding the cursor.
  • You can also plug in your own functions to determine which completion type to use.
• Support for simple completion chaining (falling back to a different completion type, keyword completion for example, if omni or user completion returns no results).

Installation

You have a few options when it comes to installing supertab:

1. Use vim 8+ plugins:

   $ mkdir -p ~/.vim/pack/plugins/start
   $ git clone --depth=1 https://github.com/ervandew/supertab.git ~/.vim/pack/plugins/start/supertab
   

   Depending on your system you may also need to add packloadall to your ~/.vimrc.

2. Use your linux package manager:

   Some linux distributions include a supertab package so you don't have to manage the install/upgrade of supertab separately from other software on your system.

3. Use a vim plugin manager:

   There are several plugin managers for vim, which will either allow you to manually clone vim plugin repositories, or will do so for you. Probably the two most popular ones currently are pathogen and vundle. Please refer to their docs for instructions on how to install plugins.

Documentation

You can access the supertab documentation from within vim using the following command:

:help supertab

You can also view the text file on github.

Frequently Asked Questions

• Why isn't anything happening when I hit <tab>?

  First make sure you properly installed supertab and that you have plugin support enabled in vim. You can run the following in vim to check that supertab was loaded:

  :scriptnames
  

  Next make sure that the supertab insert mapping exists. It's possible some other plugin could have overridden the mapping. You can check this by running the following in vim, which would show that it's mapped to SuperTabForward:

  :verbose imap <tab>
  

  If supertab has been loaded and the insert mapping looks correct, make sure you don't have the paste option enabled in your vimrc or elsewhere. When that option is enabled, all insert mappings are disabled. You can run the following command in vim to check if and where that option was set:

  :verbose set paste?
  

• Why isn't supertab honoring my configured settings (attempts to complete at the start of a line, always performs keyword completion instead of my configured default, etc.)?

  Chances are that you have a very old version of snipmate installed, or something similar, which will issue a <c-n> when no snippet is found. Supertab use to map to <c-n>, so this behavior would act as a fallback to supertab, but current versions of supertab no longer do so, resulting in snipmate bypassing supertab entirely.

  You can check if this is the case by running the following in vim to see what is mapped to <tab>:

  :verbose imap <tab>
  

  To resolve the issue you can either:

  1. Install my fork or
  2. Upgrade to a more recent snipmate fork, like garbas/vim-snipmate

  See #74 for additional details.

• Why does <tab> navigate the completion menu from bottom to top?

  First, if after reading the explanation below (or if you don't want to bother reading it), you still want the default to scroll down the list then you can use:

  let g:SuperTabDefaultCompletionType = "<c-n>"
  

  or if your default completion type is currently context then you can use this instead:

  let g:SuperTabContextDefaultCompletionType = "<c-n>"
  

  Now on to the reasoning behind this. When using <c-p> or <c-n> to start insert completion, both populate the completion popup with the same list of words in the same order, the only difference is that <c-p> highlights the nearest matching word located above the current cursor position, which is the result at the bottom of the completion popup. Without supertab installed, continuing to hit <c-p> will walk up the list to next nearest word above the cursor.

  I think Bram chose to display the results like this so that

  1. the completion logic is the same for <c-n> and <c-p>, only the first entry to highlight differs
  2. so that the behavior of <c-p> mode is consistent, always moving up the list and
  3. when starting <c-p> mode you don't have to switch over to using <c-n> to get the next nearest entry, just continue to hit <c-p>.

  So, with supertab I wanted to preserve the same behavior. If <c-p> is your default completion method (supertab defaults to this being the case), then <tab> will start it and additional uses of <tab> will move up the list instead of down so that you don't have to suddenly switch to using <s-tab> to get the next nearest result.

  Why is <c-p> the supertab default? The original supertab author found (and I agree with his finding) that while coding, the keyword match you want is typically the closer of the matches above the cursor, which <c-p> naturally provides.