Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/junegunn/fzf

:cherry_blossom: A command-line fuzzy finder
https://github.com/junegunn/fzf

bash cli fish fzf go neovim tmux unix vim zsh

Last synced: 4 days ago
JSON representation

:cherry_blossom: A command-line fuzzy finder

Awesome Lists containing this project

README 

        
FZF Vim integration

===================



Installation

------------



Once you have fzf installed, you can enable it inside Vim simply by adding the

directory to `&runtimepath` in your Vim configuration file. The path may

differ depending on the package manager.



```vim

" If installed using Homebrew

set rtp+=/usr/local/opt/fzf



" If installed using Homebrew on Apple Silicon

set rtp+=/opt/homebrew/opt/fzf



" If you have cloned fzf on ~/.fzf directory

set rtp+=~/.fzf

```



If you use [vim-plug](https://github.com/junegunn/vim-plug), the same can be

written as:



```vim

" If installed using Homebrew

Plug '/usr/local/opt/fzf'



" If installed using Homebrew on Apple Silicon

Plug '/opt/homebrew/opt/fzf'



" If you have cloned fzf on ~/.fzf directory

Plug '~/.fzf'

```



But if you want the latest Vim plugin file from GitHub rather than the one

included in the package, write:



```vim

Plug 'junegunn/fzf'

```



The Vim plugin will pick up fzf binary available on the system. If fzf is not

found on `$PATH`, it will ask you if it should download the latest binary for

you.



To make sure that you have the latest version of the binary, set up

post-update hook like so:



```vim

Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }

```



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](https://github.com/junegunn/fzf.vim) 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.



`:FZF[!]`

---------



```vim

" 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](https://github.com/kien/ctrlp.vim), 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.



### Configuration



- `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



```vim

" 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, "lnum": 1 }'))

  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

" - Popup window (center of the screen)

let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6 } }



" - Popup window (center of the current window)

let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6, 'relative': v:true } }



" - Popup window (anchored to the bottom of the current window)

let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6, 'relative': v:true, 'yoffset': 1.0 } }



" - down / up / left / right

let g:fzf_layout = { 'down': '40%' }



" - Window using a Vim command

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'

```



##### Explanation of `g:fzf_colors`



`g:fzf_colors` is a dictionary mapping fzf elements to a color specification

list:



    element: [ component, group1 [, group2, ...] ]



- `element` is an fzf element to apply a color to:



  | Element                     | Description                                           |

  | ---                         | ---                                                   |

  | `fg`  / `bg`  / `hl`        | Item (foreground / background / highlight)            |

  | `fg+` / `bg+` / `hl+`       | Current item (foreground / background / highlight)    |

  | `preview-fg` / `preview-bg` | Preview window text and background                    |

  | `hl`  / `hl+`               | Highlighted substrings (normal / current)             |

  | `gutter`                    | Background of the gutter on the left                  |

  | `pointer`                   | Pointer to the current line (`>`)                     |

  | `marker`                    | Multi-select marker (`>`)                             |

  | `border`                    | Border around the window (`--border` and `--preview`) |

  | `header`                    | Header (`--header` or `--header-lines`)               |

  | `info`                      | Info line (match counters)                            |

  | `spinner`                   | Streaming input indicator                             |

  | `query`                     | Query string                                          |

  | `disabled`                  | Query string when search is disabled                  |

  | `prompt`                    | Prompt before query (`> `)                            |

  | `pointer`                   | Pointer to the current line (`>`)                     |



- `component` specifies the component (`fg` / `bg`) from which to extract the

  color when considering each of the following highlight groups



- `group1 [, group2, ...]` is a list of highlight groups that are searched (in

  order) for a matching color definition



For example, consider the following specification:



```vim

  'prompt':  ['fg', 'Conditional', 'Comment'],

```



This means we color the **prompt**

- using the `fg` attribute of the `Conditional` if it exists,

- otherwise use the `fg` attribute of the `Comment` highlight group if it exists,

- otherwise fall back to the default color settings for the **prompt**.



You can examine the color option generated according the setting by printing

the result of `fzf#wrap()` function like so:



```vim

:echo fzf#wrap()

```



`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.



```vim

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 traverse the file system

under the current directory to get the list of files. (If

`$FZF_DEFAULT_COMMAND` is set, fzf will use the output of the command

instead.) 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.



```vim

call fzf#run({'sink': 'tabedit'})

```



You can use any shell command as the source to generate the list. The

following example will list the files managed by git. It's equivalent to

running `git ls-files | fzf` on shell.



```vim

call fzf#run({'source': 'git ls-files', 'sink': 'e'})

```



fzf options can be specified as `options` entry in spec dictionary.



```vim

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.



```vim

" 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.



```vim

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       | Function to be called with each selected item                         |

| `sinklist` (or `sink*`)    | funcref       | Similar to `sink`, but takes the list of output lines at once         |

| `exit`                     | funcref       | Function to be called with the exit status of fzf (e.g. 0, 1, 2, 130) |

| `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%`)                  |

| `tmux`                     | string        | (Layout) `--tmux` options (e.g. `90%,70%`)                            |

| `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.



```vim

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 range [0 ~ 1]] or [integer range [8 ~ ]]

    - `height` [float range [0 ~ 1]] or [integer range [4 ~ ]]

- Optional:

    - `yoffset` [float default 0.5 range [0 ~ 1]]

    - `xoffset` [float default 0.5 range [0 ~ 1]]

    - `relative` [boolean default v:false]

    - `border` [string default `rounded` (`sharp` on Windows)]: Border style

        - `rounded` / `sharp` / `horizontal` / `vertical` / `top` / `bottom` / `left` / `right` / `no[ne]`



`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:



```vim

echo fzf#wrap({'source': 'ls'})

```



After we *"wrap"* our spec, we pass it to `fzf#run`.



```vim

call fzf#run(fzf#wrap({'source': 'ls'}))

```



Now it supports `CTRL-T`, `CTRL-V`, and `CTRL-X` key bindings (configurable

via `g:fzf_action`) and it opens fzf window according to `g:fzf_layout`

setting.



To make it easier to use, let's define `LS` command.



```vim

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 `).



```vim

" 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.



```vim

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`.



```vim

" 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))

```



### Global options supported by `fzf#wrap`



- `g:fzf_layout`

- `g:fzf_action`

    - **Works only when no custom `sink` (or `sinklist`) is provided**

        - Having custom sink usually means that each entry is not an ordinary

          file path (e.g. name of color scheme), so we can't blindly apply the

          same strategy (i.e. `tabedit some-color-scheme` doesn't make sense)

- `g:fzf_colors`

- `g:fzf_history_dir`



Tips

----



### fzf inside terminal buffer



On the latest versions of Vim and Neovim, fzf will start in a terminal buffer.

If you find the default ANSI colors to be different, consider configuring the

colors using `g:terminal_ansi_colors` in regular Vim or `g:terminal_color_x`

in Neovim.



```vim

" Terminal colors for seoul256 color scheme

if has('nvim')

  let g:terminal_color_0 = '#4e4e4e'

  let g:terminal_color_1 = '#d68787'

  let g:terminal_color_2 = '#5f865f'

  let g:terminal_color_3 = '#d8af5f'

  let g:terminal_color_4 = '#85add4'

  let g:terminal_color_5 = '#d7afaf'

  let g:terminal_color_6 = '#87afaf'

  let g:terminal_color_7 = '#d0d0d0'

  let g:terminal_color_8 = '#626262'

  let g:terminal_color_9 = '#d75f87'

  let g:terminal_color_10 = '#87af87'

  let g:terminal_color_11 = '#ffd787'

  let g:terminal_color_12 = '#add4fb'

  let g:terminal_color_13 = '#ffafaf'

  let g:terminal_color_14 = '#87d7d7'

  let g:terminal_color_15 = '#e4e4e4'

else

  let g:terminal_ansi_colors = [

    \ '#4e4e4e', '#d68787', '#5f865f', '#d8af5f',

    \ '#85add4', '#d7afaf', '#87afaf', '#d0d0d0',

    \ '#626262', '#d75f87', '#87af87', '#ffd787',

    \ '#add4fb', '#ffafaf', '#87d7d7', '#e4e4e4'

  \ ]

endif

```



### Starting fzf in a popup window



```vim

" Required:

" - width [float range [0 ~ 1]] or [integer range [8 ~ ]]

" - height [float range [0 ~ 1]] or [integer range [4 ~ ]]

"

" Optional:

" - xoffset [float default 0.5 range [0 ~ 1]]

" - yoffset [float default 0.5 range [0 ~ 1]]

" - relative [boolean default v:false]

" - border [string default 'rounded']: Border style

"   - 'rounded' / 'sharp' / 'horizontal' / 'vertical' / 'top' / 'bottom' / 'left' / 'right'

let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6 } }

```



Alternatively, you can make fzf open in a tmux popup window (requires tmux 3.2

or above) by putting `--tmux` option value in `tmux` key.



```vim

" See `--tmux` option in `man fzf` for available options

" [center|top|bottom|left|right][,SIZE[%]][,SIZE[%]]

if exists('$TMUX')

  let g:fzf_layout = { 'tmux': '90%,70%' }

else

  let g:fzf_layout = { 'window': { 'width': 0.9, 'height': 0.6 } }

endif

```



### 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 open fzf on the bottom on the screen (e.g. `{'down':

'40%'}`), you might want to temporarily disable the statusline for a cleaner

look.



```vim

let g:fzf_layout = { 'down': '30%' }

autocmd! FileType fzf

autocmd  FileType fzf set laststatus=0 noshowmode noruler

  \| autocmd BufLeave  set laststatus=2 showmode ruler

```



[License](LICENSE)

------------------



The MIT License (MIT)



Copyright (c) 2013-2024 Junegunn Choi