Introduction

Vim-clap stands as a comprehensive and efficient solution, providing powerful fuzzy pickers and replacements for various established Vim plugins, designed to support both Vim and NeoVim.

More screenshots

Features

Vim-clap was initially written in pure VimScript, but later incorporated a Rust dependency to enhance performance. Presently, the Rust binary maple is a must-have for ensuring smooth and optimal functionality. The principle of Vim-Clap in this regard is to offload all the heavy computation to the Rust backend and make Vim/NeoVim a super lightweight layer focusing on UI.

• Blazingly fast thanks to the powerful Rust backend
• Consistent command interface with clap-rs/clap
• Tons of builtin providers
• Support writing new providers in both Vimscript and Rust
• Support the search syntax borrowed from fzf and more

Caveats

• While Vim-clap is intended to be compatible with Windows, comprehensive testing on this platform has not been conducted to the same extent as macOS and Linux (specifically Ubuntu), as the plugin author primarily utilizes these operating systems. Consequently, there may be Windows-specific issues yet to be identified. If you encounter any problems on Windows, please create an issue, and any assistance in addressing these issues would be highly appreciated.

• While Vim-Clap strives to offer equal support for both Vim and NeoVim, certain nuances arise from the differing implementation details between the two. For example, the focusability of Vim's popup differs from NeoVim's floating_win.

Credit

• Vim-clap is initially enlightened by snails.
• Some providers' idea and code are borrowed from fzf.vim.
• The built-in fzy python implementation is based on sweep.py.

Installation

Requirement

• Vim: :echo has('patch-8.1.2114').
• NeoVim: :echo has('nvim-0.4.2').

Installation

vim-plug

" Build the Rust binary if `cargo` exists on your system.
Plug 'liuchengxu/vim-clap', { 'do': ':Clap install-binary' }

" The bang version will try to download the prebuilt binary if `cargo` does not exist.
Plug 'liuchengxu/vim-clap', { 'do': ':Clap install-binary!' }

" `:Clap install-binary[!]` will always try to compile the binary locally.
" If you do care about the disk used for the compilation, use the way of force download,
" which will directly download the prebuilt binary even if `cargo` is available.
Plug 'liuchengxu/vim-clap', { 'do': { -> clap#installer#force_download() } }

" `:Clap install-binary[!]` will run using the terminal feature which is inherently async.
" If you don't want that and hope to run the hook synchorously:
Plug 'liuchengxu/vim-clap', { 'do': has('win32') ? 'cargo build --release' : 'make' }

Employing the do hook of the Vim plugin manager typically facilitates the automatic installation of the additional Rust binary, offering a convenient and recommended solution. However, if this process encounters any issues, manual compilation of the Rust dependency is required, as outlined in the subsequent section.

Install Rust Dependency

You can download the prebuilt binary from GitHub or compile the binary locally on your own.

Compile Rust Binary Locally

Refer to https://www.rust-lang.org/tools/install if you haven't installed Rust on your system.

Assuming Rust has already been installed on your system, specifically, cargo executable exists, you can have several ways to compile the binary:

• Use this helper function :call clap#installer#build_maple() within Vim/NeoVim.

• Run make under the clap plugin directory (macOS and Linux).

• Run the cargo command on your own:

  cd path/to/vim-clap
  
  # Compile the release build, you can find the compiled executable at target/release/maple.
  cargo build --release
  

Compile Rust binary via Docker (Linux Only)

If you run into the libssl error when using the prebuilt binary from GitHub release, you can try building a static Rust binary:

$ cd path/to/vim-clap
$ docker run --rm -it -v "$(pwd)":/volume clux/muslrust cargo build --profile production --locked
$ cp target/x86_64-unknown-linux-musl/production/maple bin/maple
# See if it really works
$ ./bin/maple version

Download Prebuilt binary

The prebuilt binary is available from GitHub release. You can call :call clap#installer#download_binary() in Vim/NeoVim, or do it manually as follows.

Quick Downloader

The scripts to download the prebuilt binary quickly are provided out of the box. The downloaded executable can be found at bin/maple on success.

• Unix: $ bash install.sh
• Windows: Run install.ps1 in the powershell.

Download Prebuilt Binary By Hand

1. Download the binary from the latest release https://github.com/liuchengxu/vim-clap/releases according to your system.
2. Rename the downloaded binary to:
   • Unix: maple
   • Windows: maple.exe
3. Move maple/maple.exe to bin directory. Don't forget to assign execute permission to maple via chmod a+x bin/maple if you are using the Unix system.

Clap Providers

• Builtin Providers
  • Global Variables
• How to Create Your Own Provider
• Disable Auto-Completion Plugin in Clap Input Window

Builtin Providers

Additional requirement means the potential extra tool needed for the particular provider besides the Rust binary maple.

• The command with a superscript + means that it supports multi-selection via Tab.
• Clap live_grep is deprecated now, Clap grep is recommended as the successor.
• :Clap grep
  • Use :Clap grep --query=<cword> to grep the word under cursor.
  • Use :Clap grep --query=@visual to grep the visual selection.
  • cwd will be searched by default, specify the extra paths in the end to search multiple directories.
    • :Clap grep --path ~/.vim/plugged/ale with cwd is ~/.vim/plugged/vim-clap will both search vim-clap and ale.

Send a pull request if certain provider is not listed here.

Global Variables

• g:clap_layout: Dict, { 'width': '67%', 'height': '33%', 'row': '33%', 'col': '17%' } by default. This variable controls the size and position of vim-clap window. By default, the vim-clap window is placed relative to the currently active window. To make it relative to the whole editor modify this variable as shown below:

  let g:clap_layout = { 'relative': 'editor' }
  

• g:clap_open_action: Dict, { 'ctrl-t': 'tab split', 'ctrl-x': 'split', 'ctrl-v': 'vsplit' }, extra key bindings for opening the selected file in a different way. NOTE: do not define a key binding which is conflicted with the other default bindings of vim-clap, and only ctrl-* is supported for now.

• g:clap_provider_alias: Dict, if you don't want to invoke some clap provider by its id(name), as it's too long or somehow, you can add an alias for that provider.

  " The provider name is `command_history`, with the following alias config,
  " now you can call it via both `:Clap command_history` and `:Clap hist:`.
  let g:clap_provider_alias = {'hist:': 'command_history'}
  

• g:clap_selected_sign: Dict, { 'text': ' >', 'texthl': "ClapSelectedSign", "linehl": "ClapSelected"}.

• g:clap_current_selection_sign: Dict, { 'text': '>>', 'texthl': "ClapCurrentSelectionSign", "linehl": "ClapCurrentSelection"}.

• g:clap_no_matches_msg: String, 'NO MATCHES FOUND', message to show when there is no matches found.

• g:clap_popup_input_delay: Number, 200ms by default, delay for actually responding to the input, vim only.

• g:clap_disable_run_rooter: Bool, v:false, vim-clap by default will try to run from the project root by changing cwd temporarily. Set it to v:true to run from the origin cwd. The project root here means the git base directory. Create an issue if you want to see more support about the project root.

The option naming convention for provider is g:clap_provider_{provider_id}_{opt}.

• g:clap_provider_grep_blink: [2, 100] by default, blink 2 times with 100ms timeout when jumping the result. Set it to [0, 0] to disable the blink.

• g:clap_provider_grep_opts: An empty string by default, allows you to enable flags such as '--hidden -g "!.git/"'.

See :help clap-options for more information.

How to Create Your Own Provider

" `:Clap quick_open` to open some dotfiles quickly.
" `description` is actually optional, but if you want to show this provider
" when you call `:Clap`, the `description` is necessary.
let g:clap_provider_quick_open = {
      \ 'source': ['~/.vimrc', '~/.spacevim', '~/.bashrc', '~/.tmux.conf'],
      \ 'sink': 'e',
      \ 'description': 'Quick open some dotfiles',
      \ }

Find more examples at wiki/Examples.

For complete guide about writing a clap provider please see PROVIDER.md.

Disable Auto-Completion Plugin in Clap Input Window

Some of the auto-completion engines need to turn off to prevent bizarre behaviors(#580)

For nvim-completion, add autocmd to your init.vim:

autocmd FileType clap_input let g:completion_enable_auto_pop = 0

For nvim-compe:

autocmd FileType clap_input call compe#setup({ 'enabled': v:false }, 0)

Configuration

Project-specific ignore config

Ignore the results from the certain files/folders.

[provider.project-ignores."~/src/github.com/bitcoin/bitcoin"]
ignore-file-path-pattern = ["test"]
ignore-file-name-pattern = ["test"]

Theme

By default vim-clap would use the colors extracted from your current colorscheme, which is not guaranteed to suitable for all the colorschemes. You can try the built-in material_design_dark theme if the default theme does not work well:

let g:clap_theme = 'material_design_dark'

You could also set g:clap_theme to be a Dict to specify the palette:

" Change the CamelCase of related highlight group name to under_score_case.
let g:clap_theme = { 'search_text': {'guifg': 'red', 'ctermfg': 'red'} }

ClapDisplay and ClapPreview are the most basic highlight groups for the display and preview window, which can be overridden if the provider has its own syntax highlight, then checkout the related syntax file for more granular highlights directly.

If you are keen to explore and even want to write your own clap theme, take autoload/clap/themes/material_design_dark.vim as a reference.

See :help clap-highlights for more information.

Keybindings

Keybindings

Insert mode

• Use Ctrl-j/Down or Ctrl-k/Up to navigate the result list up and down linewise.
• Use PageDown/PageUp to scroll the result list down and up.
• Use Ctrl-a/Home to go to the start of the input.
• Use Ctrl-e/End to go to the end of the input.
• Use Ctrl-c, Ctrl-g, Ctrl-[ or Esc(vim) to exit.
• Use Ctrl-h/BS to delete previous character.
• Use Ctrl-d to delete next character.
• Use Ctrl-b to move cursor left one character.
• Use Ctrl-f to move cursor right one character.
• Use Ctrl-n for next input in the history.
• Use Ctrl-p for previous input in the history.
• Use Enter to select the entry and exit.
  • Use Enter to expand the directory or edit the file for :Clap filer.
• By default Alt-u does nothing.
  • Use Alt-u to go up one directory in :Clap filer.
• Use Tab to select multiple entries and open them using the quickfix window.(Need the provider has sink* support)
  • Use Tab to expand the directory for :Clap filer.
• Use Ctrl-t or Ctrl-x, Ctrl-v to open the selected entry in a new tab or a new split.
• Use Ctrl-u to clear inputs.
• Use Ctrl-l to launch the whole provider list panel for invoking another provider at any time.
• Use Shift-Tab to invoke the action dialog(vim only).
• Use Shift-up and Shift-down to scroll the preview.

NeoVim only

Normal mode

• Use j/Down or k/Up to navigate the result list up and down linewise.
• By default Alt-u does nothing.
  • Use Alt-u to go up one directory in :Clap filer.
• Use Ctrl-c, Ctrl-g or Esc to exit.
• Use Ctrl-d/Ctrl-u/PageDown/PageUp to scroll the result list down and up.
• Use Ctrl-l to launch the whole provider list panel for invoking another provider at any time.
• Use Ctrl-n for next input in the history.
• Use Ctrl-p for previous input in the history.
• Use Shift-up and Shift-down to scroll the preview.
• Use gg and G to scroll to the first and last item.
• Use Enter to select the entry and exit.
• Use Shift-Tab to invoke the action dialog.
• Actions defined by g:clap_open_action.

Cmdline mode

• Use :q to exit.

See :help clap-keybindings for more information. Note that the keybindings are not consistent due to discrepancies between Vim/Neovim and different providers.

Search Syntax

Fzf search syntax

vim-clap adopts most of fzf search syntax. Note that the OR operator defined by a single bar character is unsupported, but you can achieve that by using multiple exact matches.

Extended search syntax

Apart from the basic fzf search syntax, more search syntax are supported:

Clap Plugins

WARN: This is an experimental feature, use at your own risk!

Vim-Clap was originally a mere Vim fuzzy picker plugin, however, the integration of a robust Rust backend unveiled the potential to implement various additional functionalities effortlessly, for enjoyable experimentation and potential performance enhancements.

Note that the vim-Clap plugins were mainly created for the plugin author's personal uses, thus they may not be feature-complete as their alternatives. Bugs are expected as these plugins are not extensively tested, feel free to use if you are brave enough.

You must enable the g:clap_plugin_experimental flag in your .vimrc and create a config file beforehand.

" Specify this variable to enable the plugin feature.
let g:clap_plugin_experimental = v:true

All the non-system plugins are disabled by default. To enable the plugins, you need to set enable = true explicitly for the plugins in the config file.

[plugin.git]
enable = true

Check out Available Plugins for detailed introduction to the plugins. Try :Clap clap_actions to take a look at the existing actions.

Configuration

User config file is loaded from:

• Linux: ~/.config/vimclap/config.toml
• macOS: ~/Library/Application\ Support/org.vim.Vim-Clap/config.toml
• Windows: C:\Users\Alice\AppData\Roaming\Vim\Vim Clap\config\config.toml

The default config is as follows:

## Log configuration.
[log]
# Specify the max log level.
max-level = "debug"
# Specify the log target to enable more detailed logging.
#
# Particularly useful for the debugging purpose.
#
# ```toml
# [log]
# log-target = "maple_core::stdio_server=trace,rpc=debug"
# ```
log-target = ""

## Winbar configuration.
[winbar]
# Whether to enable the winbar.
enable = false
# Specify the display style for the file path in winbar.
file-path-style = "one-segment-per-component"

## Matcher configuration.
[matcher]
# Specify how the results are sorted.
tiebreak = "score,-begin,-end,-length"

[plugin.colorizer]
# Whether to enable this plugin.
enable = false

[plugin.word-highlighter]
# Whether to enable this plugin.
enable = false
# Whether to ignore the comment line
ignore-comment-line = false
# Disable the plugin when the file matches this pattern.
ignore-files = "*.toml,*.json,*.yml,*.log,tmp"
# Specify the keyword highlights.
#
# ```toml
# # The first item is the keyword itself, the next item is the highlight group for the keyword.
# # By default only TODO is highlighted and it's linked to `Todo` highlight group.
# keyword-highlight = [ ["TODO", "Todo"] ]
#
# # You can extend this list to define more keywords and their corresponding highlight group.
# keyword-highlight = [ ["TODO", "Todo"], ["FIXME", "Error"] ]
# ```
keyword-highlight = [["TODO", "Todo"]]
# This flag controls whether to only highlight the keywords in the comment line.
#
# This flag is set as `true` by default.
keyword-highlight-comment-line-only = true

[plugin.ctags]
# Whether to enable this plugin.
enable = false
# Disable this plugin if the file size exceeds the max size limit.
#
# By default the max file size limit is 4MiB.
max-file-size = 4194304

[plugin.git]
# Whether to enable this plugin.
enable = true

[plugin.linter]
# Whether to enable this plugin.
enable = false

[plugin.lsp]
# Whether to enable this plugin.
enable = false
# Whether to include the declaration when invoking `ClapAction lsp.reference`.
include-declaration = false
# Specify the list of filetypes for which the lsp plugin will be disabled.
#
# If a filetype is included in this list, the Language Server Protocol (LSP) plugin
# will not be activated for files with that particular type.
filetype-blocklist = []
# Specifies custom languages that are not built into vim-clap.
#
# This config allows to define a new language or override the default value
# of the built-in language config. Note that if you are defining a new language,
# (check out the full list of supported languages by default in `languages.toml`),
# you need to provide associated language server configurations as well.
#
# # Example
#
# ```toml
# [[plugin.lsp.language]]
# name = "erlang"
# file-types = ["erlang"]
# root-markers = ["rebar.config"]
# language-servers = ["erlang-ls"]
#
# [plugin.lsp.language-server.erlang-ls]
# command = "erlang_ls"
# ```
language = []

# Specify language server configurations.
#
# # Example
#
# ```toml
# [plugin.lsp.language-server.rust-analyzer]
# procMacro.enable = false
# procMacro.attributes.enable = false
# diagnostics.disabled = [ "unresolved-proc-macro" ]
# ```
[plugin.lsp.language-server]

[plugin.markdown]
# Whether to enable this plugin.
enable = false
# Specify the port number for the preview page in browser.
#
# A random port will be used each time if not specified.
preview-port = 0

# Specify the strategy of tree-sitter rendering.
#
# The default strategy is to render the entire buffer until the
# file size exceeds 256 KiB.
#
#
# Possible values:
# - `visual-lines`: Always render the visual lines only.
# - `entire-buffer-up-to-limit`: Render the entire buffer until
# the buffer size exceeds the size limit (in bytes).
#
# # Example
#
# ```toml
# [plugin.syntax.render-strategy]
# strategy = "visual-lines"
# ```
[plugin.syntax.render-strategy]
strategy = "entire-buffer-up-to-limit"
file-size-limit = 262144

## Provider (fuzzy picker) configuration.
[provider]
# Whether to share the input history among providers.
share-input-history = false
# Specify the syntax highlight engine for the provider preview.
#
# Possible values: `vim`, `sublime-syntax` and `tree-sitter`
preview-highlight-engine = "vim"

# Ignore configuration per project, with paths specified as
# absolute path or relative to the home directory.
[provider.project-ignores]

# Ignore configuration per provider.
#
# There are multiple ignore settings, with priorities as follows:
# `provider_ignores` > `provider_ignores` > `global_ignore`
[provider.provider-ignores]

# Delay in milliseconds before handling the the user query.
#
# When the delay is set not-zero, some intermediate inputs
# may be dropped if user types too fast.
#
# By default the debounce is set to 200ms to all providers.
#
# # Example
#
# ```toml
# [provider.debounce]
# # Set debounce to 100ms for files provider specifically.
# "files" = 100
# ```
[provider.debounce]

## Global ignore configuration.
[global-ignore]
# Whether to ignore the comment line when applicable.
ignore-comments = false
# Whether to include only results from files tracked by git, if in a git repository.
git-tracked-only = false
# Patterns for ignoring files based on their names.
#
# For instance, to exclude results from files whose names contain "test" for
# the dumb_jump provider:
#
# ```toml
# [provider.provider-ignores.dumb_jump]
# ignore-file-name-pattern = ["test"]
# ```
ignore-file-name-pattern = []
# Patterns for ignoring files based on their paths.
#
# For instance, to exclude the results from the folder whose names contain `test`
# in the project `~/src/github.com/vim/vim`:
#
# ```toml
# [provider.project-ignores."~/src/github.com/vim/vim"]
# ignore-file-path-pattern = ["test"]
# ```
ignore-file-path-pattern = []

Available Plugins

The following plugins may only implement a subset of features of their alternatives.

TODO: elaborate on plugins' usage.

• colorizer
• ctags
• word-highlighter
• diagnostics
• git
• linter
• lsp
• markdown
• syntax

colorizer

[plugin.colorizer]
enable = true

ctags

word-highlighter

[plugin.word-highlighter]
enable = true

By default this plugin utilizes Normal guibg as the primary color. It then lighten this base color for ClapCursorWord and darkens it for ClapCursorWordTwins. You can manually adjust them in case the default highlights does not meet your expectations.

diagnostics

This plugin does not do any substantial work but used to provide an interface to interact with the diagnostics provided by the linter and lsp plugin.

git

[plugin.git]
enable = true

The signs are updated when you save the buffer and are rendered lazily, i.e., the signs are only displayed when they are visually in the range of screen.

linter

[plugin.linter]
enable = true

Although ALE has been an incredible and feature-rich linter plugin that served me well for an extended period, I began to notice a persistent lagging issue over time. There were noticeable delays in refreshing the latest diagnostics whenever I made changes to the source file (especially the Rust file). This prompted me to develop this linter plugin in Rust and the results have been remarkable. The diagnostics update is now considerably faster from what I see on Rust project.

Currently supported linters:

• go: gopls
• sh: shellcheck
• vim: vint
• python: ruff
• rust: cargo cargo check/cargo clippy

Ensure the required linter executables are installed and can be found in your system before using this plugin.

lsp

[plugin.lsp]
enable = true

This plugin aims to implement the language server protocol. It's still pretty experimental and only a handful features are supported at present.

• Goto reference/definition/declaration/typeDefinition/implementation/reference
• Open documentSymbols/workspaceSymbols

markdown

[plugin.markdown]
enable = true

• Features
  • Generate/Update/Delete toc
  • Open preview in browser

syntax

[plugin.syntax]
enable = true

This plugin implements the sublime-syntax and tree-sitter highlighting. The sublime-syntax is feature-limited and pretty experimental, this plugin primarily focues on the tree-sitter highlighting support.

Currently tree-sitter supported languages:

• Bash, C, Cpp, Dockerfile, Go, Javascript, Json, Markdown, Python, Rust, Toml, Viml