fzf.txt fzf Last change: February 3 2020 FZF - TABLE OF CONTENTS *fzf* *fzf-toc* ============================================================================== FZF Vim integration Summary :FZF[!] Configuration Examples fzf#run fzf#wrap Tips fzf inside terminal buffer Starting fzf in a popup window Hide statusline License FZF VIM INTEGRATION *fzf-vim-integration* ============================================================================== SUMMARY *fzf-summary* ============================================================================== The Vim plugin of fzf provides two core functions, and `:FZF` command which is the basic file selector command built on top of them. 1. `fzf#run([spec dict])` - Starts fzf inside Vim with the given spec - `:call fzf#run({'source': 'ls'})` 2. `fzf#wrap([spec dict]) -> (dict)` - Takes a spec for `fzf#run` and returns an extended version of it with additional options for addressing global preferences (`g:fzf_xxx`) - `:echo fzf#wrap({'source': 'ls'})` - We usually wrap a spec with `fzf#wrap` before passing it to `fzf#run` - `:call fzf#run(fzf#wrap({'source': 'ls'}))` 3. `:FZF [fzf_options string] [path string]` - Basic fuzzy file selector - A reference implementation for those who don't want to write VimScript to implement custom commands - If you're looking for more such commands, check out {fzf.vim}{1} project. The most important of all is `fzf#run`, but it would be easier to understand the whole if we start off with `:FZF` command. {1} https://github.com/junegunn/fzf.vim :FZF[!] ============================================================================== *:FZF* > " Look for files under current directory :FZF " Look for files under your home directory :FZF ~ " With fzf command-line options :FZF --reverse --info=inline /tmp " Bang version starts fzf in fullscreen mode :FZF! < Similarly to {ctrlp.vim}{2}, use enter key, CTRL-T, CTRL-X or CTRL-V to open selected files in the current window, in new tabs, in horizontal splits, or in vertical splits respectively. Note that the environment variables `FZF_DEFAULT_COMMAND` and `FZF_DEFAULT_OPTS` also apply here. {2} https://github.com/kien/ctrlp.vim < Configuration >_____________________________________________________________~ *fzf-configuration* *g:fzf_action* *g:fzf_layout* *g:fzf_colors* *g:fzf_history_dir* - `g:fzf_action` - Customizable extra key bindings for opening selected files in different ways - `g:fzf_layout` - Determines the size and position of fzf window - `g:fzf_colors` - Customizes fzf colors to match the current color scheme - `g:fzf_history_dir` - Enables history feature Examples~ *fzf-examples* > " This is the default extra key bindings let g:fzf_action = { \ 'ctrl-t': 'tab split', \ 'ctrl-x': 'split', \ 'ctrl-v': 'vsplit' } " An action can be a reference to a function that processes selected lines function! s:build_quickfix_list(lines) call setqflist(map(copy(a:lines), '{ "filename": v:val }')) copen cc endfunction let g:fzf_action = { \ 'ctrl-q': function('s:build_quickfix_list'), \ 'ctrl-t': 'tab split', \ 'ctrl-x': 'split', \ 'ctrl-v': 'vsplit' } " Default fzf layout " - down / up / left / right let g:fzf_layout = { 'down': '~40%' } " You can set up fzf window using a Vim command (Neovim or latest Vim 8 required) let g:fzf_layout = { 'window': 'enew' } let g:fzf_layout = { 'window': '-tabnew' } let g:fzf_layout = { 'window': '10new' } " Customize fzf colors to match your color scheme " - fzf#wrap translates this to a set of `--color` options let g:fzf_colors = \ { 'fg': ['fg', 'Normal'], \ 'bg': ['bg', 'Normal'], \ 'hl': ['fg', 'Comment'], \ 'fg+': ['fg', 'CursorLine', 'CursorColumn', 'Normal'], \ 'bg+': ['bg', 'CursorLine', 'CursorColumn'], \ 'hl+': ['fg', 'Statement'], \ 'info': ['fg', 'PreProc'], \ 'border': ['fg', 'Ignore'], \ 'prompt': ['fg', 'Conditional'], \ 'pointer': ['fg', 'Exception'], \ 'marker': ['fg', 'Keyword'], \ 'spinner': ['fg', 'Label'], \ 'header': ['fg', 'Comment'] } " Enable per-command history " - History files will be stored in the specified directory " - When set, CTRL-N and CTRL-P will be bound to 'next-history' and " 'previous-history' instead of 'down' and 'up'. let g:fzf_history_dir = '~/.local/share/fzf-history' < FZF#RUN ============================================================================== *fzf#run* `fzf#run()` function is the core of Vim integration. It takes a single dictionary argument, a spec, and starts fzf process accordingly. At the very least, specify `sink` option to tell what it should do with the selected entry. > call fzf#run({'sink': 'e'}) < We haven't specified the `source`, so this is equivalent to starting fzf on command line without standard input pipe; fzf will use find command (or `$FZF_DEFAULT_COMMAND` if defined) to list the files under the current directory. When you select one, it will open it with the sink, `:e` command. If you want to open it in a new tab, you can pass `:tabedit` command instead as the sink. > call fzf#run({'sink': 'tabedit'}) < Instead of using the default find command, you can use any shell command as the source. The following example will list the files managed by git. It's equivalent to running `git ls-files | fzf` on shell. > call fzf#run({'source': 'git ls-files', 'sink': 'e'}) < fzf options can be specified as `options` entry in spec dictionary. > call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'}) < You can also pass a layout option if you don't want fzf window to take up the entire screen. > " up / down / left / right / window are allowed call fzf#run({'source': 'git ls-files', 'sink': 'e', 'left': '40%'}) call fzf#run({'source': 'git ls-files', 'sink': 'e', 'window': '30vnew'}) < `source` doesn't have to be an external shell command, you can pass a Vim array as the source. In the next example, we pass the names of color schemes as the source to implement a color scheme selector. > call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')), \ 'fnamemodify(v:val, ":t:r")'), \ 'sink': 'colo', 'left': '25%'}) < The following table summarizes the available options. ---------------------------+---------------+---------------------------------------------------------------------- Option name | Type | Description ~ ---------------------------+---------------+---------------------------------------------------------------------- `source` | string | External command to generate input to fzf (e.g. `find .` ) `source` | list | Vim list as input to fzf `sink` | string | Vim command to handle the selected item (e.g. `e` , `tabe` ) `sink` | funcref | Reference to function to process each selected item `sink*` | funcref | Similar to `sink` , but takes the list of output lines at once `options` | string/list | Options to fzf `dir` | string | Working directory `up` / `down` / `left` / `right` | number/string | (Layout) Window position and size (e.g. `20` , `50%` ) `window` (Vim 8 / Neovim) | string | (Layout) Command to open fzf window (e.g. `vertical aboveleft 30new` ) `window` (Vim 8 / Neovim) | dict | (Layout) Popup window settings (e.g. `{'width': 0.9, 'height': 0.6}` ) ---------------------------+---------------+---------------------------------------------------------------------- `options` entry can be either a string or a list. For simple cases, string should suffice, but prefer to use list type to avoid escaping issues. > call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'}) call fzf#run({'options': ['--reverse', '--prompt', 'C:\Program Files\']}) < When `window` entry is a dictionary, fzf will start in a popup window. The following options are allowed: - Required: - `width` [float] - `height` [float] - Optional: - `highlight` [string default `'Comment'`]: Highlight group for border - `rounded` [boolean default `v:true`]: Use rounded border FZF#WRAP ============================================================================== *fzf#wrap* We have seen that several aspects of `:FZF` command can be configured with a set of global option variables; different ways to open files (`g:fzf_action`), window position and size (`g:fzf_layout`), color palette (`g:fzf_colors`), etc. So how can we make our custom `fzf#run` calls also respect those variables? Simply by "wrapping" the spec dictionary with `fzf#wrap` before passing it to `fzf#run`. - `fzf#wrap([name string], [spec dict], [fullscreen bool]) -> (dict)` - All arguments are optional. Usually we only need to pass a spec dictionary. - `name` is for managing history files. It is ignored if `g:fzf_history_dir` is not defined. - `fullscreen` can be either `0` or `1` (default: 0). `fzf#wrap` takes a spec and returns an extended version of it (also a dictionary) with additional options for addressing global preferences. You can examine the return value of it like so: > echo fzf#wrap({'source': 'ls'}) < After we "wrap" our spec, we pass it to `fzf#run`. > call fzf#run(fzf#wrap({'source': 'ls'})) < Now it supports CTRL-T, CTRL-V, and CTRL-X key bindings and it opens fzf window according to `g:fzf_layout` setting. To make it easier to use, let's define `LS` command. > command! LS call fzf#run(fzf#wrap({'source': 'ls'})) < Type `:LS` and see how it works. We would like to make `:LS!` (bang version) open fzf in fullscreen, just like `:FZF!`. Add `-bang` to command definition, and use value to set the last `fullscreen` argument of `fzf#wrap` (see :help ). > " On :LS!, evaluates to '!', and '!0' becomes 1 command! -bang LS call fzf#run(fzf#wrap({'source': 'ls'}, 0)) < Our `:LS` command will be much more useful if we can pass a directory argument to it, so that something like `:LS /tmp` is possible. > command! -bang -complete=dir -nargs=* LS \ call fzf#run(fzf#wrap({'source': 'ls', 'dir': }, 0)) < Lastly, if you have enabled `g:fzf_history_dir`, you might want to assign a unique name to our command and pass it as the first argument to `fzf#wrap`. > " The query history for this command will be stored as 'ls' inside g:fzf_history_dir. " The name is ignored if g:fzf_history_dir is not defined. command! -bang -complete=dir -nargs=* LS \ call fzf#run(fzf#wrap('ls', {'source': 'ls', 'dir': }, 0)) < TIPS *fzf-tips* ============================================================================== < fzf inside terminal buffer >________________________________________________~ *fzf-inside-terminal-buffer* The latest versions of Vim and Neovim include builtin terminal emulator (`:terminal`) and fzf will start in a terminal buffer in the following cases: - On Neovim - On GVim - On Terminal Vim with a non-default layout - `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}` Starting fzf in a popup window~ *fzf-starting-fzf-in-a-popup-window* > " Required: " - width [float] " - height [float] " " Optional: " - highlight [string default 'Comment']: Highlight group for border " - rounded [boolean default v:true]: Use rounded border let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6 } } < Hide statusline~ *fzf-hide-statusline* When fzf starts in a terminal buffer, the file type of the buffer is set to `fzf`. So you can set up `FileType fzf` autocmd to customize the settings of the window. For example, if you use the default layout (`{'down': '~40%'}`) on Neovim, you might want to temporarily disable the statusline for a cleaner look. > if has('nvim') && !exists('g:fzf_layout') autocmd! FileType fzf autocmd FileType fzf set laststatus=0 noshowmode noruler \| autocmd BufLeave set laststatus=2 showmode ruler endif < LICENSE *fzf-license* ============================================================================== The MIT License (MIT) Copyright (c) 2013-2020 Junegunn Choi ============================================================================== vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap: