command-t 1.13 → 2.0

data/doc/command-t.txt

@@ -2,21 +2,22 @@
 
 CONTENTS                                        *command-t-contents*
 
- 1. Introduction            |command-t-intro|
- 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. FAQ                     |command-t-faq|
-10. Tips                    |command-t-tips|
-11. Authors                 |command-t-authors|
-12. Development             |command-t-development|
-13. Website                 |command-t-website|
-14. License                 |command-t-license|
-15. History                 |command-t-history|
+ 1. Introduction                    |command-t-intro|
+ 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. Integration and Extensibility   |command-t-integration-and-extensibility|
+10. FAQ                             |command-t-faq|
+11. Tips                            |command-t-tips|
+12. Authors                         |command-t-authors|
+13. Development                     |command-t-development|
+14. Website                         |command-t-website|
+15. License                         |command-t-license|
+16. History                         |command-t-history|
 
 
 INTRODUCTION                                    *command-t-intro*
@@ -213,7 +214,7 @@ For more information about Pathogen, see:
 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
+|.vimrc|, add a `Plugin` directive telling Vundle of your desire to use
 Command-T:
 
   call vundle#begin()
@@ -231,7 +232,7 @@ For more information about Vundle, see:
 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
+|.vimrc|, add a `NeoBundle` directive telling NeoBundle of your desire to use
 Command-T:
 
   call neobundle#begin(expand('~/.vim/bundle/'))
@@ -247,7 +248,7 @@ For more information about NeoBundle, see:
                                                               *command-t-vam*
 Obtaining the source using VAM ~
 
-After the call to `vam#ActivateAddons` in your `~/.vimrc`, add Command-T to
+After the call to `vam#ActivateAddons` in your |.vimrc|, add Command-T to
 the `VAMActivate` call:
 
   call vam#ActivateAddons([])
@@ -483,7 +484,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.
@@ -550,26 +551,36 @@ COMMANDS                                        *command-t-commands*
 
 MAPPINGS                                        *command-t-mappings*
 
-By default Command-T comes with only two mappings:
+By default Command-T comes with only three mappings:
 
-  <Leader>t     bring up the Command-T file window
-  <Leader>b     bring up the Command-T buffer window
+                                                *<Plug>(CommandT)*
 
