fzf/doc/fzf.txt

fzf.txt	fzf	Last change: June 8 2019
FZF - TABLE OF CONTENTS                                            *fzf* *fzf-toc*
==============================================================================

  FZF Vim integration
    :FZF[!]
      Configuration
        Examples
    fzf#run
    fzf#wrap
    fzf inside terminal buffer
      Hide statusline
    License

FZF VIM INTEGRATION                                        *fzf-vim-integration*
==============================================================================

This repository only enables basic integration with Vim. If you're looking for
more, check out {fzf.vim}{1} project.

(Note: To use fzf in GVim, an external terminal emulator is required.)

                                       {1} https://github.com/junegunn/fzf.vim


:FZF[!]
==============================================================================

                                                                          *:FZF*

If you have set up fzf for Vim, `:FZF` command will be added.
>
    " Look for files under current directory
    :FZF

    " Look for files under your home directory
    :FZF ~

    " With options
    :FZF --no-sort --reverse --inline-info /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
    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.
    " CTRL-N and CTRL-P will be automatically bound to next-history and
    " previous-history instead of down and up. If you don't like the change,
    " explicitly bind the keys to down and up in your $FZF_DEFAULT_OPTS.
    let g:fzf_history_dir = '~/.local/share/fzf-history'
<

FZF#RUN                                                                *fzf#run*
==============================================================================

For more advanced uses, you can use `fzf#run([options])` function.

`fzf#run()` function is the core of Vim integration. It takes a single
dictionary argument. At the very least, specify `sink` option to tell what it
should do with the selected entry.
>
    call fzf#run({'sink': 'e'})
<
Without `source`, 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 `: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'})
<
fzf allows you to select multiple entries with `--multi` (or `-m`) option, and
you can change its bottom-up layout with `--reverse` option. Such options can
be specified as `options`.
>
    call fzf#run({'sink': 'tabedit', 'options': '--multi --reverse'})
<
Instead of using the default find command, you can use any shell command as
the source. This will list the files managed by git.
>
    call fzf#run({'source': 'git ls-files', 'sink': 'e'})
<
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', 'right': '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 following example, we use the names of the open
buffers as the source.
>
    call fzf#run({'source': map(filter(range(1, bufnr('$')), 'buflisted(v:val)'),
                \               'bufname(v:val)'),
                \ 'sink': 'e', 'down': '30%'})
<
Or the names of color schemes.
>
    call fzf#run({'source': map(split(globpath(&rtp, 'colors/*.vim')),
                \               'fnamemodify(v:val, ":t:r")'),
                \ 'sink': 'colo', 'left': '25%'})
<
The following table shows 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 | Use tmux pane with the given size (e.g.  `20` ,  `50%` )
  `window`  (Vim 8 / Neovim)  | string        | Command to open fzf window (e.g.  `vertical aboveleft 30new` )
  `launcher`                  | string        | External terminal emulator to start fzf with (GVim only)
  `launcher`                  | funcref       | Function for generating  `launcher`  string (GVim only)
 ---------------------------+---------------+--------------------------------------------------------------

`options` entry can be either a string or a list. For simple cases, string
should suffice, but prefer to use list type if you're concerned about escaping
issues on different platforms.
>
    call fzf#run({'options': '--reverse --prompt "C:\\Program Files\\"'})
    call fzf#run({'options': ['--reverse', '--prompt', 'C:\Program Files\']})
<

FZF#WRAP                                                              *fzf#wrap*
==============================================================================

`:FZF` command provided by default knows how to handle CTRL-T, CTRL-X, and
CTRL-V and opens the selected file in a new tab, in a horizontal split, or in
a vertical split respectively. And these key bindings can be configured via
`g:fzf_action`. This is implemented using `--expect` option of fzf and the
smart sink function. It also understands `g:fzf_colors`, `g:fzf_layout` and
`g:fzf_history_dir`. However, `fzf#run` doesn't know about any of these
options.

By "wrapping" your options dictionary with `fzf#wrap` before passing it to
`fzf#run`, you can make your command also support the options.
>
    " Usage:
    "   fzf#wrap([name string,] [opts dict,] [fullscreen boolean])

    " This command now supports CTRL-T, CTRL-V, and CTRL-X key bindings
    " and opens fzf according to g:fzf_layout setting.
    command! Buffers call fzf#run(fzf#wrap(
        \ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}))

    " This extends the above example to open fzf in fullscreen
    " when the command is run with ! suffix (Buffers!)
    command! -bang Buffers call fzf#run(fzf#wrap(
        \ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0))

    " You can optionally pass the name of the command as the first argument to
    " fzf#wrap to make it work with g:fzf_history_dir
    command! -bang Buffers call fzf#run(fzf#wrap('buffers',
        \ {'source': map(range(1, bufnr('$')), 'bufname(v:val)')}, <bang>0))
<

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 the non-default layout
   - `call fzf#run({'left': '30%'})` or `let g:fzf_layout = {'left': '30%'}`


< Hide statusline >___________________________________________________________~
                                                           *fzf-hide-statusline*

When fzf starts in a terminal buffer, you may want to hide the statusline of
the containing buffer.
>
    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) 2017 Junegunn Choi

==============================================================================
vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap: