diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README-VIM.md | 148 | ||||
| -rw-r--r-- | README.md | 73 | ||||
| -rw-r--r-- | doc/fzf.txt | 177 |
4 files changed, 330 insertions, 69 deletions
@@ -4,3 +4,4 @@ gopath pkg Gemfile.lock .DS_Store +doc/tags diff --git a/README-VIM.md b/README-VIM.md new file mode 100644 index 00000000..06db5c8f --- /dev/null +++ b/README-VIM.md @@ -0,0 +1,148 @@ +FZF Vim integration +=================== + +This repository only enables basic integration with Vim. If you're looking for +more, check out [fzf.vim](https://github.com/junegunn/fzf.vim) project. + +(Note: To use fzf in GVim, an external terminal emulator is required.) + +`:FZF[!]` +--------- + +If you have set up fzf for Vim, `:FZF` command will be added. + +```vim +" 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](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 (tmux pane or Neovim split) +- `g:fzf_colors` + - Customizes fzf colors to match the current color scheme +- `g:fzf_history_dir` + - Enables history feature +- `g:fzf_launcher` + - (Only in GVim) Terminal emulator to open fzf with + - `g:Fzf_launcher` for function reference + +#### Examples + +```vim +" This is the default extra key bindings +let g:fzf_action = { + \ 'ctrl-t': 'tab split', + \ 'ctrl-x': 'split', + \ 'ctrl-v': 'vsplit' } + +" Default fzf layout +" - down / up / left / right +let g:fzf_layout = { 'down': '~40%' } + +" In Neovim, you can set up fzf window using a Vim command +let g:fzf_layout = { 'window': 'enew' } +let g:fzf_layout = { 'window': '-tabnew' } + +" This will split only under the current window. +let g:fzf_layout = { 'window': '10 split | enew'} + +" 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'], + \ '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` +--------- + +For more advanced uses, you can use `fzf#run([options])` function with the +following 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 | 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` (*Neovim only*) | 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) | + +`fzf#wrap` +---------- + +`fzf#wrap([name string,] [opts dict,] [fullscreen boolean])` is a helper +function that decorates the options dictionary so that it understands +`g:fzf_layout`, `g:fzf_action`, `g:fzf_colors`, and `g:fzf_history_dir` like +`:FZF`. + +```vim +command! -bang MyStuff + \ call fzf#run(fzf#wrap('my-stuff', {'dir': '~/my-stuff'}, <bang>0)) +``` + +GVim +---- + +In GVim, you need an external terminal emulator to start fzf with. `xterm` +command is used by default, but you can customize it with `g:fzf_launcher`. + +```vim +" This is the default. %s is replaced with fzf command +let g:fzf_launcher = 'xterm -e bash -ic %s' + +" Use urxvt instead +let g:fzf_launcher = 'urxvt -geometry 120x30 -e sh -c %s' +``` + +If you're running MacVim on OSX, I recommend you to use iTerm2 as the +launcher. Refer to the [this wiki page][macvim-iterm2] to see how to set up. + +[macvim-iterm2]: https://github.com/junegunn/fzf/wiki/On-MacVim-with-iTerm2 + +[License](LICENSE) +------------------ + +The MIT License (MIT) + +Copyright (c) 2017 Junegunn Choi @@ -53,7 +53,7 @@ brew install fzf /usr/local/opt/fzf/install ``` -### Vim plugin +### As Vim plugin You can manually add the directory to `&runtimepath` as follows, @@ -345,75 +345,10 @@ commands as well like follows. complete -F _fzf_file_completion -o default -o bashdefault doge ``` -Usage as Vim plugin -------------------- +Vim plugin +---------- -This repository only enables basic integration with Vim. If you're looking for -more, check out [fzf.vim](https://github.com/junegunn/fzf.vim) project. - -(Note: To use fzf in GVim, an external terminal emulator is required.) - -#### `:FZF[!]` - -If you have set up fzf for Vim, `:FZF` command will be added. - -```vim -" 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](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. Refer to [the wiki page][fzf-config] for -customization. - -[fzf-config]: https://github.com/junegunn/fzf/wiki/Configuring-Vim-plugin - -#### `fzf#run` - -For more advanced uses, you can use `fzf#run([options])` function with the -following 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 | 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` (*Neovim only*) | 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) | - -Examples can be found on [the wiki -page](https://github.com/junegunn/fzf/wiki/Examples-(vim)). - -#### `fzf#wrap` - -`fzf#wrap([name string,] [opts dict,] [fullscreen boolean])` is a helper -function that decorates the options dictionary so that it understands -`g:fzf_layout`, `g:fzf_action`, `g:fzf_colors`, and `g:fzf_history_dir` like -`:FZF`. - -```vim -command! -bang MyStuff - \ call fzf#run(fzf#wrap('my-stuff', {'dir': '~/my-stuff'}, <bang>0)) -``` +See [README-VIM.md](README-VIM.md). Tips ---- diff --git a/doc/fzf.txt b/doc/fzf.txt new file mode 100644 index 00000000..447e1fad --- /dev/null +++ b/doc/fzf.txt @@ -0,0 +1,177 @@ +fzf.txt fzf Last change: April 1 2017 +FZF - TABLE OF CONTENTS *fzf* *fzf-toc* +============================================================================== + + FZF Vim integration + :FZF[!] + Configuration + Examples + fzf#run + fzf#wrap + GVim + 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_launcher* + *g:Fzf_launcher* + + - `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 (tmux pane or Neovim split) + - `g:fzf_colors` + - Customizes fzf colors to match the current color scheme + - `g:fzf_history_dir` + - Enables history feature + - `g:fzf_launcher` + - (Only in GVim) Terminal emulator to open fzf with + - `g:Fzf_launcher` for function reference + + +Examples~ + *fzf-examples* +> + " This is the default extra key bindings + let g:fzf_action = { + \ 'ctrl-t': 'tab split', + \ 'ctrl-x': 'split', + \ 'ctrl-v': 'vsplit' } + + " Default fzf layout + " - down / up / left / right + let g:fzf_layout = { 'down': '~40%' } + + " In Neovim, you can set up fzf window using a Vim command + let g:fzf_layout = { 'window': 'enew' } + let g:fzf_layout = { 'window': '-tabnew' } + + " This will split only under the current window. + let g:fzf_layout = { 'window': '10 split | enew'} + + " 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'], + \ '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 with the +following 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 | 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` (Neovim only) | 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) + ---------------------------+---------------+-------------------------------------------------------------- + + +FZF#WRAP *fzf#wrap* +============================================================================== + +`fzf#wrap([name string,] [opts dict,] [fullscreen boolean])` is a helper +function that decorates the options dictionary so that it understands +`g:fzf_layout`, `g:fzf_action`, `g:fzf_colors`, and `g:fzf_history_dir` like +`:FZF`. +> + command! -bang MyStuff + \ call fzf#run(fzf#wrap('my-stuff', {'dir': '~/my-stuff'}, <bang>0)) +< + +GVIM *fzf-gvim* +============================================================================== + +In GVim, you need an external terminal emulator to start fzf with. `xterm` +command is used by default, but you can customize it with `g:fzf_launcher`. +> + " This is the default. %s is replaced with fzf command + let g:fzf_launcher = 'xterm -e bash -ic %s' + + " Use urxvt instead + let g:fzf_launcher = 'urxvt -geometry 120x30 -e sh -c %s' +< +If you're running MacVim on OSX, I recommend you to use iTerm2 as the +launcher. Refer to the {this wiki page}{3} to see how to set up. + + {3} https://github.com/junegunn/fzf/wiki/On-MacVim-with-iTerm2 + + +LICENSE *fzf-license* +============================================================================== + +The MIT License (MIT) + +Copyright (c) 2017 Junegunn Choi + +============================================================================== +vim:tw=78:sw=2:ts=2:ft=help:norl:nowrap: |