-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`:
+<Leader>t       bring up the Command-T file window
 
-  nnoremap <silent> <Leader>t :CommandT<CR>
-  nnoremap <silent> <Leader>b :CommandTBuffer<CR>
+                                                *<Plug>(CommandTBuffer)*
 
-Replacing "<Leader>t" or "<Leader>b" with your mapping of choice.
+<Leader>b       bring up the Command-T buffer window
+
+                                                *<Plug>(CommandTJump)*
+
+<Leader>j       bring up the Command-T jumplist window
+
+Note that Command-T won't overwrite a pre-existing mapping so if you prefer
+to define different mappings use lines like these in your |.vimrc|:
+
+  nnoremap <silent> <Leader>t <Plug>(CommandT)
+  nnoremap <silent> <Leader>b <Plug>(CommandTBuffer)
+  nnoremap <silent> <Leader>j <Plug>(CommandTJump)
+
+Replacing "<Leader>t", "<Leader>b" or "<Leader>j" 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")
     macmenu &File.New\ Tab key=<nop>
-    map <D-t> :CommandT<CR>
+    map <D-t> <Plug>(CommandT)
   endif
 
 When the Command-T window is active a number of other additional mappings
@@ -580,8 +591,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
 
@@ -769,10 +780,17 @@ Following is a list of all available options:
       When this setting is off (the default) the matches in the |:CommandTTag|
       listing do not include filenames.
 
+                                                *g:CommandTCursorColor*
+                                                string (default: 'Underlined')
+  |g:CommandTCursorColor|
+
+      Specifies the |:highlight| color that will be applied to the cursor in
+      the Command-T prompt.
+
                                                 *g:CommandTHighlightColor*
   |g:CommandTHighlightColor|                      string (default: 'PmenuSel')
 
-      Specifies the highlight color that will be used to show the currently
+      Specifies the |:highlight| color that will be used to show the currently
       selected item in the match listing window.
 
                                                 *g:CommandTWildIgnore*
@@ -792,6 +810,14 @@ Following is a list of all available options:
       Ignore case when searching. Defaults to on, which means that searching
       is case-insensitive by default. See also |g:CommandTSmartCase|.
 
+                                                *g:CommandTRecursiveMatch*
+  |g:CommandTRecursiveMatch|                      boolean (default: 1)
+
+      Use this to downgrade Command-T's match-scoring algorithm to its older,
+      non-recursive form. Doing so may improve the responsiveness of the match
+      listing, but at the cost of slightly less precision in the ranking of
+      results.
+
                                                 *g:CommandTSmartCase*
   |g:CommandTSmartCase|                           boolean (default: none)
 
@@ -865,10 +891,17 @@ Following is a list of all available options:
       environment ends up defaulting to an undesired encoding, such as
       "ASCII-8BIT".
 
+                                              *g:CommandTIgnoreSpaces*
+  |g:CommandTIgnoreSpaces|                      boolean (default: 0)
+
+      When typing a search term into Command-T, use this option to have it
+      ignore spaces. Without this option set, it will search for literal
+      spaces inside file names.
+
 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>'
 
@@ -992,6 +1025,53 @@ settings can be used to control behavior:
         'wildignore' at all.
 
 
+INTEGRATION AND EXTENSIBILITY         *command-t-integration-and-extensibility*
+
+For the purposes of integrating with other plug-ins, or otherwise extending
+Command-T's functionality, a number of hooks and features are provided. Note
+that making use of any of these extension points is considered to be advanced
+configuration, and the more invasive the modifications, the greater the risk
+that they will interact poorly with future versions of Command-T. Proceed with
+caution.
+
+                                                *command-t-filetype*
+command-t filetype ~
+
+Command-T displays its match listing using a special Vim buffer with a
+filetype of  `command-t`. This can be used in |ftplugins| or elsewhere to set up
+an |autocommand| or apply custom configuration.
+
+For example of an |ftplugin| that sets a custom 'statusline' for the
+Command-T match listing buffer, see: https://wt.pe/f
+
+                                                *command-t-load*
+                                                *commandt#Load*
+Eager loading with commandt#CommandTLoad ~
+
+In order to minimize Vim startup time, most of Command-T's functionality is
+only loaded on first use, via Vim's |autoload| mechanism.
+
+If you should wish to monkey patch some Command-T functionality, the
+`commandt#Load()` function (also exposed via the |:CommandTLoad| command) is
+provided as a means of eager-loading Command-T's code, so that you can go
+ahead and patch it.
+
+                                                *commandt#ActiveFinder*
+                                                *commandt#CheckBuffer*
+                                                *commandt#Path*
+Statusline hooks ~
+
+A number of methods are provided that may be useful for creating a
+context-sensitive 'statusline'.
+
+- `commandt#ActiveFinder()`: Returns the class name of the currently
+  active finder.
+- `commandt#Path()`: Returns the path that Command-T is currently
+  searching.
+- `commandt#CheckBuffer()`: Takes a buffer number and returns true if
+  it is the Command-T match listing buffer.
+
+
 FAQ                                             *command-t-faq*
 
 Why does my build fail with "unknown argument -multiply_definedsuppress"? ~
@@ -1035,7 +1115,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>']
@@ -1119,17 +1199,25 @@ anchored at the root level of your repository in any case.
 Command-T will internally cache up to 10 different directories, so even if you
 |cd| repeatedly, it should only need to scan each directory once.
 
+It's advisable to keep a long-running Vim instance in place and let it cache
+the directory listings rather than repeatedly closing and re-opening Vim in
+order to edit every file. On those occasions when you do need to flush the
+cache (ie. with |CommandTFlush| or <C-f> in the match listing window), use of
+the Watchman scanner should make the delay barely noticeable.
+
     let g:CommandTSmartCase = 1
 
 Makes Command-T perform case-sensitive matching whenever the search pattern
 includes an uppercase letter. This allows you to narrow the search results
 listing with fewer keystrokes. See also |g:CommandTIgnoreCase|.
 
