command-t 1.9.1 → 1.10

data/doc/command-t.txt

@@ -5,7 +5,6 @@ CONTENTS                                        *command-t-contents*
  1. Introduction            |command-t-intro|
  2. Requirements            |command-t-requirements|
  3. Installation            |command-t-installation|
- 3. Managing using Pathogen |command-t-pathogen|
  4. Trouble-shooting        |command-t-trouble-shooting|
  5. Usage                   |command-t-usage|
  6. Commands                |command-t-commands|
@@ -16,9 +15,8 @@ CONTENTS                                        *command-t-contents*
 11. Authors                 |command-t-authors|
 12. Development             |command-t-development|
 13. Website                 |command-t-website|
-14. Donations               |command-t-donations|
-15. License                 |command-t-license|
-16. History                 |command-t-history|
+14. License                 |command-t-license|
+15. History                 |command-t-history|
 
 
 INTRODUCTION                                    *command-t-intro*
@@ -94,11 +92,15 @@ On OS X Snow Leopard, Lion and Mountain Lion, the system comes with Ruby 1.8.7
 and all recent versions of MacVim (the 7.2 snapshots and 7.3) are linked
 against it.
 
-On OS X Mavericks, the default system ruby is 2.0, but MacVim continues to
-link against 1.8.7, which is also present on the system at:
+On OS X Mavericks, the default system Ruby is 2.0, but MacVim continues to
+link against 1.8.7, as does the Apple-provided Vim. Ruby 1.8.7 is present on
+the system at:
 
   /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby
 
+On OS X Yosemite, the default system Ruby is 2.0, and the Vim that comes with
+the system links against it.
+
 On Linux and similar platforms, the linked version of Ruby will depend on
 your distribution. You can usually find this out by examining the
 compilation and linking flags displayed by the |:version| command in Vim, and
@@ -140,26 +142,128 @@ folder.
 
 INSTALLATION                                    *command-t-installation*
 
-You can install Command-T by obtaining the source files and building the C
-extension. The recommended way to get the source is by using a plug-in
-management system such as Pathogen (see |command-t-pathogen|).
+You install Command-T by obtaining the source files and building the C
+extension.
+
+The recommended way to get the source is by using a plug-in management system.
+There are several such systems available, and my preferred one is Pathogen
+(https://github.com/tpope/vim-pathogen) due to its simplicity and robustness.
+
+Other plug-in managers include:
+
+- Vundle: https://github.com/gmarik/Vundle.vim (see |command-t-vundle|)
+- NeoBundle: https://github.com/Shougo/neobundle.vim (see
+  |command-t-neobundle|)
+- VAM: https://github.com/MarcWeber/vim-addon-manager (see |command-t-vam|)
+
+The following sections outline how to use each of these managers to download
+Command-T, and finally |command-t-compile| describes how to compile it.
+
+                                                         *command-t-pathogen*
+Obtaining the source using Pathogen ~
+
+Pathogen is a plugin that allows you to maintain plugin installations in
+separate, isolated subdirectories under the "bundle" directory in your
+|'runtimepath'|. The following examples assume that you already have
+Pathogen installed and configured, and that you are installing into
+`~/.vim/bundle`.
+
+If you manage your entire `~/.vim` folder using Git then you can add the
+Command-T repository as a submodule:
+
+  cd ~/.vim
+  git submodule add git://git.wincent.com/command-t.git bundle/command-t
+  git submodule init
 
-Command-T is also distributed as a "vimball" which means that it can be
-installed by opening it in Vim and then sourcing it:
+Or if you just wish to do a simple clone instead of using submodules:
 
-  :e command-t.vba
-  :so %
+  cd ~/.vim
+  git clone git://git.wincent.com/command-t.git bundle/command-t
 
-The files will be installed in your |'runtimepath'|. To check where this is
-you can issue:
+Once you have a local copy of the repository you can update it at any time
+with:
 
-  :echo &rtp
+  cd ~/.vim/bundle/command-t
+  git pull
 
-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:
+Or you can switch to a specific release with:
 
