<commit_before>*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. Usage                           |command-t-usage|
 7. Commands                        |command-t-commands|
 8. Functions                       |command-t-functions|
 9. Mappings                        |command-t-mappings|
10. Options                         |command-t-options|
11. FAQ                             |command-t-faq|
12. Tips                            |command-t-tips|
13. Authors                         |command-t-authors|
14. Development                     |command-t-development|
15. Website                         |command-t-website|
16. Related projects                |command-t-related-projects|
17. License                         |command-t-license|
18. 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 executables -- 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*

You'll need a C compiler. `cd` into the `lua/wincent/commandt/lib/` directory
and type:
>
    make
<
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*

Until version 5.0, Command-T was written in a combination Ruby, Vimscript, and
C, and was compatible with a range of versions of both Vim and Neovim. Back
when the project started in 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 a 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).

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.

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<commit_msg>docs(lua): add some notes about pasting queries<commit_after>*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. Usage                           |command-t-usage|
 7. Commands                        |command-t-commands|
 8. Functions                       |command-t-functions|
 9. Mappings                        |command-t-mappings|
10. Options                         |command-t-options|
11. FAQ                             |command-t-faq|
12. Tips                            |command-t-tips|
13. Authors                         |command-t-authors|
14. Development                     |command-t-development|
15. Website                         |command-t-website|
16. Related projects                |command-t-related-projects|
17. License                         |command-t-license|
18. 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 executables -- 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*

You'll need a C compiler. `cd` into the `lua/wincent/commandt/lib/` directory
and type:
>
    make
<
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*

Until version 5.0, Command-T was written in a combination Ruby, Vimscript, and
C, and was compatible with a range of versions of both Vim and Neovim. Back
when the project started in 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 a 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 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
{'fraction_non_alphanumeric': 0.046425826287471175, 'fraction_numerical': 0.00568793235972329, 'mean_word_length': 2.92962851102386, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3170634', 'n_tokens_mistral': 3315, 'n_tokens_neox': 3069, 'n_words': 1765}