-It's advisable to keep a long-running Vim instance in place and let it cache
-the directory listings rather than repeatedly closing and re-opening Vim in
-order to edit every file. On those occasions when you do need to flush the
-cache (ie. with |CommandTFlush| or <C-f> in the match listing window), use of
-the Watchman scanner should make the delay barely noticeable.
+    let g:CommandTRecursiveMatch = 0
+
+This one is a little more subjective. You may want to turn off Command-T's
+recursive match-scoring algorithm to save some cycles. This finds matches more
+quickly at the possible cost of ranking them slightly less precisely. Whether
+applying this setting helps or hurts you in a very large repo is probably
+repo-dependent.
 
 As noted in the introduction, Command-T works best when you adopt a
 "path-centric" mentality. This is especially true on very large hierarchies.
@@ -1154,6 +1242,7 @@ 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 2.0a (not yet released) added the |g:CommandTRecursiveMatch| option
 - version 1.10 (July 2014) added the |g:CommandTIgnoreCase| and
   |g:CommandTSmartCase| options
 - version 1.9 (May 2014) tweaked memoization algorithm for a 10% speed boost
@@ -1174,31 +1263,32 @@ Command-T is written and maintained by Greg Hurrell <greg@hurrell.net>.
 Other contributors that have submitted patches include (in alphabetical
 order):
 
-  Abhinav Gupta                   Noon Silk
-  Aleksandrs Ļedovskis            Ole Petter Bang
-  Andy Waite                      Patrick Hayes
-  Anthony Panozzo                 Paul Jolly
-  Artem Nezvigin                  Pavel Sergeev
-  Ben Boeckel                     Rainux Luo
-  Ben Osheroff                    Richard Feldman
-  Daniel Hahler                   Roland Puntaier
-  David Szotten                   Ross Lagerwall
-  Emily Strickland                Scott Bronson
-  Felix Tjandrawibawa             Seth Fowler
-  Gary Bernhardt                  Sherzod Gapirov
-  Ivan Ukhov                      Shlomi Fish
-  Jacek Wysocki                   Steven Moazami
-  Jeff Kreeftmeijer               Sung Pae
-  Kevin Webster                   Thomas Pelletier
-  Lucas de Vries                  Ton van den Heuvel
-  Marcus Brito                    Victor Hugo Borja
-  Marian Schubert                 Vlad Seghete
-  Matthew Todd                    Vít Ondruch
-  Mike Lundy                      Woody Peterson
-  Nadav Samet                     Yan Pritzker
-  Nate Kane                       Yiding Jia
-  Nicholas Alpi                   Zak Johnson
-  Nikolai Aleksandrovich Pavlov
+  Abhinav Gupta                   Nikolai Aleksandrovich Pavlov
+  Aleksandrs Ļedovskis            Noon Silk
+  Andy Waite                      Ole Petter Bang
+  Anthony Panozzo                 Patrick Hayes
+  Artem Nezvigin                  Paul Jolly
+  Ben Boeckel                     Pavel Sergeev
+  Ben Osheroff                    Rainux Luo
+  Daniel Hahler                   Richard Feldman
+  David Szotten                   Roland Puntaier
+  Emily Strickland                Ross Lagerwall
+  Felix Tjandrawibawa             Scott Bronson
+  Gary Bernhardt                  Seth Fowler
+  Ivan Ukhov                      Sherzod Gapirov
+  Jacek Wysocki                   Shlomi Fish
+  Jeff Kreeftmeijer               Steven Moazami
+  Jerome Castaneda                Sung Pae
+  KJ Tsanaktsidis                 Thomas Pelletier
+  Kevin Webster                   Ton van den Heuvel
+  Lucas de Vries                  Victor Hugo Borja
+  Marcus Brito                    Vlad Seghete
+  Marian Schubert                 Vít Ondruch
+  Matthew Todd                    Woody Peterson
+  Mike Lundy                      Yan Pritzker
+  Nadav Samet                     Yiding Jia
+  Nate Kane                       Zak Johnson
+  Nicholas Alpi
 
 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
@@ -1266,7 +1356,7 @@ Bug reports should be submitted to the issue tracker at:
 
 LICENSE                                         *command-t-license*
 
