+*command-t.txt* Command-T plug-in for VIM
+ 1. Introduction |command-t|
+ 2. Requirements |command-t-requirements|
+ 3. Installation |command-t-installation|
+ 4. Trouble-shooting |command-t-trouble-shooting|
+ 5. Usage |command-t-usage|
+ 6. Commands |command-t-commands|
+ 7. Mappings |command-t-mappings|
+ 8. Options |command-t-options|
+ 9. Author |command-t-author|
+10. Website |command-t-website|
+11. Donations |command-t-donations|
+12. License |command-t-license|
+13. History |command-t-history|
+The Command-T plug-in provides an extremely fast, intuitive mechanism for
+opening files with a minimal number of keystrokes. It's named "Command-T"
+because it is inspired by the "Go to File" window bound to Command-T in
+Files are selected by typing characters that appear in their paths, and are
+ordered by an algorithm which knows that characters that appear in certain
+locations (for example, immediately after a path separator) should be given
+Screencasts demonstrating the plug-in can be viewed at:
+The plug-in requires VIM compiled with Ruby support, a compatible Ruby
+installation at the operating system level, and a C compiler to build
+1. VIM compiled with Ruby support
+You can check for Ruby support by launching VIM with the --version switch:
+If "+ruby" appears in the version information then your version of VIM has
+Another way to check is to simply try using the :ruby command from within VIM
+If your VIM lacks support you'll see an error message like this:
+ E319: Sorry, the command is not available in this version
+The version of VIM distributed with Mac OS X does not include Ruby support,
+while MacVim does; it is available from:
+For Windows users, the executable from www.vim.org does include Ruby support.
+In addition to having Ruby support in VIM, your system itself must have a
+compatible Ruby install. In practice this usually means a version of Ruby from
+the 1.8 series, as VIM's support for 1.9 is still not official.
+The current version of Mac OS X comes with Ruby 1.8.7.
+A suitable Ruby environment for Windows can be installed using RubyInstaller
+If using RubyInstaller be sure to download the installer executable, not the
+7-zip archive. When installing mark the checkbox "Add Ruby executables to your
+PATH" so that VIM can find them.
+Part of Command-T is implemented in C as a Ruby extension for speed, allowing
+it to work responsively even on directory hierarchies containing enormous
+numbers of files. As such, a C compiler is required in order to build the
+extension and complete the installation.
+On Mac OS X, this can be obtained by installing the Xcode Tools that come on
+the Mac OS X install disc.
+On Windows, the RubyInstaller Development Kit can be used to conveniently
+install the necessary tool chain:
+To use the Development Kit extract the archive contents to your C:\Ruby
+Command-T is distributed as a "vimball" which means that it can be installed
+by opening it in VIM and then sourcing it:
+The files will be installed in your |'runtimepath'|. To check where this is
+The C extension must then be built, which can be done from the shell. If you
+use a typical |'runtimepath'| then the files were installed inside ~/.vim and
+you can build the extension with:
+ cd ~/.vim/ruby/command-t
+Most installation problems are caused by a mismatch between the version of
+Ruby on the host operating system, and the version of Ruby that VIM itself
+linked against at compile time. For example, if one is 32-bit and the other is
+64-bit, or one is from the Ruby 1.9 series and the other is from the 1.8
+series, then the plug-in is not likely to work.
+As such, on Mac OS X, I recommend using the standard Ruby that comes with the
+system (currently 1.8.7) along with the latest snapshot of MacVim (currently
+On Windows, I recommend using the version 1.8.7 RubyInstaller and the
+corresponding RubyInstaller Development Kit linked to above, along with the
+standard (32-bit) version of VIM that can be downloaded from www.vim.org.
+Bring up the Command-T match window by typing:
+If a mapping for <Leader>t already exists at the time the plug-in is loaded
+then Command-T will not overwrite it. You can instead open the match window by
+A prompt will appear at the bottom of the screen along with a match window
+showing all of the files in the current directory (as returned by the
+Type letters in the prompt to narrow down the selection, showing only the
+files whose paths contain those letters in the specified order. Letters do not
+need to appear consecutively in a path in order for it to be classified as a
+Once the desired file has been selected it can be opened by pressing <CR>.
+(By default files are opened in the current window, but there are other
+mappings that you can use to open in a vertical or horizontal split, or in
+a new tab.) Note that if you have |'nohidden'| set and there are unsaved
+changes in the current window when you press <CR> then opening in the current
+window would fail; in this case Command-T will open the file in a new split.
+The following mappings are active when the prompt has focus:
+ <BS> delete the character to the left of the cursor
+ <Del> delete the character at the cursor
+ <Left> move the cursor one character to the left
+ <C-h> move the cursor one character to the left
+ <Right> move the cursor one character to the right
+ <C-l> move the cursor one character to the right
+ <C-a> move the cursor to the start (left)
+ <C-e> move the cursor to the end (right)
+ <C-u> clear the contents of the prompt
+ <Tab> change focus to the match listing
+The following mappings are active when the match listing has focus:
+ <Tab> change focus to the prompt
+The following mappings are active when either the prompt or the match listing
+ <CR> open the selected file
+ <C-CR> open the selected file in a new split window
+ <C-s> open the selected file in a new split window
+ <C-v> open the selected file in a new vertical split window
+ <C-t> open the selected file in a new tab
+ <C-j> select next file in the match listing
+ <C-n> select next file in the match listing
+ <Down> select next file in the match listing
+ <C-k> select previous file in the match listing
+ <C-p> select previous file in the match listing
+ <Up> select previous file in the match listing
+ <C-c> cancel (dismisses match listing)
+The following is also available on terminals which support it:
+ <Esc> cancel (dismisses match listing)
+Note that the default mappings can be overriden by setting options in your
+~/.vimrc file (see the OPTIONS section for a full list of available options).
+In addition, when the match listing has focus, typing a character will cause
+the selection to jump to the first path which begins with that character.
+Typing multiple characters consecutively can be used to distinguish between
+paths which begin with the same prefix.
+|:CommandT| Brings up the Command-T match window, starting in the
+ current working directory as returned by the|:pwd|
+|:CommandTFlush|Instructs the plug-in to flush its path cache, causing
+ the directory to be rescanned for new or deleted paths
+ the next time the match window is shown. In addition, all
+ configuration settings are re-evaluated, causing any
+ changes made to settings via the |:let| command to be picked
+By default Command-T comes with only one mapping:
+ <Leader>t bring up the Command-T match window
+However, Command-T won't overwrite a pre-existing mapping so if you prefer
+to define a different mapping use a line like this in your ~/.vimrc:
+ nmap <silent> <Leader>t :CommandT<CR>
+Replacing "<Leader>t" with your mapping of choice.
+Note that in the case of MacVim you actually can map to Command-T (written
+as <D-t> in VIM) in your ~/.gvimrc file if you first unmap the existing menu
+binding of Command-T to "New Tab":
+ macmenu &File.New\ Tab key=<nop>
+ map <D-t> :CommandT<CR>
+When the Command-T window is active a number of other additional mappings
+become available for doing things like moving between and selecting matches.
+These are fully described above in the USAGE section, and settings for
+overriding the mappings are listed below under OPTIONS.
+A number of options may be set in your ~/.vimrc to influence the behaviour of
+the plug-in. To set an option, you include a line like this in your ~/.vimrc:
+ let g:CommandTMaxFiles=20000
+To have Command-T pick up new settings immediately (that is, without having
+to restart VIM) you can issue the |:CommandTFlush| command after making
+Following is a list of all available options:
+ |g:CommandTMaxFiles| number (default 10000)
+ The maximum number of files that will be considered when scanning the
+ current directory. Upon reaching this number scanning stops.
+ |g:CommandTMaxDepth| number (default 15)
+ The maximum depth (levels of recursion) to be explored when scanning the
+ current directory. Any directories at levels beyond this depth will be
+ |g:CommandTMaxHeight| number (default: 0)
+ The maximum height in lines the match window is allowed to expand to.
+ If set to 0, the window will occupy as much of the available space as
+ needed to show matching entries.
+ |g:CommandTAlwaysShowDotFiles| boolean (default: 0)
+ By default Command-T will show dot-files only if the entered search
+ string contains a dot that could cause a dot-file to match. When set to
+ a non-zero value, this setting instructs Command-T to always include
+ matching dot-files in the match list regardless of whether the search
+ string contains a dot. See also |g:CommandTNeverShowDotFiles|.
+ |g:CommandTNeverShowDotFiles| boolean (default: 0)
+ By default Command-T will show dot-files if the entered search string
+ contains a dot that could cause a dot-file to match. When set to a
+ non-zero value, this setting instructs Command-T to never show dot-files
+ under any circumstances. Note that it is contradictory to set both this
+ setting and |g:CommandTAlwaysShowDotFiles| to true, and if you do so VIM
+ will suffer from headaches, nervous twitches, and sudden mood swings.
+ |g:CommandTScanDotDirectories| boolean (default: 0)
+ Normally Command-T will not recurse into "dot-directories" (directories
+ whose names begin with a dot) while performing its initial scan. Set
+ this setting to a non-zero value to override this behavior and recurse.
+ Note that this setting is completely independent of the
+ |g:CommandTAlwaysShowDotFiles| and |g:CommandTNeverShowDotFiles|
+ settings; those apply only to the selection and display of matches
+ (after scanning has been performed), whereas
+ |g:CommandTScanDotDirectories| affects the behaviour at scan-time.
+ Note also that even with this setting on you can still use Command-T to
+ open files inside a "dot-directory" such as ~/.vim, but you have to use
+ the |:cd| command to change into that directory first. For example:
+ |g:CommandTMatchWindowAtTop| boolean (default: 0)
+ When this settings is off (the default) the match window will appear at
+ the bottom so as to keep it near to the prompt. Turning it on causes the
+ match window to appear at the top instead. This may be preferable if you
+ want the best match (usually the first one) to appear in a fixed location
+ on the screen rather than moving as the number of matches changes during
+As well as the basic options listed above, there are a number of settings that
+can be used to override the default key mappings used by Command-T. For
+example, to set <C-x> as the mapping for cancelling (dismissing) the Command-T
+window, you would add the following to your ~/.vimrc:
+ let g:CommandTCancelMap='<C-x>'
+Following is a list of all map settings:
+ Setting Default mapping(s)
+ |g:CommandTBackspaceMap| <BS>
+ Delete the character at the current cursor position
+ |g:CommandTDeleteMap| <Del>
+ Delete the character to the right of the current cursor position
+ |g:CommandTAcceptSelectionMap| <CR>
+ Accept the currently selected item (opens in current window)
+ |g:CommandTAcceptSelectionSplitMap| <C-CR>
+ Accept the currently selected item
+ (opens in split window)
+ |g:CommandTAcceptSelectionTabMap| <C-t>
+ Accept the currently selected item (opens in tab)
+ |g:CommandTAcceptSelectionVSplitMap| <C-v>
+Accept the currently selected item (opens in vertical split)
+ |g:CommandTToggleFocusMap| <Tab>
+Toggle keyboard focus between prompt and match listing
+ |g:CommandTCancelMap| <C-c>
+ <Esc> (not on all terminals)
+Dismiss the Command-T prompt and match listing
+ |g:CommandTSelectNextMap| <C-n>
+Select next match in match listing
+ |g:CommandTSelectPrevMap| <C-p>
+Select previous match in match listing
+ |g:CommandTClearMap| <C-u>
+Clear all text from the prompt
+ |g:CommandTCursorLeftMap| <Left>
+Move the cursor one character to the left within the prompt
+ |g:CommandTCursorRightMap| <Right>
+Move the cursor one character to the right within the prompt
+ |g:CommandTCursorEndMap| <C-e>
+Move the cursor to the end (far right) of the prompt
+ |g:CommandTCursorStartMap| <C-a>
+In addition to the options provided by Command-T itself, some of VIM's own
+settings can be used to control behavior:
+ |'wildignore'| string (default: '')
+ VIM's |'wildignore'| setting is used to determine which files should be
+ excluded from listings. This is a comma-separated list of file glob
+ patterns. It defaults to the empty string, but common settings include
+ "*.o,*.obj" (to exclude object files) or ".git,.svn" (to exclude SCM
+ metadata directories). For example:
+ :set wildignore+=*.o,*.obj,.git
+ See the |'wildignore'| documentation for more information.
+Command-T is written and maintained by Wincent Colaiuta <firstname.lastname@example.org>.
+As this was the first VIM plug-in I had ever written I was heavily influenced
+by the design of the LustyExplorer plug-in by Stephen Bach, which I understand
+is one of the largest Ruby-based VIM plug-ins to date.
+While the Command-T codebase doesn't contain any code directly copied from
+LustyExplorer, I did use it as a reference for answers to basic questions (like
+"How do you do 'X' in a Ruby-based VIM plug-in?"), and also copied some basic
+architectural decisions (like the division of the code into Prompt, Settings
+and MatchWindow classes).
+LustyExplorer is available from:
+The official website for Command-T is:
+The latest release will always be available from there.
+Development in progress can be inspected via the project's Git repository
+A copy of each release is also available from the official VIM scripts site
+Bug reports should be submitted to the issue tracker at:
+Command-T itself is free software released under the terms of the BSD license.
+If you would like to support further development you can make a donation via
+PayPal to email@example.com:
+Copyright 2010 Wincent Colaiuta. All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+- |:CommandT| now accepts an optional parameter to specify the starting
+ directory, temporarily overriding the usual default of VIM's |:pwd|
+- fix truncated paths when operating from root directory
+- fix for Ruby 1.9 compatibility regression introduced in 0.5
+- documentation enhancements, specifically targetted at Windows users
+- |:CommandTFlush| now re-evaluates settings, allowing changes made via |let|
+ to be picked up without having to restart VIM
+- fix premature abort when scanning very deep directory hierarchies
+- remove broken |<Esc>| key mapping on vt100 and xterm terminals
+- provide settings for overriding default mappings
+- minor performance optimization
+- add |g:CommandTMatchWindowAtTop| setting (patch from Zak Johnson)
+- documentation fixes and enhancements
+- internal refactoring and simplification
+- add |g:CommandTMaxHeight| setting for controlling the maximum height of the
+ match window (patch from Lucas de Vries)
+- fix bug where |'list'| setting might be inappropriately set after dismissing
+- compatibility fix for different behaviour of "autoload" under Ruby 1.9.1
+- avoid "highlight group not found" warning when run under a version of VIM
+ that does not have syntax highlighting support
+- open in split when opening normally would fail due to |'hidden'| and
+- compatibility fixes for compilation under Ruby 1.9 series
+- compatibility fixes for compilation under Ruby 1.8.5
+- compatibility fixes for Windows and other non-UNIX platforms
+- suppress "mapping already exists" message if <Leader>t mapping is already
+ defined when plug-in is loaded
+- exclude paths based on |'wildignore'| setting rather than a hardcoded
+- initial public release