Scope

Minimal, fast, and extensible fuzzy finder for Vim.

Usage • Requirements • Installation • Configuration

There are already good implementations of this kind, such as fuzzyy and fzf. This plugin, while minimal, encompasses all essential features, excluding the preview window, which I consider non-essential. The emphasis is on performance -- pushing the essential features to their limits, and eliminating any unnecessary clutter. The feature set and key mappings align closely with nvim-telescope. The code is concise and easy-to-understand.

Extending the functionality to perform fuzzy search for other items is straightforward.

Usage

Map the following functions to your favorite keys.

In the following examples, replace <your_key> with the desired key combination.

To quickly try it out, use the commands provided below.

Find File

Find files in the current working directory. Files are retrieved through an external job, and the window seamlessly refreshes to display real-time results.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.File()<cr>

[!TIP] If you are using legacy script to map keys, use:

nnoremap <your_key> <scriptcmd>vim9cmd scope#fuzzy#File()<cr>

Same pattern applies to other mappings also.

If you're not concerned with customizing the behavior, another option is to simply map keys to commands.

Search for installed Vim files:

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.File($'find {$VIMRUNTIME} -type f -print -follow')<cr>

Use fd instead of find command, and limit the maximum number of files returned by external job to 500,000 (default is 100,000):

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.File('fd -tf --follow', 500000)<cr>

Find files in ~/.vim, ignoring swap files and hidden files.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.File($'find {$HOME}/.vim -path "*/.vim/.*" -prune -o -not ( -name "*.swp" -o -name ".*" ) -type f -print -follow')<cr>

API

# findCmd: String  : Command string to search for files. If omitted or set to
#                      'null_string', uses 'find' command.
# count:   Number  : Maximum number of files returned.
def File(findCmd: string = null_string, count: number = 100000)

[!NOTE] If the findCmd argument (above) is either unset or set to null_string, the find command (accessible from $PATH)) is automatically utilized. Under this circumstance, the following conditions apply:

• Patterns specified in the Vim option wildignore, along with patterns present in files .gitignore, ~/.gitignore, .findignore, and ~/.findignore, are excluded. For instance, to prevent the find command from traversing into the .git directory or displaying Vim swap files, add the following line to your .vimrc file: set wildignore+=.git/*,*.swp.
• If the .gitignore file contains ** or ! within the patterns, the performance of the find command may deteriorate. If this becomes problematic, consider using fd.
• For guidance on setting wildignore patterns, refer to :h autocmd-patterns within Vim. For similar assistance regarding gitignore patterns, consult 'PATTERN FORMAT'.

[!TIP] To echo the command string in Vim's command line, set the option find_echo_cmd to true. Default is false. Setting this option helps in debugging arguments given to find command. Setting of options is discussed later.

Live Grep

Unlike fuzzy search grep, command is executed after each keystroke in a dedicated external job. Result updates occur every 100 milliseconds, ensuring real-time feedback. To maintain Vim's responsiveness, lengthy processes may be terminated. An ideal scenario involves launching Vim within the project directory, initiating a grep search, and iteratively refining your query until you pinpoint the desired result. Notably, when editing multiple files, you need not re-enter the grep string for each file. Refer to the note below for further details.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.Grep()<cr>

[!TIP]

1. To perform a second grep with the same keyword, there's no need to retype it. The prompt conveniently retains the previous grep string as virtual text. Simply input <Right> or <PgDn> to auto-fill and proceed, or overwrite it as needed. For smaller projects, you can efficiently execute repeated greps without relying on the quickfix list.
2. Special characters can be entered into the prompt window directly without requiring backslash escaping.
3. When working with live grep, it can be advantageous to suspend it temporarily and refine the results through filtering. Press <C-k> to enter pattern search mode. For instance, while in pattern search mode, typing ^foo will selectively display lines starting with foo. To negate patterns, prepend ! to the search term. For instance, to filter lines that do not contain foo or bar, input !foo|bar into the prompt. Whether the pattern is case-sensitive is determined by ignorecase Vim option. To force case (in)sensitive search prepend the pattern with \c or \C. Pressing <C-k> again will toggle back to live grep mode.

Define your own grep command:

vim9script
import autoload 'scope/fuzzy.vim'
# Case sensitive grep
nnoremap <your_key> <scriptcmd>fuzzy.Grep('grep --color=never -REIHns --exclude-dir=.git')<cr>
# ripgrep
nnoremap <your_key> <scriptcmd>fuzzy.Grep('rg --vimgrep --no-heading --smart-case')<cr>
# silvergrep
nnoremap <your_key> <scriptcmd>fuzzy.Grep('ag --vimgrep')<cr>
# Search the word under cursor
nnoremap <your_key> <scriptcmd>fuzzy.Grep(null_string, true, '<cword>')<cr>

grep command string is echoed in the command line after each search. You can set an option to turn this off (see below).

API

# grepCmd:    String  : Command string as you'd use in a shell. If omitted, uses 'grep'
#                         and excludes paths specified in 'wildignore'.
# ignorecase: Boolean : Strictly for syntax highlighting. Should match the 'ignorecase'
#                         option given to 'grep'.
# cword:      String  : If not null_string, put the word under cursor into the prompt.
#                         Allowable values are '<cword>' and '<cWORD>'.
# dir:        String  : If not null_string, search in the specified directory instead of the
#                         current directory.
def Grep(grepCmd: string = null_string, ignorecase: bool = true, cword: string = null_string,
             dir: string = null_string)

[!NOTE] If the grepCmd argument (above) is either not set or set to null_string, the grep command (accessible from $PATH) is automatically utilized. In this scenario, patterns specified in the Vim option 'wildignore' are automatically excluded from grep operations. For example, to prevent the grep command from traversing into the .git directory, include the following line in your .vimrc file: set wildignore+=.git/*. Any pattern within 'wildignore' containing a slash (/) is interpreted as a directory (utilizing grep option --exclude-dir), while others are considered as files (utilizing grep option --exclude).

To optimize responsiveness, consider fine-tuning Grep() settings, particularly for larger projects and slower systems. For instance, adjusting timer_delay to a higher value can help alleviate jitteriness during fast typing or clipboard pasting. Additionally, grep_poll_interval dictates the initial responsiveness of the prompt for the first few typed characters.

Here's a breakdown of available options:

To optimize performance, adjust these options accordingly:

scope#fuzzy#OptionsSet({
    grep_echo_cmd: false,
    # ...
})

or

import autoload 'scope/fuzzy.vim'
fuzzy.OptionsSet({
    grep_echo_cmd: false,
    # ...
})

Switch Buffer

Switching buffers becomes effortless with fuzzy search. When no input is provided, it automatically selects the alternate buffer.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.Buffer()<cr>

Search unlisted buffers as well.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.Buffer(true)<cr>

API

# list_all_buffers: Boolean : If 'true', include unlisted buffers as well.
def Buffer(list_all_buffers: bool = false)

Search Current Buffer

Enter a word in the prompt, and it will initiate a fuzzy search within the current buffer. The prompt conveniently displays the word under the cursor (<cword>) or the previously searched word as virtual text. Use <Right> or <PgDn> to auto-fill and continue, or type over it.

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.BufSearch()<cr>
# Search the word under cursor
nnoremap <your_key> <scriptcmd>fuzzy.BufSearch('<cword>')<cr>

API

# cword:  String  : If not null_string, put the word under cursor into the prompt.
#                     Allowable values are '<cword>' and '<cWORD>'.
# recall: Boolean : Put previously searched word or <cword> into the prompt.
def BufSearch(cword: string = null_string, recall: bool = true)

Quickfix and Location List Integration

While the popup window is open, you can conveniently send all items (unfiltered) to a quickfix list by typing <C-q>. For filtered items, utilize <C-Q>. Likewise, to direct items to the location list, simply type <C-l> or <C-L>.

Vim conveniently retains the ten most recently used quickfix and location lists for each window. When creating a new quickfix or location list, you can choose to either append it to the end of the stack or replace existing entries with new ones. This behavior is controlled by the quickfix_stack option, which can be set using fuzzy.OptionsSet().

File list (File()), grep (Grep()), buffer list (Buffer()), word search in a buffer (BufSearch()), and git file list (GitFile()) provide formatted output containing filename information (and line numbers when available), facilitating seamless navigation. Other fuzzy search commands can also send output to the quickfix or location list, although their utility may be limited.

You have the option to display the contents of the current quickfix or location list in a popup menu for efficient fuzzy searching and navigation. Use the following mappings:

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.Quickfix()<cr>
nnoremap <your_key> <scriptcmd>fuzzy.Loclist()<cr>

The current item is highlighted with an asterisk. You can also navigate to the next error in the list by using the :cnext command instead of the popup window.

The entire stack of quickfix and location lists can be displayed in a popup window. Use the following mappings:

vim9script
import autoload 'scope/fuzzy.vim'
nnoremap <your_key> <scriptcmd>fuzzy.QuickfixHistory()<cr>
nnoremap <your_key> <scriptcmd>fuzzy.LoclistHistory()<cr>

After selecting a list from the popup menu of fuzzy.QuickfixHistory() or fuzzy.LoclistHistory(), you can automatically open the quickfix or location-list window. Add the following autocmd group:

augroup scope-quickfix-history
    autocmd!
    autocmd QuickFixCmdPost chistory cwindow
    autocmd QuickFixCmdPost lhistory lwindow
augroup END

For automatic quickfix or location list window opening after <C-q> or <C-l> commands, replace chistory|lhistory above with clist|llist.

All Functions

You can map the following fuzzy search functions to keys.

Commands

The above functions have equivalent commands that can be invoked from the command line. The primary command is :Scope, with the function name as its only argument except for Grep. These commands are primarily provided for convenience. The main interface, as described above, is through key mappings.

For example, to initiate a buffer search, use the command :Scope Buffer or :Scope buffer. Typing :Scope <Tab> will display all available functions.

Grep takes additional arguments. :Scope {Grep|grep} [dir] [str] starts a live search with 'str' as the initial search string if non-empty. If 'dir' is specified, search in that directory instead of the current directory.

You can map these commands to keys also. For example:

nnoremap <your_key> <cmd>Scope File<cr>

Key Mappings

When popup window is open the following key mappings can be used.

Prompt window editor key mappings align with Vim's default mappings for command-line editing.

Requirements

• Vim version 9.1 or higher

Installation

Install this plugin via vim-plug.

vim9script
plug#begin()
Plug 'girishji/scope.vim'
plug#end()

call plug#begin()
Plug 'girishji/scope.vim'
call plug#end()

Install using Vim's built-in package manager.

$ mkdir -p $HOME/.vim/pack/downloads/opt
$ cd $HOME/.vim/pack/downloads/opt
$ git clone https://github.com/girishji/scope.vim.git

packadd scope.vim

Configuration

The appearance of the popup window can be customized using borderchars, borderhighlight, highlight, scrollbarhighlight, thumbhighlight, maxheight, and other :h popup_create-arguments. To wrap long lines set wrap to true (default is false). To configure these settings, use scope#popup#OptionsSet().

For example, to set the border of the popup window to the Comment highlight group:

scope#popup#OptionsSet({borderhighlight: ['Comment']})

or,

import autoload 'scope/popup.vim' as sp
sp.OptionsSet({borderhighlight: ['Comment']})

Following highlight groups modify the content of popup window:

• ScopeMenuMatch: Modifies characters searched so far. Default: Linked to Special.
• ScopeMenuVirtualText: Virtual text in the Grep window. Default: Linked to Comment.
• ScopeMenuSubtle: Line number, file name, and path. Default: Linked to Comment.
• ScopeMenuCurrent: Special item indicating current status (used only when relevant). Default: Linked to Statement.

Writing Your Own Extension

The search functionality encompasses four fundamental patterns:

1. Obtaining a List and Fuzzy Searching:

   • This represents the simplest use case, where a list of items is acquired, and fuzzy search is performed on them. Check out this gist for a practical example.

2. Asynchronous List Update with Fuzzy Search:

   • In scenarios like file searching, the list of all items is updated asynchronously while concurrently conducting a fuzzy search. See this gist for an example.

3. Dynamic List Update on User Input:

   • Certain cases, such as handling tags or Vim commands, involve waiting for a new list of items every time the user inputs something.

4. Asynchronous Relevant Items Update on User Input:

   • For dynamic searches like live grep, the list is updated asynchronously, but exclusively with relevant items, each time the user types something.

Representative code for each of these patterns can be found in autoload/scope/fuzzy.vim.

Credits

Some portions of this code are shamelessly ripped from habamax.

Other Plugins to Enhance Your Workflow

1. devdocs.vim - browse documentation from devdocs.io.

2. easyjump.vim - makes code navigation a breeze.

3. fFtT.vim - accurately target words in a line.

4. autosuggest.vim - live autocompletion for Vim's command line.

5. vimcomplete - enhances autocompletion in Vim.

Contributing

Open an issue if you encounter problems. Pull requests are welcomed.