-Copyright 2010-2015 Greg Hurrell. All rights reserved.
+Copyright 2010-present 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:
@@ -1291,6 +1381,58 @@ POSSIBILITY OF SUCH DAMAGE.
 
 HISTORY                                         *command-t-history*
 
+2.0 (28 December 2015)
+
+- add |:CommandTIgnoreSpaces| option (patch from KJ Tsanaktsidis)
+- make Command-T resilient to people deleting its hidden, unlisted buffer
+- the match listing buffer now has filetype "command-t", which may be useful
+  for detectability/extensibility
+- Command-T now sets the name of the match listing buffer according to how it
+  was invoked (ie. for the file finder, the name is "Command-T [Files]", for
+  the buffer finder, the name is "Command-T [Buffers]", and so on);
+  previously the name was a fixed as "GoToFile" regardless of the active
+  finder type
+- Many internal function names have changed, so if you or your plug-ins are
+  calling those internals they will need to be updated:
+  - `commandt#CommandTFlush()` is now `commandt#Flush()`
+  - `commandt#CommandTLoad()` is now `commandt#Load()`
+  - `commandt#CommandTShowBufferFinder()` is now `commandt#BufferFinder()`
+  - `commandt#CommandTShowFileFinder()` is now `commandt#FileFinder()`
+  - `commandt#CommandTShowJumpFinder()` is now `commandt#JumpFinder()`
+  - `commandt#CommandTShowMRUFinder()` is now `commandt#MRUFinder()`
+  - `commandt#CommandTShowTagFinder()` is now `commandt#TagFinder()`
+- A number of functions have been turned into "private" autoloaded functions,
+  to make it clear that they are intended only for internal use:
+  - `CommandTAcceptSelection()` is now `commandt#private#AcceptSelection()`
+  - `CommandTAcceptSelectionSplit()` is now `commandt#private#AcceptSelectionSplit()`
+  - `CommandTAcceptSelectionTab()` is now `commandt#private#AcceptSelectionTab()`
+  - `CommandTAcceptSelectionVSplit()` is now `commandt#private#AcceptSelectionVSplit()`
+  - `CommandTBackspace()` is now `commandt#private#Backspace()`
+  - `CommandTCancel()` is now `commandt#private#Cancel()`
+  - `CommandTClear()` is now `commandt#private#Clear()`
+  - `CommandTClearPrevWord()` is now `commandt#private#ClearPrevWord()`
+  - `CommandTCursorEnd()` is now `commandt#private#CursorEnd()`
+  - `CommandTCursorLeft()` is now `commandt#private#CursorLeft()`
+  - `CommandTCursorRight()` is now `commandt#private#CursorRight()`
+  - `CommandTCursorStart()` is now `commandt#private#CursorStart()`
+  - `CommandTDelete()` is now `commandt#private#Delete()`
+  - `CommandTHandleKey()` is now `commandt#private#HandleKey()`
+  - `CommandTListMatches()` is now `commandt#private#ListMatches()`
+  - `CommandTQuickfix()` is now `commandt#private#Quickfix()`
+  - `CommandTRefresh()` is now `commandt#private#Refresh()`
+  - `CommandTSelectNext()` is now `commandt#private#SelectNext()`
+  - `CommandTSelectPrev()` is now `commandt#private#SelectPrev()`
+  - `CommandTToggleFocus()` is now `commandt#private#ToggleFocus()`
+- add |g:CommandTRecursiveMatch| option
+- stop distribution as a vimball in favor of a zip archive
+- don't clobber |alternate-file| name when opening Command-T match listing
+  (patch from Jerome Castaneda)
+- add |g:CommandTCursorColor| option
+- expose mappings for |:CommandT| and |:CommandTBuffer| using `<Plug>`
+  mappings |<Plug>(CommandT)| and |<Plug>(CommandT)|
+- add `<Leader>j` mapping to |:CommandTJump|, via |<Plug>(CommandTJump)|
+  (defined only if no pre-existing mapping exists)
+
 1.13 (29 April 2015)
 
 - avoid "W10: Warning: Changing a readonly file" when starting Vim in
