mirror of
https://github.com/junegunn/fzf.vim.git
synced 2025-12-29 15:26:54 +08:00
dd97e412a5
In my environment '--graph' is a kiss of death. It results in seeing nothing but graph lines due to the number of branches in flight. Secondly the colors baked into this break with my color scheme which has a background of black rending the date unreadable. So to solve this I need to be able to specify my own options, so add a new options g:fzf_commits_log_options to allow this.
205 lines
8.3 KiB
Markdown
205 lines
8.3 KiB
Markdown
fzf :heart: vim
|
|
===============
|
|
|
|
Things you can do with [fzf][fzf] and Vim.
|
|
|
|
Rationale
|
|
---------
|
|
|
|
[fzf][fzf] in itself is not a Vim plugin, and the official repository only
|
|
provides the [basic wrapper function][run] for Vim and it's up to the users to
|
|
write their own Vim commands with it. However, I've learned that many users of
|
|
fzf are not familiar with Vimscript and are looking for the "default"
|
|
implementation of the features they can find in the alternative Vim plugins.
|
|
|
|
This repository is a bundle of fzf-based commands and mappings extracted from
|
|
my [.vimrc][vimrc] to address such needs. They are *not* designed to be
|
|
flexible or configurable, and there's no guarantee of backward-compatibility.
|
|
|
|
Why you should use fzf on Vim
|
|
-----------------------------
|
|
|
|
Because you can and you love fzf.
|
|
|
|
fzf runs asynchronously and can be orders of magnitude faster than similar Vim
|
|
plugins. However, the benefit may not be noticeable if the size of the input
|
|
is small, which is the case for many of the commands provided here.
|
|
Nevertheless I wrote them anyway since it's really easy to implement custom
|
|
selector with fzf.
|
|
|
|
fzf is an independent command-line program and thus requires an external
|
|
terminal emulator when on GVim. You may or may not like the experience. Also
|
|
note that fzf currently does not compile on Windows.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Using [vim-plug](https://github.com/junegunn/vim-plug):
|
|
|
|
```vim
|
|
Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }
|
|
Plug 'junegunn/fzf.vim'
|
|
```
|
|
|
|
Make sure to use the latest version of fzf and Vim 7.4 or above.
|
|
|
|
Commands
|
|
--------
|
|
|
|
| Command | List |
|
|
| --- | --- |
|
|
| `Files [PATH]` | Files (similar to `:FZF`) |
|
|
| `GitFiles` | Git files
|
|
| `Buffers` | Open buffers |
|
|
| `Colors` | Color schemes |
|
|
| `Ag [PATTERN]` | [ag][ag] search result (`ALT-A` to select all, `ALT-D` to deselect all) |
|
|
| `Lines` | Lines in loaded buffers |
|
|
| `BLines` | Lines in the current buffer |
|
|
| `Tags` | Tags in the project (`ctags -R`) |
|
|
| `BTags` | Tags in the current buffer |
|
|
| `Marks` | Marks |
|
|
| `Windows` | Windows |
|
|
| `Locate PATTERN` | `locate` command output |
|
|
| `History` | `v:oldfiles` and open buffers |
|
|
| `History:` | Command history |
|
|
| `History/` | Search history |
|
|
| `Snippets` | Snippets ([UltiSnips][us]) |
|
|
| `Commits` | Git commits (requires [fugitive.vim][f]) |
|
|
| `BCommits` | Git commits for the current buffer |
|
|
| `Commands` | Commands |
|
|
| `Maps` | Normal mode mappings |
|
|
| `Helptags` | Help tags <sup id="a1">[1](#helptags)</sup> |
|
|
|
|
- Most commands support `CTRL-T` / `CTRL-X` / `CTRL-V` key
|
|
bindings to open in a new tab, a new split, or in a new vertical split
|
|
- Bang-versions of the commands (e.g. `Ag!`) will open fzf in fullscreen
|
|
- You can set `g:fzf_command_prefix` to give the same prefix to the commands
|
|
- e.g. `let g:fzf_command_prefix = 'Fzf'` and you have `FzfFiles`, etc.
|
|
|
|
(<a name="helptags">1</a>: `Helptags` will shadow the command of the same name
|
|
from [pathogen][pat]. But its functionality is still available via `call
|
|
pathogen#helptags()`. [↩](#a1))
|
|
|
|
[pat]: https://github.com/tpope/vim-pathogen
|
|
[f]: https://github.com/tpope/vim-fugitive
|
|
|
|
### Customization
|
|
|
|
```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
|
|
" - window (nvim only)
|
|
let g:fzf_layout = { 'down': '~40%' }
|
|
|
|
" For Commits and BCommits to customize the options used by 'git log':
|
|
let g:fzf_commits_log_options = '--graph --color=always --format="%C(auto)%h%d %s %C(black)%C(bold)%cr"'
|
|
|
|
" Advanced customization using autoload functions
|
|
autocmd VimEnter * command! Colors
|
|
\ call fzf#vim#colors({'left': '15%', 'options': '--reverse --margin 30%,0'})
|
|
```
|
|
|
|
Mappings
|
|
--------
|
|
|
|
| Mapping | Description |
|
|
| --- | --- |
|
|
| `<plug>(fzf-maps-n)` | Normal mode mappings |
|
|
| `<plug>(fzf-maps-i)` | Insert mode mappings |
|
|
| `<plug>(fzf-maps-x)` | Visual mode mappings |
|
|
| `<plug>(fzf-maps-o)` | Operator-pending mappings |
|
|
| `<plug>(fzf-complete-word)` | `cat /usr/share/dict/words` |
|
|
| `<plug>(fzf-complete-path)` | Path completion using `find` (file + dir) |
|
|
| `<plug>(fzf-complete-file)` | File completion using `find` |
|
|
| `<plug>(fzf-complete-file-ag)` | File completion using `ag` |
|
|
| `<plug>(fzf-complete-line)` | Line completion (all open buffers) |
|
|
| `<plug>(fzf-complete-buffer-line)` | Line completion (current buffer only) |
|
|
|
|
### Usage
|
|
|
|
```vim
|
|
" Mapping selecting mappings
|
|
nmap <leader><tab> <plug>(fzf-maps-n)
|
|
xmap <leader><tab> <plug>(fzf-maps-x)
|
|
omap <leader><tab> <plug>(fzf-maps-o)
|
|
|
|
" Insert mode completion
|
|
imap <c-x><c-k> <plug>(fzf-complete-word)
|
|
imap <c-x><c-f> <plug>(fzf-complete-path)
|
|
imap <c-x><c-j> <plug>(fzf-complete-file-ag)
|
|
imap <c-x><c-l> <plug>(fzf-complete-line)
|
|
|
|
" Advanced customization using autoload functions
|
|
inoremap <expr> <c-x><c-k> fzf#vim#complete#word({'left': '15%'})
|
|
```
|
|
|
|
### Completion helper
|
|
|
|
`fzf#complete` is a helper function for creating custom fuzzy completion using
|
|
fzf. If the first parameter is a command string or a Vim list, it will be used
|
|
as the source.
|
|
|
|
```vim
|
|
" Replace the default dictionary completion with fzf-based fuzzy completion
|
|
inoremap <expr> <c-x><c-k> fzf#complete('cat /usr/share/dict/words')
|
|
```
|
|
|
|
For advanced uses, you can pass an options dictionary to the function. The set
|
|
of options is pretty much identical to that for `fzf#run` only with the
|
|
following exceptions:
|
|
|
|
- `reducer` (funcref)
|
|
- Reducer transforms the output lines of fzf into a single string value
|
|
- `prefix` (string or funcref; default: `\k*$`)
|
|
- Regular expression pattern to extract the completion prefix
|
|
- Or a function to extract completion prefix
|
|
- Both `source` and `options` can be given as funcrefs that take the
|
|
completion prefix as the argument and return the final value
|
|
- `sink` or `sink*` are not allowed
|
|
|
|
#### Reducer example
|
|
|
|
```vim
|
|
function! s:make_sentence(lines)
|
|
return substitute(join(a:lines), '^.', '\=toupper(submatch(0))', '').'.'
|
|
endfunction
|
|
|
|
inoremap <expr> <c-x><c-s> fzf#complete({
|
|
\ 'source': 'cat /usr/share/dict/words',
|
|
\ 'reducer': function('<sid>make_sentence'),
|
|
\ 'options': '--multi --reverse --margin 15%,0',
|
|
\ 'left': 20})
|
|
```
|
|
|
|
Status line (neovim)
|
|
--------------------
|
|
|
|
```vim
|
|
function! s:fzf_statusline()
|
|
" Override statusline as you like
|
|
highlight fzf1 ctermfg=161 ctermbg=251
|
|
highlight fzf2 ctermfg=23 ctermbg=251
|
|
highlight fzf3 ctermfg=237 ctermbg=251
|
|
setlocal statusline=%#fzf1#\ >\ %#fzf2#fz%#fzf3#f
|
|
endfunction
|
|
|
|
autocmd! User FzfStatusLine call <SID>fzf_statusline()
|
|
```
|
|
|
|
License
|
|
-------
|
|
|
|
MIT
|
|
|
|
[fzf]: https://github.com/junegunn/fzf
|
|
[run]: https://github.com/junegunn/fzf#usage-as-vim-plugin
|
|
[vimrc]: https://github.com/junegunn/dotfiles/blob/master/vimrc
|
|
[ag]: https://github.com/ggreer/the_silver_searcher
|
|
[us]: https://github.com/SirVer/ultisnips
|