-  cd ~/.vim/ruby/command-t
+  cd ~/.vim/bundle/command-t
+  git checkout 1.10
+
+To generate the help tags under Pathogen it is necessary to do so explicitly
+from inside Vim:
+
+  :call pathogen#helptags()
+
+For more information about Pathogen, see:
+
+  https://github.com/tpope/vim-pathogen
+
+                                                           *command-t-vundle*
+Obtaining the source using Vundle ~
+
+Anywhere between the calls to `vundle#begin` and `vundle#end` in your
+`~/.vimrc`, add a `Plugin` directive telling Vundle of your desire to use
+Command-T:
+
+  call vundle#begin()
+  Plugin 'wincent/command-t'
+  call vundle#end()
+
+To actually install the plug-in run `:PluginInstall` from inside Vim. After
+this, you can proceed to compile Command-T (see |command-t-compile|).
+
+For more information about Vundle, see:
+
+  https://github.com/gmarik/Vundle.vim
+
+                                                        *command-t-neobundle*
+Obtaining the source using NeoBundle ~
+
+Anywhere between the calls to `neobundle#begin` and `neobundle#end` in your
+`~/.vimrc`, add a `NeoBundle` directive telling NeoBundle of your desire to use
+Command-T:
+
+  call neobundle#begin(expand('~/.vim/bundle/'))
+  NeoBundle 'wincent/command-t'
+  call neobundle#end()
+
+To actually install the plug-in run `:NeoBundleInstall` from inside Vim. After
+this, you can proceed to compile Command-T (see |command-t-compile|).
+
+For more information about NeoBundle, see:
+
+  https://github.com/Shougo/neobundle.vim
+                                                              *command-t-vam*
+Obtaining the source using VAM ~
+
+After the call to `vam#ActivateAddons` in your `~/.vimrc`, add Command-T to
+the `VAMActivate` call:
+
+  call vam#ActivateAddons([])
+  VAMActivate github:wincent/command-t
+
+After VAM has downloaded Command-T, you can proceed to compile it (see
+|command-t-compile|).
+
+For more information about VAM, see:
+
+  https://github.com/MarcWeber/vim-addon-manager
+
+                                                         *command-t-compile*
+Compiling Command-T ~
+
+The C extension must be built, which can be done from the shell. If you use a
+typical Pathogen, Vundle or NeoBundle set-up then the files were installed inside
+`~/.vim/bundle/command-t`. A typical VAM installation path might be
+`~/.vim/vim-addons/command-t`.
+
+Wherever the Command-T files were installed, you can build the extension by
+changing to the `ruby/command-t` subdirectory and running a couple of commands
+as follows:
+
+  cd ~/.vim/bundle/command-t/ruby/command-t
   ruby extconf.rb
   make
 
@@ -175,7 +279,7 @@ Note: If you are on OS X Mavericks and compiling against MacVim, the default
 system Ruby is 2.0 but MacVim still links against the older 1.8.7 Ruby that is
 also bundled with the system; in this case the build command becomes:
 
-  cd ~/.vim/ruby/command-t
+  cd ~/.vim/bundle/command-t/ruby/command-t
   /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/ruby extconf.rb
   make
 
@@ -198,50 +302,6 @@ repository with:
 
   su -c 'yum install vim-command-t'
 
-MANAGING USING PATHOGEN                         *command-t-pathogen*
-
-Pathogen is a plugin that allows you to maintain plugin installations in
-separate, isolated subdirectories under the "bundle" directory in your
-|'runtimepath'|. The following examples assume that you already have
-Pathogen installed and configured, and that you are installing into
-~/.vim/bundle. For more information about Pathogen, see:
-
-  http://www.vim.org/scripts/script.php?script_id=2332
-
-If you manage your entire ~/.vim folder using Git then you can add the
-Command-T repository as a submodule:
-
-  cd ~/.vim
-  git submodule add git://git.wincent.com/command-t.git bundle/command-t
-  git submodule init
-
-Or if you just wish to do a simple clone instead of using submodules:
-
-  cd ~/.vim
-  git clone git://git.wincent.com/command-t.git bundle/command-t
-
-Once you have a local copy of the repository you can update it at any time
-with:
-
-  cd ~/.vim/bundle/command-t
-  git pull
-
-Or you can switch to a specific release with:
-
-  cd ~/.vim/bundle/command-t
-  git checkout 0.8b
-
-After installing or updating you must build the extension:
-
-  cd ~/.vim/bundle/command-t/ruby/command-t
-  ruby extconf.rb
-  make
-
-While the Vimball installation automatically generates the help tags, under
-Pathogen it is necessary to do so explicitly from inside Vim:
-
-  :call pathogen#helptags()
-
 
 TROUBLE-SHOOTING                                *command-t-trouble-shooting*
 
@@ -358,7 +418,7 @@ The following is also available on terminals which support it:
     <Esc>       cancel (dismisses file 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).
+`~/.vimrc` file (see the OPTIONS section for a full list of available options).
 
 In addition, when the file listing has focus, typing a character will cause
 the selection to jump to the first path which begins with that character.
@@ -424,7 +484,7 @@ By default Command-T comes with only two mappings:
   <Leader>b     bring up the Command-T buffer window
 
 However, Command-T won't overwrite a pre-existing mapping so if you prefer
-to define different mappings use lines like these in your ~/.vimrc:
+to define different mappings use lines like these in your `~/.vimrc`:
 
   nnoremap <silent> <Leader>t :CommandT<CR>
   nnoremap <silent> <Leader>b :CommandTBuffer<CR>
