mirror of
https://github.com/Llewellynvdm/fzf.git
synced 2024-12-22 19:09:00 +00:00
8cb59e6fca
A spec can have `exit` callback that is called with the exit status of fzf. This can be used to clean up temporary resources or restore the original state when fzf is closed without a selection.
510 lines
21 KiB
Plaintext
510 lines
21 KiB
Plaintext
fzf.txt fzf Last change: February 15 2024
|
|
FZF - TABLE OF CONTENTS *fzf* *fzf-toc*
|
|
==============================================================================
|
|
|
|
FZF Vim integration |fzf-vim-integration|
|
|
Installation |fzf-installation|
|
|
Summary |fzf-summary|
|
|
:FZF[!] |:FZF|
|
|
Configuration |fzf-configuration|
|
|
Examples |fzf-examples|
|
|
Explanation of g:fzf_colors |fzf-explanation-of-gfzfcolors|
|
|
fzf#run |fzf#run|
|
|
fzf#wrap |fzf#wrap|
|
|
Global options supported by fzf#wrap |fzf-global-options-supported-by-fzf#wrap|
|
|
Tips |fzf-tips|
|
|
fzf inside terminal buffer |fzf-inside-terminal-buffer|
|
|
Starting fzf in a popup window |fzf-starting-fzf-in-a-popup-window|
|
|
Hide statusline |fzf-hide-statusline|
|
|
License |fzf-license|
|
|
|
|
FZF VIM INTEGRATION *fzf-vim-integration*
|
|
==============================================================================
|
|
|
|
|
|
INSTALLATION *fzf-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.
|
|
>
|
|
" 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}{1}, the same can be written as:
|
|
>
|
|
" 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:
|
|
>
|
|
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:
|
|
|
|
*fzf#install*
|
|
>
|
|
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
|
|
<
|
|
{1} https://github.com/junegunn/vim-plug
|
|
|
|
|
|
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}{2} 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.
|
|
|
|
{2} 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}{3}, 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.
|
|
|
|
{3} 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, "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~
|
|
*fzf-explanation-of-gfzfcolors*
|
|
|
|
`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:
|
|
>
|
|
'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:
|
|
>
|
|
:echo fzf#wrap()
|
|
<
|
|
|
|
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 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.
|
|
>
|
|
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.
|
|
>
|
|
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 | 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.
|
|
>
|
|
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
|
|
==============================================================================
|
|
|
|
*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 (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.
|
|
>
|
|
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 <bang> value to set the
|
|
last `fullscreen` argument of `fzf#wrap` (see :help <bang>).
|
|
>
|
|
" On :LS!, <bang> evaluates to '!', and '!0' becomes 1
|
|
command! -bang LS call fzf#run(fzf#wrap({'source': 'ls'}, <bang>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': <q-args>}, <bang>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': <q-args>}, <bang>0))
|
|
<
|
|
|
|
< Global options supported by fzf#wrap >______________________________________~
|
|
*fzf-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-tips*
|
|
==============================================================================
|
|
|
|
|
|
< fzf inside terminal buffer >________________________________________________~
|
|
*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.
|
|
|
|
>
|
|
" 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 >____________________________________________~
|
|
*fzf-starting-fzf-in-a-popup-window*
|
|
>
|
|
" 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` options in `tmux` key.
|
|
>
|
|
" 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 >___________________________________________________________~
|
|
*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 open fzf on the bottom on the screen (e.g. `{'down':
|
|
'40%'}`), you might want to temporarily disable the statusline for a cleaner
|
|
look.
|
|
>
|
|
let g:fzf_layout = { 'down': '30%' }
|
|
autocmd! FileType fzf
|
|
autocmd FileType fzf set laststatus=0 noshowmode noruler
|
|
\| autocmd BufLeave <buffer> set laststatus=2 showmode ruler
|
|
<
|
|
|
|
LICENSE *fzf-license*
|
|
==============================================================================
|
|
|
|
The MIT License (MIT)
|
|
|
|
Copyright (c) 2013-2024 Junegunn Choi
|
|
|
|
==============================================================================
|
|
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap:
|