fzf/README.md

434 lines
13 KiB
Markdown
Raw Normal View History

2015-04-11 15:44:41 +00:00
<img src="https://raw.githubusercontent.com/junegunn/i/master/fzf.png" height="170" alt="fzf - a command-line fuzzy finder"> [![travis-ci](https://travis-ci.org/junegunn/fzf.svg?branch=master)](https://travis-ci.org/junegunn/fzf) <a href="http://flattr.com/thing/3115381/junegunnfzf-on-GitHub" target="_blank"><img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a>
2015-03-15 17:49:09 +00:00
===
2013-10-23 01:26:55 +00:00
2015-03-15 01:57:09 +00:00
fzf is a general-purpose command-line fuzzy finder.
2013-10-23 01:26:55 +00:00
2013-10-29 13:14:11 +00:00
![](https://raw.github.com/junegunn/i/master/fzf.gif)
2013-10-28 06:50:46 +00:00
2015-03-15 01:57:09 +00:00
Pros
----
- No dependency
- Blazingly fast
- e.g. `locate / | fzf`
- Flexible layout
- Runs in fullscreen or in horizontal/vertical split using tmux
- The most comprehensive feature set
- Try `fzf --help` and be surprised
- Batteries included
2015-04-11 15:44:41 +00:00
- Vim/Neovim plugin, key bindings and fuzzy auto-completion
2013-10-23 01:26:55 +00:00
Installation
------------
2015-02-17 04:15:16 +00:00
fzf project consists of the followings:
- `fzf` executable
- `fzf-tmux` script for launching fzf in a tmux pane
2015-02-17 04:15:16 +00:00
- Shell extensions
- Key bindings (`CTRL-T`, `CTRL-R`, and `ALT-C`) (bash, zsh, fish)
2015-03-06 09:57:36 +00:00
- Fuzzy auto-completion (bash only)
2015-04-11 02:28:30 +00:00
- Vim/Neovim plugin
2015-02-17 04:15:16 +00:00
You can [download fzf executable][bin] alone, but it's recommended that you
install the extra stuff using the attached install script.
[bin]: https://github.com/junegunn/fzf-bin/releases
2015-03-06 09:57:36 +00:00
#### Using git (recommended)
2015-02-17 04:15:16 +00:00
Clone this repository and run
2013-10-23 01:26:55 +00:00
[install](https://github.com/junegunn/fzf/blob/master/install) script.
```sh
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install
2013-10-23 01:26:55 +00:00
```
2015-03-06 09:57:36 +00:00
#### Using Homebrew
2015-02-17 04:15:16 +00:00
On OS X, you can use [Homebrew](http://brew.sh/) to install fzf.
2015-02-17 04:15:16 +00:00
```sh
2015-04-02 16:21:50 +00:00
brew reinstall --HEAD fzf
2013-10-23 01:26:55 +00:00
2015-04-02 16:21:50 +00:00
# Install shell extensions
/usr/local/Cellar/fzf/HEAD/install
2015-02-17 04:15:16 +00:00
```
2014-03-31 01:15:38 +00:00
2015-03-06 09:57:36 +00:00
#### Install as Vim plugin
2013-10-23 01:26:55 +00:00
2014-03-04 02:25:50 +00:00
Once you have cloned the repository, add the following line to your .vimrc.
2013-10-23 01:26:55 +00:00
2014-03-04 02:25:50 +00:00
```vim
set rtp+=~/.fzf
```
2013-10-23 01:26:55 +00:00
2015-03-06 09:57:36 +00:00
Or you can have [vim-plug](https://github.com/junegunn/vim-plug) manage fzf
(recommended):
2014-09-02 04:06:05 +00:00
```vim
Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': 'yes \| ./install' }
```
2013-10-23 01:26:55 +00:00
2015-03-11 06:07:34 +00:00
#### Upgrading fzf
fzf is being actively developed and you might want to upgrade it once in a
while. Please follow the instruction below depending on the installation
method.
- git: `cd ~/.fzf && git pull && ./install`
2015-04-11 15:44:41 +00:00
- brew: `brew reinstall --HEAD fzf`
2015-03-11 06:07:34 +00:00
- vim-plug: `:PlugUpdate fzf`
2013-10-23 01:26:55 +00:00
Usage
-----
fzf will launch curses-based finder, read the list from STDIN, and write the
selected item to STDOUT.
```sh
find * -type f | fzf > selected
```
Without STDIN pipe, fzf will use find command to fetch the list of
2013-11-02 03:56:43 +00:00
files excluding hidden ones. (You can override the default command with
`FZF_DEFAULT_COMMAND`)
2013-10-23 01:26:55 +00:00
```sh
vim $(fzf)
2013-10-23 01:26:55 +00:00
```
2015-03-06 09:57:36 +00:00
#### Using the finder
2013-11-09 18:56:18 +00:00
2015-03-06 09:57:36 +00:00
- `CTRL-J` / `CTRL-K` (or `CTRL-N` / `CTRL-P)` to move cursor up and down
- `Enter` key to select the item, `CTRL-C` / `CTRL-G` / `ESC` to exit
- On multi-select mode (`-m`), `TAB` and `Shift-TAB` to mark multiple items
- Emacs style key bindings
- Mouse: scroll, click, double-click; shift-click and shift-scroll on
multi-select mode
2015-03-06 09:57:36 +00:00
#### Extended-search mode
2013-11-15 17:21:39 +00:00
With `-x` or `--extended` option, fzf will start in "extended-search mode".
2013-11-15 17:21:39 +00:00
In this mode, you can specify multiple patterns delimited by spaces,
such as: `^music .mp3$ sbtrkt !rmx`
2013-11-15 16:55:33 +00:00
| Token | Description | Match type |
| -------- | -------------------------------- | -------------------- |
| `^music` | Items that start with `music` | prefix-exact-match |
| `.mp3$` | Items that end with `.mp3` | suffix-exact-match |
| `sbtrkt` | Items that match `sbtrkt` | fuzzy-match |
| `!rmx` | Items that do not match `rmx` | inverse-fuzzy-match |
| `'wild` | Items that include `wild` | exact-match (quoted) |
| `!'fire` | Items that do not include `fire` | inverse-exact-match |
If you don't need fuzzy matching and do not wish to "quote" every word, start
fzf with `-e` or `--extended-exact` option.
2015-03-06 09:57:36 +00:00
Examples
--------
2013-10-23 01:26:55 +00:00
2015-03-06 09:57:36 +00:00
Many useful examples can be found on [the wiki
page](https://github.com/junegunn/fzf/wiki/examples). Feel free to add your
own as well.
2014-05-02 14:38:36 +00:00
2013-12-21 15:22:23 +00:00
Key bindings for command line
-----------------------------
The install script will setup the following key bindings for bash, zsh, and
fish.
- `CTRL-T` - Paste the selected file path(s) into the command line
- `CTRL-R` - Paste the selected command from history into the command line
2015-04-11 15:44:41 +00:00
- Sort is disabled by default to respect chronological ordering
- Press `CTRL-R` again to toggle sort
- `ALT-C` - cd into the selected directory
2013-11-08 16:16:39 +00:00
2015-04-21 17:07:27 +00:00
If you're on a tmux session, fzf will start in a split pane. You may disable
this tmux integration by setting `FZF_TMUX` to 0, or change the height of the
pane with `FZF_TMUX_HEIGHT` (e.g. `20`, `50%`).
If you use vi mode on bash, you need to add `set -o vi` *before* `source
~/.fzf.bash` in your .bashrc, so that it correctly sets up key bindings for vi
mode.
2015-03-06 09:57:36 +00:00
`fzf-tmux` script
-----------------
[fzf-tmux](bin/fzf-tmux) is a bash script that opens fzf in a tmux pane.
2015-03-06 09:57:36 +00:00
```sh
# usage: fzf-tmux [-u|-d [HEIGHT[%]]] [-l|-r [WIDTH[%]]] [--] [FZF OPTIONS]
# (-[udlr]: up/down/left/right)
2015-03-06 09:57:36 +00:00
# select git branches in horizontal split below (15 lines)
git branch | fzf-tmux -d 15
2015-03-06 09:57:36 +00:00
# select multiple words in vertical split on the left (20% of screen width)
cat /usr/share/dict/words | fzf-tmux -l 20% --multi --reverse
2015-03-06 09:57:36 +00:00
```
It will still work even when you're not on tmux, silently ignoring `-[udlr]`
options, so you can invariably use `fzf-tmux` in your scripts.
2015-03-06 09:57:36 +00:00
Fuzzy completion for bash
-------------------------
#### Files and directories
2013-11-29 08:49:48 +00:00
Fuzzy completion for files and directories can be triggered if the word before
the cursor ends with the trigger sequence which is by default `**`.
- `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>`
```sh
2013-11-19 16:42:57 +00:00
# Files under current directory
# - You can select multiple items with TAB key
vim **<TAB>
2013-11-19 16:42:57 +00:00
# Files under parent directory
vim ../**<TAB>
# Files under parent directory that match `fzf`
vim ../fzf**<TAB>
2013-11-19 16:42:57 +00:00
# Files under your home directory
vim ~/**<TAB>
2013-11-19 16:42:57 +00:00
# Directories under current directory (single-selection)
cd **<TAB>
2013-11-19 16:42:57 +00:00
# Directories under ~/github that match `fzf`
cd ~/github/fzf**<TAB>
```
#### Process IDs
Fuzzy completion for PIDs is provided for kill command. In this case
2013-11-29 08:49:48 +00:00
there is no trigger sequence, just press tab key after kill command.
```sh
# Can select multiple processes with <TAB> or <Shift-TAB> keys
kill -9 <TAB>
```
#### Host names
2013-11-29 09:09:51 +00:00
For ssh and telnet commands, fuzzy completion for host names is provided. The
names are extracted from /etc/hosts and ~/.ssh/config.
```sh
ssh **<TAB>
telnet **<TAB>
```
#### Environment variables / Aliases
```sh
unset **<TAB>
export **<TAB>
unalias **<TAB>
```
2013-11-19 16:42:57 +00:00
#### Settings
```sh
2013-11-19 16:42:57 +00:00
# Use ~~ as the trigger sequence instead of the default **
export FZF_COMPLETION_TRIGGER='~~'
2013-11-19 16:42:57 +00:00
# Options to fzf command
export FZF_COMPLETION_OPTS='+c -x'
```
2014-01-07 08:07:02 +00:00
Usage as Vim plugin
-------------------
(Note: To use fzf in GVim, an external terminal emulator is required.)
2014-03-25 10:55:52 +00:00
2015-03-06 09:57:36 +00:00
#### `:FZF[!]`
2014-03-27 15:58:07 +00:00
If you have set up fzf for Vim, `:FZF` command will be added.
2014-01-07 08:07:02 +00:00
```vim
" Look for files under current directory
:FZF
" Look for files under your home directory
:FZF ~
" With options
:FZF --no-sort -m /tmp
" Bang version starts in fullscreen instead of using tmux pane or Neovim split
:FZF!
2014-01-07 08:07:02 +00:00
```
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
2015-04-21 17:07:27 +00:00
`FZF_DEFAULT_OPTS` also apply here. Refer to [the wiki page][fzf-config] for
2015-04-15 13:52:15 +00:00
customization.
2015-04-21 17:07:27 +00:00
[fzf-config]: https://github.com/junegunn/fzf/wiki/Configuring-FZF-command-(vim)
2015-03-06 09:57:36 +00:00
#### `fzf#run([options])`
2014-03-25 10:55:52 +00:00
For more advanced uses, you can call `fzf#run()` function which returns the list
of the selected items.
`fzf#run()` may take an options-dictionary:
| 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) |
2014-03-25 10:55:52 +00:00
2015-04-11 00:21:23 +00:00
_However on Neovim `fzf#run` is asynchronous and does not return values so you
should use `sink` or `sink*` to process the output from fzf._
2015-03-06 09:57:36 +00:00
##### Examples
2014-03-25 10:55:52 +00:00
If `sink` option is not given, `fzf#run` will simply return the list.
2014-01-07 08:07:02 +00:00
```vim
2014-03-25 10:55:52 +00:00
let items = fzf#run({ 'options': '-m +c', 'dir': '~', 'source': 'ls' })
2014-01-07 08:07:02 +00:00
```
2014-03-25 10:55:52 +00:00
But if `sink` is given as a string, the command will be executed for each
selected item.
2014-01-07 08:07:02 +00:00
```vim
2014-03-25 10:55:52 +00:00
" Each selected item will be opened in a new tab
let items = fzf#run({ 'sink': 'tabe', 'options': '-m +c', 'dir': '~', 'source': 'ls' })
2014-01-07 08:07:02 +00:00
```
2014-03-25 10:55:52 +00:00
We can also use a Vim list as the source as follows:
2014-01-07 08:07:02 +00:00
```vim
2014-03-25 10:55:52 +00:00
" Choose a color scheme with fzf
2014-03-27 15:58:07 +00:00
nnoremap <silent> <Leader>C :call fzf#run({
2014-03-25 10:55:52 +00:00
\ 'source':
\ map(split(globpath(&rtp, "colors/*.vim"), "\n"),
\ "substitute(fnamemodify(v:val, ':t'), '\\..\\{-}$', '', '')"),
\ 'sink': 'colo',
\ 'options': '+m',
\ 'left': 20,
\ 'launcher': 'xterm -geometry 20x30 -e bash -ic %s'
2014-03-27 15:58:07 +00:00
\ })<CR>
2014-01-07 08:07:02 +00:00
```
2014-03-25 10:55:52 +00:00
`sink` option can be a function reference. The following example creates a
handy mapping that selects an open buffer.
```vim
" List of buffers
2015-04-11 15:44:41 +00:00
function! s:buflist()
2014-03-25 10:55:52 +00:00
redir => ls
silent ls
redir END
return split(ls, '\n')
endfunction
2015-04-11 15:44:41 +00:00
function! s:bufopen(e)
execute 'buffer' matchstr(a:e, '^[ 0-9]*')
2014-03-25 10:55:52 +00:00
endfunction
2014-03-27 15:58:07 +00:00
nnoremap <silent> <Leader><Enter> :call fzf#run({
2015-04-11 15:44:41 +00:00
\ 'source': reverse(<sid>buflist()),
\ 'sink': function('<sid>bufopen'),
\ 'options': '+m',
2015-04-11 15:44:41 +00:00
\ 'down': len(<sid>buflist()) + 2
2014-03-25 10:55:52 +00:00
\ })<CR>
```
2014-01-07 08:07:02 +00:00
2015-03-06 09:57:36 +00:00
More examples can be found on [the wiki
page](https://github.com/junegunn/fzf/wiki/Examples-(vim)).
2013-11-10 10:51:32 +00:00
Tips
----
2015-03-06 09:57:36 +00:00
#### Rendering issues
2014-03-09 01:43:59 +00:00
If you have any rendering issues, check the followings:
1. Make sure `$TERM` is correctly set. fzf will use 256-color only if it
2015-04-21 17:07:27 +00:00
contains `256` (e.g. `xterm-256color`)
2014-03-09 02:52:35 +00:00
2. If you're on screen or tmux, `$TERM` should be either `screen` or
2015-04-21 17:07:27 +00:00
`screen-256color`
2014-03-09 01:43:59 +00:00
3. Some terminal emulators (e.g. mintty) have problem displaying default
2015-04-21 17:07:27 +00:00
background color and make some text unable to read. In that case, try
`--black` option. And if it solves your problem, I recommend including it
in `FZF_DEFAULT_OPTS` for further convenience.
2014-03-09 01:43:59 +00:00
4. If you still have problem, try `--no-256` option or even `--no-color`.
2013-12-21 15:22:23 +00:00
2015-03-06 09:57:36 +00:00
#### Respecting `.gitignore`, `.hgignore`, and `svn:ignore`
2014-04-06 06:25:58 +00:00
[ag](https://github.com/ggreer/the_silver_searcher) or
[pt](https://github.com/monochromegane/the_platinum_searcher) will do the
filtering:
```sh
# Feed the output of ag into fzf
ag -l -g "" | fzf
# Setting ag as the default source for fzf
export FZF_DEFAULT_COMMAND='ag -l -g ""'
# Now fzf (w/o pipe) will use ag instead of find
fzf
```
2015-03-06 09:57:36 +00:00
#### `git ls-tree` for fast traversal
2014-05-02 03:52:06 +00:00
If you're running fzf in a large git repository, `git ls-tree` can boost up the
speed of the traversal.
```sh
export FZF_DEFAULT_COMMAND='
(git ls-tree -r --name-only HEAD ||
find * -name ".*" -prune -o -type f -print -o -type l -print) 2> /dev/null'
2014-05-02 03:52:06 +00:00
```
2015-03-06 09:57:36 +00:00
#### Fish shell
It's [a known bug of fish](https://github.com/fish-shell/fish-shell/issues/1362)
that it doesn't allow reading from STDIN in command substitution, which means
simple `vim (fzf)` won't work as expected. The workaround is to store the result
of fzf to a temporary file.
```sh
2015-04-21 17:07:27 +00:00
fzf > $TMPDIR/fzf.result; and vim (cat $TMPDIR/fzf.result)
```
2015-03-06 09:57:36 +00:00
#### Handling UTF-8 NFD paths on OSX
Use iconv to convert NFD paths to NFC:
```sh
find . | iconv -f utf-8-mac -t utf8//ignore | fzf
```
2014-04-06 06:25:58 +00:00
2013-10-23 01:26:55 +00:00
License
-------
[MIT](LICENSE)
2013-10-23 01:26:55 +00:00
Author
------
Junegunn Choi