@@ -432,7 +492,7 @@ to define different mappings use lines like these in your ~/.vimrc:
 Replacing "<Leader>t" or "<Leader>b" 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
+as <D-t> in Vim) in your `~/.gvimrc` file if you first unmap the existing menu
 binding of Command-T to "New Tab":
 
   if has("gui_macvim")
@@ -448,8 +508,8 @@ overriding the mappings are listed below under OPTIONS.
 
 OPTIONS                                         *command-t-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:
+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
 
@@ -566,7 +626,7 @@ Following is a list of all available options:
       |g:CommandTScanDotDirectories| affects the behaviour at scan-time.
 
       Note also that even with this setting off you can still use Command-T to
-      open files inside a "dot-directory" such as ~/.vim, but you have to use
+      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:
 
         :cd ~/.vim
@@ -615,10 +675,78 @@ Following is a list of all available options:
 
       See also |command-t-wildignore|.
 
+                                                *g:CommandTIgnoreCase*
+  |g:CommandTIgnoreCase|                          boolean (default: 1)
+
+      Ignore case when searching. Defaults to on, which means that searching
+      is case-insensitive by default. See also |g:CommandTSmartCase|.
+
+                                                *g:CommandTSmartCase*
+  |g:CommandTSmartCase|                           boolean (default: none)
+
+      Override the |g:CommandTIgnoreCase| setting if the search pattern
+      contains uppercase characters, forcing the match to be case-sensitive.
+      If unset (which is the default), the value of the Vim |'smartcase'|
+      setting will be used instead.
+
+                                              *g:CommandTAcceptSelectionCommand*
+  |g:CommandTAcceptSelectionCommand|            string (default: 'e')
+
+      The Vim command that will be used to open a selection from the match
+      listing (via |g:CommandTAcceptSelectionMap|).
+
+      For an example of how this can be used to apply arbitrarily complex
+      logic, see the example in |g:CommandTAcceptSelectionTabCommand| below.
+
+                                           *g:CommandTAcceptSelectionTabCommand*
+  |g:CommandTAcceptSelectionTabCommand|      string (default: 'tabe')
+
+      The Vim command that will be used to open a selection from the match
+      listing in a new tab (via |g:CommandTAcceptSelectionSplitMap|).
+
+      For example, this can be used to switch to an existing buffer (rather
+      than opening a duplicate buffer with the selection in a new tab) with
+      configuration such as the following:
+
+          set switchbuf=usetab
+
+          function! GotoOrOpen(...)
+            for file in a:000
+              if bufexists(file)
+                exec "sb " . file
+              else
+                exec "tabe " . file
+              endif
+            endfor
+          endfunction
+
+          command! -nargs=+ GotoOrOpen call GotoOrOpen("<args>")
+
+          let g:CommandTAcceptSelectionTabCommand = 'GotoOrOpen'
+
+                                        *g:CommandTAcceptSelectionSplitCommand*
+  |g:CommandTAcceptSelectionSplitCommand| string (default: 'sp')
+
+      The Vim command that will be used to open a selection from the match
+      listing in a split (via |g:CommandTAcceptSelectionVSplitMap|).
+
+      For an example of how this can be used to apply arbitrarily complex
+      logic, see the example in |g:CommandTAcceptSelectionTabCommand| above.
+
+                                        *g:CommandTAcceptSelectionVsplitCommand*
+                                        string (default: 'vs')
+  |g:CommandTAcceptSelectionVSplitCommand|
+
+      The Vim command that will be used to open a selection from the match
+      listing in a vertical split (via |g:CommandTAcceptSelectionVSplitMap|).
+
+      For an example of how this can be used to apply arbitrarily complex
+      logic, see the example in |g:CommandTAcceptSelectionTabCommand| above.
+
 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:
+window, you would add the following to your `~/.vimrc`:
 
   let g:CommandTCancelMap='<C-x>'
 
@@ -669,6 +797,9 @@ Following is a list of all map settings and their defaults:
                                       *g:CommandTClearMap*
                   |g:CommandTClearMap|  <C-u>
 
+                                      *g:CommandTClearPrevWordMap*
+          |g:CommandTClearPrevWordMap|  <C-w>
+
                                       *g:CommandTRefreshMap*
                 |g:CommandTRefreshMap|  <C-f>
 
@@ -758,7 +889,7 @@ Why doesn't the Escape key close the match listing in terminal Vim? ~
 
 In some terminals such as xterm the Escape key misbehaves, so Command-T
 doesn't set up a mapping for it. If you want to try using the escape key
-anyway, you can add something like the following to your ~/.vimrc file:
+anyway, you can add something like the following to your `~/.vimrc` file:
 
   if &term =~ "xterm" || &term =~ "screen"
     let g:CommandTCancelMap = ['<ESC>', '<C-c>']
