-
Notifications
You must be signed in to change notification settings - Fork 318
/
Copy pathcommand-t.txt
1358 lines (1083 loc) · 56.5 KB
/
command-t.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*command-t.txt* Command-T plug-in for Vim *command-t*
CONTENTS *command-t-contents*
1. Introduction |command-t-intro|
2. Requirements |command-t-requirements|
3. Installation |command-t-installation|
4. Upgrading |command-t-upgrading|
5. Trouble-shooting |command-t-trouble-shooting|
6. Known issues |command-t-known-issues|
7. Usage |command-t-usage|
8. Commands |command-t-commands|
9. Functions |command-t-functions|
10. Mappings |command-t-mappings|
11. Options |command-t-options|
12. FAQ |command-t-faq|
13. Tips |command-t-tips|
14. Authors |command-t-authors|
15. Development |command-t-development|
16. Website |command-t-website|
17. Related projects |command-t-related-projects|
18. License |command-t-license|
19. History |command-t-history|
INTRODUCTION *command-t-intro*
The Command-T plug-in provides an extremely fast, intuitive mechanism for
opening files and buffers 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 TextMate.
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
more weight.
To search efficiently, especially in large projects, you should adopt a
"path-centric" rather than a "filename-centric" mentality. That is you should
think more about where the desired file is found rather than what it is
called. This means narrowing your search down by including some characters
from the upper path components rather than just entering characters from the
filename itself.
REQUIREMENTS *command-t-requirements*
The core of Command-T is written in C for speed, and it optionally makes use
of a number of external programs -- such as `git`, `rg`, and `watchman` --
for finding files.
Run `:checkhealth wincent.commandt` to confirm that the C library has been
built, and check for the presence of the optional executable helpers.
See also |command-t-ruby-requirements| for older requirements.
INSTALLATION *command-t-installation*
Most people choose to install using a plug-in manager (although you may
also choose to simply download the source code or pull it into your dot-files
as a Git submodule). As an example, if you were using packer.nvim
(https://github.com/wbthomason/packer.nvim), the following config could be
used:
use {
'wincent/command-t',
run = 'cd lua/wincent/commandt/lib && make',
setup = function ()
vim.g.CommandTPreferredImplementation = 'lua'
end,
config = function()
require('wincent.commandt').setup({
-- Customizations go here.
})
end,
}
Note the use of `make`; you'll need a C compiler to actually build the
plug-in. If you're managing the plug-in manually, `cd` into the
`lua/wincent/commandt/lib/` directory and type:
>
make
<
If you're not sure where to run this command, running
`:checkhealth wincent.commandt` should show the exact location.
See also |command-t-ruby-installation| for older installation instructions
(relevant if you wish to continue using the Ruby implementation as a
fallback, as described in |command-t-upgrading| below).
UPGRADING *command-t-upgrading*
This section details what has changed from version 5.x to 6.x, why, and how to
update. For additional context see the blog post:
https://wincent.dev/blog/command-t-lua-rewrite
Up to and including version 5.0, Command-T was written in a combination of
Ruby, Vimscript, and C, and was compatible with a range of versions of both
Vim and Neovim. Back when the project started (2010), Vim was at version 7 and
Neovim did not exist yet. At that time, Ruby provided a convenient means of
packaging high-performance C code inside a library that could be called from
Vim, making Command-T the fastest fuzzy-finder by far. The downside was that
it was hard to install because it required that care be taken to compile both
Vim and Command-T with the exact same version of Ruby. Additionally, Vim did
not yet provide handy abstractions for things like floating windows, which
meant that a large fraction of the Command-T codebase was actually dedicated
to micromanaging windows, buffers and splits, so that it could create the
illusion of rendering a separate match listing interface without interfering
with existing buffers, splits, and settings. Most of this code was written in
Ruby (a "real" programming language), which was a bit more pleasant to work
with than Vimscript (infamous for its quirks), but the design was still fairly
unorthodox; for example, the decision to capture query inputs by setting up
mappings for individual keys (given that there was no actual input buffer)
meant that some things that you might reasonably expect to work, like being
able to copy and paste a query, did not always work.
Since then, a number of things have occurred: competitive pressure from Neovim
has lead to a proliferation of features in both editors, including floating
windows which make building plug-in UIs like the one needed by Command-T
much easier than before. While Vim has doubled down on its bespoke scripting
language in the form of "Vim9 script", Neovim has leveraged Lua, which is
broadly used across a range of technology ecosystems and offers excellent
performance. Many core editor APIs are now easily accessible from Lua, and for
those that aren't, running pieces of Vimscript from Lua is possible, albeit
ugly. Interestingly, from the perspective of Command-T, interfacing with a
C library from Lua is relatively straightforward due to the excellent FFI
support.
From version 6.0, as the result of a complete rewrite, the core of Command-T
is now written in Lua and C, and it only supports Neovim. The C library is now
pure POSIX-compliant C, free from any references to the Ruby virtual machine.
This, combined with the low overhead of calling into C from Lua via the FFI
means that the performance critical parts of the code are even faster than
before, up to twice as fast according to the benchmarks. In addition, by
targeting newer APIs and writing the UI code in Lua, that portion of the core
is also significantly more responsive and robust. Various UI quirks have been
eliminated in this way, including the aforementioned inability to paste
queries (Command-T uses a real buffer for input now, which means that all
standard Vim editing commands can be used inside the prompt area).
There is a cost, however. Most notably, the rewrite is not yet a
feature-complete copy of the original Ruby-powered version, and filling in
the gaps is dependent on seeing adequate demand from users. Additionally,
as a ground-up rewrite, there is the possibility that new bugs have been
introduced. The other obvious cost is that this is a breaking change, in a
sense. No attempt has been made at providing Windows support for instance, nor
for Vim. In my judgment, Neovim has won the war, and I have no interest in
investing in projects that require me to master a custom programming language
usuable in only one environment.
In recognition of the fact that many plug-in users in the Vim/Neovim ecosystem
use plug-in managers to track the `HEAD` of the default branch of a Git
repository, we can use SemVer (https://semver.org/) but not expect it to serve
much communicative purpose nor shield users from inconvenience. As such, the
initial plan is to keep the Ruby code exactly where it is inside the plug-in
and print a deprecation warning prompting people to either opt-in to continue
using the old implementation, or otherwise opt-in to the new one.
How to opt-in to remaining on the Ruby implementation ~
Set:
>
let g:CommandTPreferredImplementation='ruby'
<
early on in your |vimrc|, before the Lua code in the plug-in has had a chance
to execute. This will cause the Ruby code to set up its commands, options,
and mappings as it always has done. That is, a command like |:CommandT| will
open the Ruby-powered file finder, and a mapping like `<Leader>t` will trigger
that command. Likewise, options such as |g:CommandTMaxFiles| will continue to
operate as before. The behavior of these commands, options, and mappings is
described in |command-t-ruby.txt| (the bulk of the documentation in this file,
|command-t.txt|, refers to the Lua-powered facilities).
The Lua implementation is still available for testing even when
|g:CommandTPreferredImplementation| is set to `"ruby"`. For example, to use
the Lua-powered version of |:CommandT| when Ruby is selected, invoke the
command with the `:KommandT` alias instead.
How to opt-in to switching to the Lua implementation ~
Call:
>
require('wincent.commandt').setup()
<
early on in your |vimrc|, before the Ruby plug-in code has had a chance to
execute. Alternatively, if you wish to defer calling |commandt.setup()| until
later on in the |startup| process, you can instead define early on:
>
let g:CommandTPreferredImplementation='lua'
<
In order to make a clean break, and avoid confusion about the capabilities
and behavior of the different implementations, the Lua version does not make
any use of the |g:| options variables from the Ruby implementation. That is,
instead of setting a variable like |g:CommandTMaxHeight| to control the height
of the match listing, you would instead pass a `height` value in your
|commandt.setup()| call:
>
require('wincent.commandt').setup({
height = 30,
})
<
Upon opting in to use the Lua implementation, it will set up commands such as
|:CommandT|, |:CommandTBuffer|, and |:CommandTHelp|. As noted previously, not
all commands in the Ruby implementation have equivalents in the Lua
implementation yet.
The Ruby implementation, which continues to exist, will take the call to
|commandt.setup()| as a cue to define alternate versions of its commands under
different aliases, that can be used as a fallback in the event that something
is faulty or insufficient with the Lua versions. For example, the Ruby
versions of the above will be available as `:KommandT`, `:KommandTBuffer`, and
`:KommandTHelp`, respectively. At some point in the future, once the new
version is considered sufficiently stable and complete, these fallbacks
won't be defined any more. Expect that change to be made with the release of
version 7.0.
Unlike the Ruby version, the Lua version does not define any mappings out of
the box. In order to set up the equivalent mappings for Lua, you would add the
following to your |vimrc| or some other file that gets loaded during
|startup|:
>
vim.keymap.set('n', '<Leader>b', '<Plug>(CommandTBuffer)')
vim.keymap.set('n', '<Leader>j', '<Plug>(CommandTJump)')
vim.keymap.set('n', '<Leader>t', '<Plug>(CommandT)')
<
What happens if you don't explicitly opt-in to either implementation ~
When you open Neovim, Command-T will show a message prompting you to choose an
implementation via one of the above means. You can either follow this prompt,
or ignore it, but it will appear every time that you open Neovim until you
make a decision.
If you don't opt-in explicitly, Command-T version 6.0 will behave as though
you had chosen Ruby. Starting with version 7.0, it will behave as though you
had chosen Lua.
If you are running Vim instead of Neovim, Command-T will behave as though you
had chosen Ruby.
If you wish to avoid the entire business of upgrading, you can set up your
plug-in manager to track the Command-T `5-x-release` branch instead of `main`.
That branch only contains the Ruby code, and none of the Lua changes that
started with the 6.0 release.
TROUBLE-SHOOTING *command-t-trouble-shooting*
Command-T hangs ~
Command-T may appear to hang while scanning the filesystem if it encounters
a circular or cyclical symbolic link, causing it to scan some directory
hierarchy in an infinite loop. While Command-T could implement cycle detection
(and it in fact did in the Ruby implementation), doing so would mean slowing
down every scan in a well-constructed filesystem, just to avoid problems
caused by pathological filesystems. Given that the prime design goal of
Command-T is to provide the fastest experience possible, there are no plans to
implement cycle detection in the Lua rewrite.
As such, the recommendation is to remove such cycles from the filesystem.
One way to find the cycles is with the `find` command:
>
find . -follow -printf ""
<
This will print "File system loop detected" for every cycle found. Note that
on macOS you may need to install and use the GNU version of `find` (for
example, via Homebrew), and execute the command as `gfind`.
Another way to mitigate the harm caused by cycles is to use the `max_files`
options to limit the number of files that Command-T will scan before
terminating the scan. See |command-t-max_files|.
Other trouble-shooting issues ~
See |command-t-ruby-trouble-shooting| for older trouble-shooting tips.
KNOWN ISSUES *command-t-known-issues*
- There are many missing features in 6.x compared with 5.x.
- 5.x used to cache directory listings, requiring the use of |:CommandTFlush|
to force a re-scan. 6.x does not implement any such caching (which means
that results are always fresh, but on large directories the re-scanning may
introduce a noticeable delay).
- The documentation for 6.x (ie. this document) is still a work in progress.
USAGE *command-t-usage*
See also |command-t-ruby-usage| for older usage information.
COMMANDS *command-t-commands*
*:CommandT*
|:CommandT| Brings up the Command-T file window, starting in the current
working directory as returned by the |:pwd| command. Scans
for files using the `fts` facilities provided by the C
standard library.
*:CommandTBuffer*
|:CommandTBuffer| Brings up the Command-T buffer window.
This works exactly like the standard file window,
except that the selection is limited to files that
you already have open in buffers.
*:CommandTFind*
|:CommandTFind| Brings up the Command-T file window, starting in the current
working directory as returned by the |:pwd| command. Scans
for files by executing the `find` executable.
*:CommandTGit*
|:CommandTGit| Brings up the Command-T file window, starting in the current
working directory as returned by the |:pwd| command. Scans
for files using `git`, so only works inside Git
repositories.
*:CommandTHelp*
|:CommandTHelp| Brings up the Command-T help search window. This works
exactly like the standard file window, except that it shows
help topics found in any documentation under Vim's
|'runtimepath'|.
*:CommandTLine*
|:CommandTLine| Brings up the Command-T line search window. This works
exactly like the standard file window, except that it shows
the lines in the current buffer.
*:CommandTRipgrep*
|:CommandTRipgrep| Brings up the Command-T file window, starting in the current
working directory as returned by the |:pwd| command. Scans
for files using `rg`.
*:CommandTWatchman*
|:CommandTWatchman| Brings up the Command-T file window, starting in the current
working directory as returned by the |:pwd| command. Scans
for files by connecting to the `watchman` daemon, which must
be installed on your system.
See also |command-t-ruby-commands| for commands that exist specifically within
the Ruby-powered version of Command-T.
FUNCTIONS *command-t-functions*
All Lua functions defined by Command-T are namespaced under `wincent` in
order to avoid collisions with other plug-ins and with built-in functionality
provided by Neovim. That is, to require and use a function like
|commandt.setup()| you would use a `require` statement like:
>
require('wincent.commandt').setup()
<
The are a number of private functions that are defined inside the plug-in that
are for internal use only. To make clear where the public/private boundary
falls, all internal functions are nested under `wincent.commandt.private`. As
such, if you were to require one of these, be aware that none of these APIs
are documented and they could change without notice at any time; for example:
>
local Window = require('wincent.commandt.private.window').Window
<
*commandt.setup()*
|commandt.setup()|
>
require('wincent.commandt').setup({
always_show_dot_files = false,
height = 15,
ignore_case = nil, -- If nil, will infer from Neovim's `'ignorecase'`.
mappings = {
i = {
['<C-a>'] = '<Home>',
['<C-c>'] = 'close',
['<C-e>'] = '<End>',
['<C-h>'] = '<Left>',
['<C-j>'] = 'select_next',
['<C-k>'] = 'select_previous',
['<C-l>'] = '<Right>',
['<C-n>'] = 'select_next',
['<C-p>'] = 'select_previous',
['<C-s>'] = 'open_split',
['<C-t>'] = 'open_tab',
['<C-v>'] = 'open_vsplit',
['<CR>'] = 'open',
['<Down>'] = 'select_next',
['<Up>'] = 'select_previous',
},
n = {
['<C-a>'] = '<Home>',
['<C-c>'] = 'close',
['<C-e>'] = '<End>',
['<C-h>'] = '<Left>',
['<C-j>'] = 'select_next',
['<C-k>'] = 'select_previous',
['<C-l>'] = '<Right>',
['<C-n>'] = 'select_next',
['<C-p>'] = 'select_previous',
['<C-s>'] = 'open_split',
['<C-t>'] = 'open_tab',
['<C-u>'] = 'clear',
['<C-v>'] = 'open_vsplit',
['<CR>'] = 'open',
['<Down>'] = 'select_next',
['<Esc>'] = 'close',
['<Up>'] = 'select_previous',
['H'] = 'select_first',
['M'] = 'select_middle',
['G'] = 'select_last',
['L'] = 'select_last',
['gg'] = 'select_first',
['j'] = 'select_next',
['k'] = 'select_previous',
},
},
margin = 10,
match_listing = {
-- 'double', 'none', 'rounded', 'shadow', 'single', 'solid', or a
-- list of strings.
border = { '', '', '', '│', '┘', '─', '└', '│' },
},
never_show_dot_files = false,
order = 'forward', -- 'forward' or 'reverse'.
position = 'center', -- 'bottom', 'center' or 'top'.
prompt = {
-- 'double', 'none', 'rounded', 'shadow', 'single', 'solid', or a
-- list of strings.
border = { '┌', '─', '┐', '│', '┤', '─', '├', '│' },
},
open = function(item, kind)
commandt.open(item, kind)
end,
root_markers = { '.git', '.hg', '.svn', '.bzr', '_darcs' },
scanners = {
file = {
max_files = 0,
},
find = {
max_files = 0,
},
git = {
max_files = 0,
submodules = true,
untracked = false,
},
rg = {
max_files = 0,
},
},
selection_highlight = 'PmenuSel',
smart_case = nil, -- If nil, will infer from Neovim's `'smartcase'`.
threads = nil, -- Let heuristic apply.
traverse = 'none', -- 'file', 'pwd' or 'none'.
})
<
See below for description of specific properties that can be used in the table
passed to |commandt.setup()|.
*command-t-always_show_dot_files*
boolean (default: false)
When showing a file listing Command-T will by default show dot-files only
if the entered search string contains a dot that could cause a dot-file to
match. For example, given a search query like ".init", the following path
would match and be shown in the match listing:
.config/nvim/init.lua
but a query like "init" would not show the path.
When set to true, this setting instructs Command-T to always include
matching dot-files in the match listing regardless of whether the search
string contains a dot. So, for the example path above, a query like "init"
would cause the path to show in the match listing even though it is a dot-file.
Note that this setting only influences file listings (ie. those shown by
commands like |:CommandT|, |:CommandTFind|, and so on); the buffer listing (shown
by |:CommandTBuffer|) treats dot-files like any other file and will show them
whenever they match the search query.
See also |command-t-never_show_dot_files|
*command-t-max_files*
number or function (default: 0)
`max_files` can be used to limit the number of files that Command-T will scan
before terminating the scan. A value of 0 (the default), means no limit. The
following example shows how to configure different limits for each of the
built-in scanners:
>
scanners = {
file = {
max_files = 100000, -- A "big" limit.
},
find = {
max_files = 10, -- A small limit.
},
git = {
max_files = 0, -- Same as no limit.
},
rg = {
-- No setting, no limit.
},
}
<
If you define your own finder, you can provide a `max_files` value with that.
For example, you can provide a literal number:
>
finders = {
ack = {
command = function(directory)
local command = 'ack -f --print0'
if directory ~= '' and directory ~= '.' and directory ~= './' then
directory = vim.fn.shellescape(directory)
command = command .. ' -- ' .. directory
end
local drop = 0
local max_files = 10000
return command, drop
end,
max_files = 100000,
},
}
<
or a function that returns a number:
>
finders = {
ack = {
command = function(directory)
local command = 'ack -f --print0'
if directory ~= '' and directory ~= '.' and directory ~= './' then
directory = vim.fn.shellescape(directory)
command = command .. ' -- ' .. directory
end
local drop = 0
return command, drop
end,
max_files = function(options)
-- Imagine we want to use the same value as is configured for rg:
return options.scanners.rg.max_files
end,
},
}
<
The built-in `file` scanner will terminate its scan as soon as the specified
`max_files` limit is reached. In contrast, `command`-based scanners (like the
"ack" example shown above, or the built-in `find`, `git`, or `rg` scanners),
all involve forking out to a separate process; for these, as soon as Command-T
detects that they have returned `max_files` or more results it will terminate
them with a `SIGKILL` signal. Depending on whether or how the forked process's
output is buffered, it's possible that slightly more than `max_files` items
may be returned.
*command-t-never_show_dot_files*
boolean (default: false)
In the file listing, Command-T will by default show dot-files if the entered
search string contains a dot that could cause a dot-file to match. Otherwise,
dot-files are suppressed. For example, given a search query like ".init", the
following path would match and be shown in the match listing:
.config/nvim/init.lua
but a query like "init" would not show the path.
When set to a true, this setting instructs Command-T to never show dot-files
under any circumstances, so a search like ".init" would not show the
corresponding path.
Note that it is contradictory to set both this setting and
|command-t-always_show_dot_files| to true.
Note that this setting has no effect in buffer listings (ie. those shown by
|:CommandTBuffer|), where dot files are treated like any other file.
*command-t-root_markers*
list of strings (default: various)
`root_markers` is used in conjunction with the `traverse` setting (see
|command-t-traverse|) to control how commands like |:CommandT| choose a root
directory at which to begin the search when invoked without an explicit path
argument.
The default value is a list-like table containing the following strings:
'.git', '.hg', '.svn', '.bzr', '_darcs'.
*command-t-traverse*
string (default: 'none')
Controls how path-based commands like |:CommandT| choose a root directory from
which to begin the search when invoked without an explicit path argument.
Possible vaules are:
- "none": use Neovim's present working directory as the root (ie. attempt no
traversal).
- "file": starting from the file currently being edited, traverse upwards
through the filesystem hierarchy until finding an SCM root (as indicated
by the presence of a ".git", ".hg" or similar diretory) and use that as the
base path. If no such root is found, fall back to using the present working
directory as a root. The list of SCM markers that Command-T uses to detect an
SCM root can be customized with the `root_markers` option (see
|command-t-root_markers|).
- "pwd": traverse upwards looking for an SCM root just like the "file" setting
(above), but instead of starting from the file currently being edited, start
from Neovim's present working directory.
MAPPINGS *command-t-mappings*
See also |command-t-ruby-mappings| for older mappings.
OPTIONS *command-t-options*
See also |command-t-ruby-options| for older options.
FAQ *command-t-faq*
See also |command-t-ruby-faq| for older FAQs.
TIPS *command-t-tips*
See also |command-t-ruby-tips| for older tips.
AUTHORS *command-t-authors*
Command-T is written and maintained by Greg Hurrell <[email protected]>.
Other contributors that have submitted patches include, in alphabetical order:
Abhinav Gupta Nate Kane
Adrian Keet Nicholas T.
Aleksandrs Ļedovskis Nicolas Alpi
Alexey Terekhov Nikolai Aleksandrovich Pavlov
Andrea Cedraro Nilo César Teixeira
Andrius Grabauskas Noon Silk
Andy Waite Ole Petter Bang
Anthony Panozzo Patrick Hayes
Artem Nezvigin Paul Jolly
Ben Boeckel Pavel Sergeev
Brendan Mulholland Rainux Luo
Cody Buell Richard Feldman
Daniel Burgess Roland Puntaier
Daniel Hahler Ross Lagerwall
David Emett Sam Morris
David Szotten Scott Bronson
Douglas Drumond Seth Fowler
Elanora Manson Sherzod Gapirov
Emily Strickland Shlomi Fish
Felix Tjandrawibawa Stefan Schmidt
Gary Bernhardt Stephen Gelman
Henric Trotzig Steve Herrell
Ivan Ukhov Steven Moazami
Jakob Pfender Steven Stallion
Jeff Kreeftmeijer Sung Pae
Jerome Castaneda Thomas Pelletier
Joe Lencioni Timothy Reen
KJ Tsanaktsidis Todd Derr
Kevin Webster Tom Spurling
Kien Nguyen Duc Ton van den Heuvel
Lucas de Vries Victor Hugo Borja
Marcus Brito Vlad Seghete
Marian Schubert Vít Ondruch
Matthew Todd Woody Peterson
Max Timkovich Yan Pritzker
Mike Lundy Zak Johnson
Nadav Samet xiaodezhang
This list produced with:
:read !git shortlog -s HEAD | grep -v 'Greg Hurrell' | cut -f 2-3 | column -c 72 | expand | sed -e 's/^/ /'
Additionally, Hanson Wang, Jacek Wysocki, Kevin Cox, and Yiding Jia wrote
patches which were not directly included but which served as a model for
changes that did end up making it in.
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
was one of the largest Ruby-based Vim plug-ins at the time.
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:
http://www.vim.org/scripts/script.php?script_id=1890
DEVELOPMENT *command-t-development*
Development in progress can be inspected at:
https://github.com/wincent/command-t
the clone URL for which is:
https://github.com/wincent/command-t.git
Mirrors exist on GitLab and BitBucket, and are automatically updated once per
hour:
https://gitlab.com/wincent/command-t
https://bitbucket.org/ghurrell/command-t
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 or similar, which often
means running a version later than the last official release, the intention is
that the "main" 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 "main". You can track this branch if you're
feeling wild and experimental, but note that the "next" branch may
periodically be rewound (force-updated) to keep it in sync with the
"main" branch after each official release.
The release process is:
1. Update the version in `lua/wincent/commandt/version.lua`.
2. Update |command-t-history|.
3. Commit with a message like "chore: prepare for 6.0.0 release".
4. Create a signed tag with `git tag -s -m '6.0.0 release` (or similar).
5. Publish with `git push origin --follow-tags` (or similar).
6. Create GitHub release and publish release notes.
7. Create archive (eg. `git archive -o command-t-6.0.0-b.1.zip HEAD -- .` or
similar).
8. Upload to vim.org (http://www.vim.org/scripts/script.php?script_id=3025).
WEBSITE *command-t-website*
The official website for Command-T is:
https://github.com/wincent/command-t
The latest release will always be available from:
https://github.com/wincent/command-t/releases
A copy of each release is also available from the official Vim scripts site
at:
http://www.vim.org/scripts/script.php?script_id=3025
Bug reports should be submitted to the issue tracker at:
https://github.com/wincent/command-t/issues
RELATED PROJECTS *command-t-related-projects*
fuzzy-native ~
Command-T's matching algorithm ported to C++ and wrapped inside a Node NPM
module:
https://github.com/hansonw/fuzzy-native
ctrlp-cmatcher ~
Command-T's matching algorithm wrapped in a Python extension, for use with
the CtrlP Vim plug-in:
https://github.com/JazzCore/ctrlp-cmatcher
commandt.score ~
Command-T's match-scoring algorithm wrapped in a Python extension:
https://pypi.python.org/pypi/commandt.score
LICENSE *command-t-license*
Copyright 2010-present Greg Hurrell and contributors.
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.
HISTORY *command-t-history*
main (not yet released) ~
- fix: teach buffer finder to see all buffers passed into Neovim as
command-line arguments (https://github.com/wincent/command-t/issues/418).
- feat: add `max_files` settings
(https://github.com/wincent/command-t/issues/420).
- fix: fix compilation error reported on Linux
(https://github.com/wincent/command-t/pull/423).
- feat: add `match_listing` / `border` and `prompt` / `border` settings.
- feat: add `traverse` and `root_markers` settings
(https://github.com/wincent/command-t/issues/416).
6.0.0-b.1 (16 December 2022) ~
- fix: actually respect `scanners.git.submodules` and `scanners.git.untracked`
options in |commandt.setup()| (https://github.com/wincent/command-t/pull/414).
- fix: avoid "invalid option" error to `format` at specific window dimensions
(https://github.com/wincent/command-t/issues/415).
6.0.0-b.0 (21 October 2022) ~
- feat: add back |:CommandTLine| finder
(https://github.com/wincent/command-t/pull/408).
6.0.0-a.4 (5 September 2022) ~
- fix: use correct `git ls-files` switch when `scanners.git.untracked` is `true`
(https://github.com/wincent/command-t/pull/405).
- fix: make Watchman scanner work with a path argument
(https://github.com/wincent/command-t/commit/c7020a44cfddfb87).
- feat: show "fallback" in prompt title if a fallback scanner kicks in
(https://github.com/wincent/command-t/commit/c16b2721fdad1d0b).
6.0.0-a.3 (31 August 2022) ~
- fix: fix build problem on 32-bit systems; this was a regression introduced
in 6.0.0-a.2 (https://github.com/wincent/command-t/commit/6c8e2a3e3b5acd00).
- docs: drop unnecessary `{ remap = true }` from mapping instructions
(https://github.com/wincent/command-t/pull/401)
- feat: implement fallback for when `find`, `git`, or `rg` return no results
(https://github.com/wincent/command-t/commit/9e8c790ca718b40f2).
- refactor: hide standard error output from `find`, `git` and `rg`
(https://github.com/wincent/command-t/commit/b229d929ae2a55a7b).
- fix: don't let control characters mess up the display
(https://github.com/wincent/command-t/issues/402).
6.0.0-a.2 (29 August 2022) ~
- fix: fix rendering glitches due to interaction with vim-dirvish
(https://github.com/wincent/command-t/commit/ca959c9437d13ca0).
- feat: teach prompt window to delete a word with `<C-w>`
(https://github.com/wincent/command-t/commit/0a19ffbe7bed4988).
- fix: avoid aborts on 32-bit systems
(https://github.com/wincent/command-t/issues/399).
6.0.0-a.1 (28 August 2022) ~
- fix: gracefully handle |commandt.setup()| calls without a `finders` config.
(https://github.com/wincent/command-t/commit/e59f7406a565b574).
- refactor: get rid of a potentially confusing diagnostic message
(https://github.com/wincent/command-t/commit/05b434a7dd3e2963).
- docs: add documentation for the |:CommandTFind|, |:CommandTGit|,
|:CommandTRipgrep|, and |:CommandTWatchman| commands
(https://github.com/wincent/command-t/commit/c488f7f41e863398).
6.0.0-a.0 (26 August 2022) ~
- Rewrite in Lua; for more details see |command-t-upgrading|. Note that this
is an alpha release, so the new APIs are subject to change.
5.0.5 (24 July 2022) ~
- Teach watchman scanner to favor `watch-project` over `watch` when
available (#390, patch from Todd Derr).
5.0.4 (28 May 2022) ~
- Support opening files which contain newlines (#365).
- Guard against possible |E315| on accepting a selection.
- Fix possible |E434| when trying to jump to some help targets.
- Use |execute()| when available to avoid possible issues with
potentially nested calls to |:redir|.
- Fix conflict with vim-cool plugin (#354).
- Close match listing after buffer deletion to avoid likely errors on
subsequent interactions (#357, patch from Andrius Grabauskas).
- Fix |E116| error opening filenames containing single quotes.
- Deal with |'wildignore'| (and |g:CommandTWildIgnore|) patterns of the form
"*pattern" (eg. "*~", which would ignore files created with Vim's default
|'backupext'|) (#369, patch from Steve Herrell).
- Turn off |'signcolumn'| in the match listing (#376).
- Teach file scanner to skip over badly encoded strings.
- Teach watchman scanner to tolerate broken watchman installation.
5.0.3 (19 September 2018) ~
- Fix unlisted buffers showing up in |:CommandTBuffer| listing on Neovim.
- Fix edge cases with opening selections in tabs (#315).
- Fix possible degenerate performance of |:CommandTBuffer| and
|:CommandTMRU| on Neovim.
- Handle missing match listing buffer in Neovim (#342).
5.0.2 (7 September 2017) ~
- Fix a RangeError on 64-bit Windows (#304, patch from Adrian Keet).
- Fix issue switching back to previously opened file in another tab (#306).
- Fix inability to open some help targets with |:CommandTHelp| (#307).
- Similar to #307, make |:CommandTCommand| work with commands containing
special characters.
- Again similar to #307, prevent special characters in tags from being escaped
when using |:CommandTTag|.
5.0.1 (18 August 2017) ~
- Fixed inability to open a top-level file with a name matching a previously
opened file (#295).
- Fixed a related issue where previously opened file would cause a file to be
opened directly rather than in the desired split/tab (#298).
- Tweaked <c-w> mapping behavior to better match what other readline-ish
implementations do, especially with respect to moving past punctuation
(#301).
5.0 (6 June 2017) ~
- Command-T now uses |:map-<nowait>|, when available, when setting up mappings.
- 'wildignore' filtering is now always performed by producing an equivalent
regular expression and applying that; previously this only happened with
the "watchman" file scanner (includes a bug fix from Henric Trotzig).
- Fixed mis-memoization of |:CommandTHelp| and |:CommandTJump| finders
(whichever one you used first would be used for both).
- Added mapping (<C-d>) to delete a buffer from the buffer list (patch from
Max Timkovich).
- Added |g:CommandTGitIncludeUntracked| option (patch from Steven Stallion).
- Added |:CommandTOpen|, which implements smart "goto or open" functionality,
and adjust |g:CommandTAcceptSelectionCommand|,
|g:CommandTAcceptSelectionTabCommand|,
|g:CommandTAcceptSelectionSplitCommand|, and
|g:CommandTAcceptSelectionVSplitCommand| to use it by default. Their default
values have been changed from "e", "tabe", "sp" and "vs" to "CommandTOpen
e", "CommandTOpen tabe", "CommandTOpen sp" and "CommandTOpen vs",
respectively. Use with |'switchbuf'| set to "usetab" for maximum effect.
- Added |g:CommandTWindowFilter| for customizing the filtering expression that
is used to determine which windows Command-T should not open selected
files in.
4.0 (16 May 2016) ~
- A non-leading dot in the search query can now match against dot-files and
"dot-directories" in non-leading path components.
- Matching algorithm sped up by about 17x (with help from Hanson Wang).
- |g:CommandTInputDebounce| now defaults to 0, as the recent optimizations
make debouncing largely unnecessary.
- Added |:CommandTHelp| for jumping to locations in the help, and an
accompanying mapping, |<Plug>(CommandTHelp)|.
- Added |:CommandTLine| for jumping to lines within the current buffer, and a
corresponding mapping, |<Plug>(CommandTLine)|.
- Added |:CommandTHistory| for jumping to previously entered commands, and a
corresponding mapping, |<Plug>(CommandTHistory)|.
- Added |:CommandTSearch| for jumping to previously entered searches, and a
corresponding mapping, |<Plug>(CommandTSearch)|.
- Added |:CommandTCommand| for finding commands, and a corresponding mapping,
|<Plug>(CommandTCommand)|.
- Added |<Plug>(CommandTMRU)| and |<Plug>(CommandTTag)| mappings.
- The "ruby" and "find" scanners now show numerical progress in the prompt
area during their scans.
- Removed functionality that was previously deprecated in 2.0.
- Fix inability to type "^" and "|" at the prompt.
- Make it possible to completely disable |'wildignore'|-based filtering by
setting |g:CommandTWildIgnore| to an empty string.
- The "watchman" file scanner now respects |'wildignore'| and
|g:CommandTWildIgnore| by constructing an equivalent regular expression and
using that for filtering.
- Show a warning when hitting |g:CommandTMaxFiles|, and add a corresponding
|g:CommandTSuppressMaxFilesWarning| setting to suppress the warning.
3.0.2 (9 February 2016) ~
- Minimize flicker on opening and closing the match listing in MacVim.
- Add |CommandTWillShowMatchListing| and |CommandTDidHideMatchListing| "User"
autocommands.
3.0.1 (25 January 2016) ~
- restore compatibility with Ruby 1.8.7.
3.0 (19 January 2016) ~
- change |g:CommandTIgnoreSpaces| default value to 1.