@@ -1372,7 +1514,7 @@ HISTORY                                         *command-t-history*
 
 1.9.1 (30 May 2014)
 
-- include the file in the release vimball archive that was missing from the
+- include the file in the release archive that was missing from the
   1.9 release
 
 1.9 (25 May 2014)
@@ -1591,4 +1733,4 @@ HISTORY                                         *command-t-history*
 - initial public release
 
 ------------------------------------------------------------------------------
-vim:tw=78:ft=help:
+vim:ts=8:tw=78:ft=help:

data/doc/tags

@@ -13,10 +13,13 @@ command-t-compile	command-t.txt	/*command-t-compile*
 command-t-contents	command-t.txt	/*command-t-contents*
 command-t-development	command-t.txt	/*command-t-development*
 command-t-faq	command-t.txt	/*command-t-faq*
+command-t-filetype	command-t.txt	/*command-t-filetype*
 command-t-history	command-t.txt	/*command-t-history*
 command-t-installation	command-t.txt	/*command-t-installation*
+command-t-integration-and-extensibility	command-t.txt	/*command-t-integration-and-extensibility*
 command-t-intro	command-t.txt	/*command-t-intro*
 command-t-license	command-t.txt	/*command-t-license*
+command-t-load	command-t.txt	/*command-t-load*
 command-t-mappings	command-t.txt	/*command-t-mappings*
 command-t-neobundle	command-t.txt	/*command-t-neobundle*
 command-t-options	command-t.txt	/*command-t-options*
@@ -30,6 +33,10 @@ command-t-vundle	command-t.txt	/*command-t-vundle*
 command-t-website	command-t.txt	/*command-t-website*
 command-t-wildignore	command-t.txt	/*command-t-wildignore*
 command-t.txt	command-t.txt	/*command-t.txt*
+commandt#ActiveFinder	command-t.txt	/*commandt#ActiveFinder*
+commandt#CheckBuffer	command-t.txt	/*commandt#CheckBuffer*
+commandt#Load	command-t.txt	/*commandt#Load*
+commandt#Path	command-t.txt	/*commandt#Path*
 g:CommandTAcceptSelectionCommand	command-t.txt	/*g:CommandTAcceptSelectionCommand*
 g:CommandTAcceptSelectionMap	command-t.txt	/*g:CommandTAcceptSelectionMap*
 g:CommandTAcceptSelectionSplitCommand	command-t.txt	/*g:CommandTAcceptSelectionSplitCommand*
@@ -53,6 +60,7 @@ g:CommandTFileScanner	command-t.txt	/*g:CommandTFileScanner*
 g:CommandTGitScanSubmodules	command-t.txt	/*g:CommandTGitScanSubmodules*
 g:CommandTHighlightColor	command-t.txt	/*g:CommandTHighlightColor*
 g:CommandTIgnoreCase	command-t.txt	/*g:CommandTIgnoreCase*
+g:CommandTIgnoreSpaces	command-t.txt	/*g:CommandTIgnoreSpaces*
 g:CommandTInputDebounce	command-t.txt	/*g:CommandTInputDebounce*
 g:CommandTMatchWindowAtTop	command-t.txt	/*g:CommandTMatchWindowAtTop*
 g:CommandTMatchWindowReverse	command-t.txt	/*g:CommandTMatchWindowReverse*
@@ -63,6 +71,7 @@ g:CommandTMaxHeight	command-t.txt	/*g:CommandTMaxHeight*
 g:CommandTMinHeight	command-t.txt	/*g:CommandTMinHeight*
 g:CommandTNeverShowDotFiles	command-t.txt	/*g:CommandTNeverShowDotFiles*
 g:CommandTQuickfixMap	command-t.txt	/*g:CommandTQuickfixMap*
+g:CommandTRecursiveMatch	command-t.txt	/*g:CommandTRecursiveMatch*
 g:CommandTRefreshMap	command-t.txt	/*g:CommandTRefreshMap*
 g:CommandTSCMDirectories	command-t.txt	/*g:CommandTSCMDirectories*
 g:CommandTScanDotDirectories	command-t.txt	/*g:CommandTScanDotDirectories*