@@ -871,7 +1002,8 @@ kind of ongoing calibration will come quite naturally.
 Finally, it is important to be on a relatively recent version of Command-T to
 fully benefit from the available performance enhancements:
 
-- version 1.8 (March 2013) sped up the Watchman file scanner by switching its
+- version 1.9 (May 2014) tweaked memoization algorithm for a 10% speed boost
+- version 1.8 (March 2014) sped up the Watchman file scanner by switching its
   communication from the JSON to the binary Watchman protocol
 - version 1.7 (February 2014) added the |g:CommandTInputDebounce| and
   |g:CommandTFileScanner| settings, along with support for the Watchman file
@@ -884,22 +1016,23 @@ fully benefit from the available performance enhancements:
 
 AUTHORS                                         *command-t-authors*
 
-Command-T is written and maintained by Wincent Colaiuta <win@wincent.com>.
+Command-T is written and maintained by Greg Hurrell <greg@hurrell.net>.
 Other contributors that have submitted patches include (in alphabetical
 order):
 
-  Andy Waite              Nadav Samet             Steven Moazami
-  Anthony Panozzo         Nate Kane               Sung Pae
-  Daniel Hahler           Nicholas Alpi           Thomas Pelletier
-  Felix Tjandrawibawa     Noon Silk               Ton van den Heuvel
-  Gary Bernhardt          Paul Jolly              Victor Hugo Borja
-  Ivan Ukhov              Pavel Sergeev           Vít Ondruch
-  Jeff Kreeftmeijer       Rainux Luo              Woody Peterson
-  Lucas de Vries          Roland Puntaier         Yan Pritzker
-  Marcus Brito            Ross Lagerwall          Yiding Jia
-  Marian Schubert         Scott Bronson           Zak Johnson
-  Matthew Todd            Seth Fowler
-  Mike Lundy              Shlomi Fish
+  Andy Waite              Matthew Todd            Seth Fowler
+  Anthony Panozzo         Mike Lundy              Shlomi Fish
+  Artem Nezvigin          Nadav Samet             Steven Moazami
+  Daniel Hahler           Nate Kane               Sung Pae
+  Felix Tjandrawibawa     Nicholas Alpi           Thomas Pelletier
+  Gary Bernhardt          Noon Silk               Ton van den Heuvel
+  Ivan Ukhov              Ole Petter Bang         Victor Hugo Borja
+  Jacek Wysocki           Paul Jolly              Vít Ondruch
+  Jeff Kreeftmeijer       Pavel Sergeev           Woody Peterson
+  Kevin Webster           Rainux Luo              Yan Pritzker
+  Lucas de Vries          Roland Puntaier         Yiding Jia
+  Marcus Brito            Ross Lagerwall          Zak Johnson
+  Marian Schubert         Scott Bronson
 
 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
@@ -936,10 +1069,10 @@ per hour from the authoritative repository:
 Patches are welcome via the usual mechanisms (pull requests, email, posting to
 the project issue tracker etc).
 
-As many users choose to track Command-T using Pathogen, which often means
-running a version later than the last official release, the intention is that
-the "master" branch should be kept in a stable and reliable state as much as
-possible.
+As many users choose to track Command-T using Pathogen or similar, which often
+means running a version later than the last official release, the intention is
+that the "master" branch should be kept in a stable and reliable state as much
+as possible.
 
 Riskier changes are first cooked on the "next" branch for a period before
 being merged into master. You can track this branch if you're feeling wild and
@@ -966,18 +1099,9 @@ Bug reports should be submitted to the issue tracker at:
   https://wincent.com/issues
 
 
-DONATIONS                                       *command-t-donations*
-
-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 win@wincent.com:
-
-  https://wincent.com/products/command-t/donations
-
-
 LICENSE                                         *command-t-license*
 
-Copyright 2010-2014 Wincent Colaiuta. All rights reserved.
+Copyright 2010-2014 Greg Hurrell. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -1002,6 +1126,22 @@ POSSIBILITY OF SUCH DAMAGE.
 
 HISTORY                                         *command-t-history*
 
+1.10 (15 July 2014)
+
+- improve tag finder performance by caching tag lists (patch from Artem
+  Nezvigin)
+- consider the |'autowriteall'| option when deciding whether to open a file in
+  a split
+- make selection acceptance commands configurable (patch from Ole Petter Bang)
+- add <C-w> mapping to delete previous word of the match prompt (patch from
+  Kevin Webster)
+- try harder to always clear status line after closing the match listing
+  (patch from Ton van den Heuvel)
+- don't allow MRU autocommands to produce errors when the extension has not
+  been compiled
+- add |g:CommandTIgnoreCase| and |g:CommandTSmartCase| options, providing
+  support for case-sensitive matching (based on patch from Jacek Wysocki)
+
 1.9.1 (30 May 2014)
 
 - include the file in the release vimball archive that was missing from the