2013-10-23 23:25:19 -04:00
|
|
|
fzf - Fuzzy finder for your shell
|
|
|
|
=================================
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
fzf is a general-purpose fuzzy finder for your shell.
|
|
|
|
|
2013-10-29 09:14:11 -04:00
|
|
|
![](https://raw.github.com/junegunn/i/master/fzf.gif)
|
2013-10-28 02:50:46 -04:00
|
|
|
|
2013-10-23 23:25:19 -04:00
|
|
|
It was heavily inspired by [ctrlp.vim](https://github.com/kien/ctrlp.vim) and
|
|
|
|
the likes.
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
Requirements
|
|
|
|
------------
|
|
|
|
|
2013-12-25 11:15:46 -05:00
|
|
|
fzf requires Ruby (>= 1.8.5).
|
|
|
|
|
2013-10-22 21:26:55 -04:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
2013-11-19 11:29:36 -05:00
|
|
|
Clone this repository and run
|
2013-10-22 21:26:55 -04:00
|
|
|
[install](https://github.com/junegunn/fzf/blob/master/install) script.
|
|
|
|
|
|
|
|
```sh
|
2013-11-19 11:29:36 -05:00
|
|
|
git clone https://github.com/junegunn/fzf.git ~/.fzf
|
|
|
|
~/.fzf/install
|
2013-10-22 21:26:55 -04:00
|
|
|
```
|
|
|
|
|
2014-01-14 02:51:52 -05:00
|
|
|
The script will setup:
|
2013-11-19 11:29:36 -05:00
|
|
|
|
2014-01-14 02:51:52 -05:00
|
|
|
- `fzf` executable
|
2014-03-13 02:28:01 -04:00
|
|
|
- Key bindings (`CTRL-T`, `CTRL-R`, and `ALT-C`) for bash and zsh
|
2014-01-14 02:51:52 -05:00
|
|
|
- Fuzzy auto-completion for bash
|
2013-10-22 21:26:55 -04:00
|
|
|
|
2013-10-31 12:12:46 -04:00
|
|
|
### Install as Vim plugin
|
2013-10-22 21:26:55 -04:00
|
|
|
|
2014-03-03 21:25:50 -05:00
|
|
|
Once you have cloned the repository, add the following line to your .vimrc.
|
2013-10-22 21:26:55 -04:00
|
|
|
|
2014-03-03 21:25:50 -05:00
|
|
|
```vim
|
|
|
|
set rtp+=~/.fzf
|
|
|
|
```
|
2013-10-22 21:26:55 -04:00
|
|
|
|
2014-03-03 21:25:50 -05:00
|
|
|
Or you may use any Vim plugin manager, such as
|
|
|
|
[vim-plug](https://github.com/junegunn/vim-plug).
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2013-10-25 05:31:16 -04:00
|
|
|
```
|
|
|
|
usage: fzf [options]
|
|
|
|
|
2014-01-21 22:03:17 -05:00
|
|
|
Options
|
|
|
|
-m, --multi Enable multi-select
|
|
|
|
-x, --extended Extended-search mode
|
2014-03-04 07:29:45 -05:00
|
|
|
-e, --extended-exact Extended-search mode (exact match)
|
2014-01-21 22:03:17 -05:00
|
|
|
-q, --query=STR Initial query
|
2014-02-01 11:45:44 -05:00
|
|
|
-f, --filter=STR Filter mode. Do not start interactive finder.
|
2014-01-21 22:03:17 -05:00
|
|
|
-s, --sort=MAX Maximum number of matched items to sort (default: 1000)
|
|
|
|
+s, --no-sort Do not sort the result. Keep the sequence unchanged.
|
|
|
|
-i Case-insensitive match (default: smart-case match)
|
|
|
|
+i Case-sensitive match
|
|
|
|
+c, --no-color Disable colors
|
2014-03-07 03:32:14 -05:00
|
|
|
+2, --no-256 Disable 256-color
|
2014-03-08 14:06:12 -05:00
|
|
|
--black Use black background
|
2014-03-06 06:52:38 -05:00
|
|
|
--no-mouse Disable mouse
|
2014-01-21 22:03:17 -05:00
|
|
|
|
|
|
|
Environment variables
|
|
|
|
FZF_DEFAULT_COMMAND Default command to use when input is tty
|
|
|
|
FZF_DEFAULT_OPTS Defaults options. (e.g. "-x -m --sort 10000")
|
2013-10-25 05:31:16 -04:00
|
|
|
```
|
|
|
|
|
2013-10-22 21:26:55 -04:00
|
|
|
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-01 23:56:43 -04:00
|
|
|
files excluding hidden ones. (You can override the default command with
|
|
|
|
`FZF_DEFAULT_COMMAND`)
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
```sh
|
2013-11-06 06:54:02 -05:00
|
|
|
vim $(fzf)
|
2013-10-22 21:26:55 -04:00
|
|
|
```
|
|
|
|
|
2013-10-25 05:31:16 -04:00
|
|
|
If you want to preserve the exact sequence of the input, provide `--no-sort` (or
|
|
|
|
`+s`) option.
|
2013-10-24 05:56:33 -04:00
|
|
|
|
|
|
|
```sh
|
2013-10-25 05:31:16 -04:00
|
|
|
history | fzf +s
|
2013-10-24 05:56:33 -04:00
|
|
|
```
|
|
|
|
|
2013-10-22 21:26:55 -04:00
|
|
|
### Key binding
|
|
|
|
|
|
|
|
Use CTRL-J and CTRL-K (or CTRL-N and CTRL-P) to change the selection, press
|
2013-11-20 07:18:51 -05:00
|
|
|
enter key to select the item. CTRL-C, CTRL-G, or ESC will terminate the finder.
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
The following readline key bindings should also work as expected.
|
|
|
|
|
|
|
|
- CTRL-A / CTRL-E
|
|
|
|
- CTRL-B / CTRL-F
|
|
|
|
- CTRL-W / CTRL-U
|
2013-11-16 11:19:16 -05:00
|
|
|
- ALT-B / ALT-F
|
2013-10-22 21:26:55 -04:00
|
|
|
|
2013-11-09 13:56:18 -05:00
|
|
|
If you enable multi-select mode with `-m` option, you can select multiple items
|
2013-11-10 06:19:57 -05:00
|
|
|
with TAB or Shift-TAB key.
|
2013-11-09 13:56:18 -05:00
|
|
|
|
2014-03-07 03:30:44 -05:00
|
|
|
You can also use mouse. Double-click on an item to select it or shift-click (or
|
|
|
|
ctrl-click) to select multiple items. Use mouse wheel to move the cursor up and
|
|
|
|
down.
|
2014-03-06 06:52:38 -05:00
|
|
|
|
2013-11-15 12:21:39 -05:00
|
|
|
### Extended-search mode
|
2013-11-15 06:40:57 -05:00
|
|
|
|
2013-11-15 12:21:39 -05:00
|
|
|
With `-x` or `--extended` option, fzf will start in "extended-search mode".
|
2013-11-15 06:40:57 -05:00
|
|
|
|
2013-11-15 12:21:39 -05:00
|
|
|
In this mode, you can specify multiple patterns delimited by spaces,
|
|
|
|
such as: `^music .mp3$ sbtrkt !rmx`
|
2013-11-15 06:40:57 -05:00
|
|
|
|
2013-11-15 11:55:33 -05: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 |
|
2013-11-15 06:40:57 -05:00
|
|
|
|
2014-03-04 07:29:45 -05:00
|
|
|
If you don't need fuzzy matching and do not wish to "quote" every word, start
|
|
|
|
fzf with `-e` or `--extended-exact` option.
|
|
|
|
|
2013-12-21 10:18:41 -05:00
|
|
|
Useful examples
|
|
|
|
---------------
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
```sh
|
|
|
|
# vimf - Open selected file in Vim
|
2013-10-24 11:40:04 -04:00
|
|
|
vimf() {
|
2014-03-14 04:46:55 -04:00
|
|
|
local file
|
|
|
|
file=$(fzf) && vim "$file"
|
2013-10-24 11:40:04 -04:00
|
|
|
}
|
2013-10-22 21:26:55 -04:00
|
|
|
|
|
|
|
# fd - cd to selected directory
|
|
|
|
fd() {
|
2014-03-14 04:46:55 -04:00
|
|
|
local dir
|
2014-03-14 04:53:23 -04:00
|
|
|
dir=$(find ${1:-*} -path '*/\.*' -prune \
|
|
|
|
-o -type d -print 2> /dev/null | fzf +m) &&
|
|
|
|
cd "$dir"
|
2013-10-22 21:26:55 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
# fda - including hidden directories
|
|
|
|
fda() {
|
2014-03-14 04:46:55 -04:00
|
|
|
local dir
|
2014-03-14 04:53:23 -04:00
|
|
|
dir=$(find ${1:-.} -type d 2> /dev/null | fzf +m) && cd "$dir"
|
2013-10-22 21:26:55 -04:00
|
|
|
}
|
|
|
|
|
2013-10-24 05:56:33 -04:00
|
|
|
# fh - repeat history
|
|
|
|
fh() {
|
2013-10-25 05:31:16 -04:00
|
|
|
eval $(history | fzf +s | sed 's/ *[0-9]* *//')
|
2013-10-24 05:56:33 -04:00
|
|
|
}
|
|
|
|
|
|
|
|
# fkill - kill process
|
|
|
|
fkill() {
|
2013-11-09 14:00:27 -05:00
|
|
|
ps -ef | sed 1d | fzf -m | awk '{print $2}' | xargs kill -${1:-9}
|
2013-10-24 05:56:33 -04:00
|
|
|
}
|
2014-03-14 04:46:55 -04:00
|
|
|
|
|
|
|
# fbr - checkout git branch
|
|
|
|
fbr() {
|
|
|
|
local branches branch
|
|
|
|
branches=$(git branch) &&
|
|
|
|
branch=$(echo "$branches" | fzf +s +m) &&
|
|
|
|
git checkout $(echo "$branch" | sed "s/.* //")
|
|
|
|
}
|
|
|
|
|
|
|
|
# fbr - checkout git commit
|
|
|
|
fco() {
|
|
|
|
local commits commit
|
|
|
|
commits=$(git log --pretty=oneline --abbrev-commit) &&
|
|
|
|
commit=$(echo "$commits" | fzf +s +m -e) &&
|
|
|
|
git checkout $(echo "$commit" | sed "s/ .*//")
|
|
|
|
}
|
2013-11-26 11:00:23 -05:00
|
|
|
```
|
2013-10-24 05:56:33 -04:00
|
|
|
|
2013-12-21 10:22:23 -05:00
|
|
|
Key bindings for command line
|
|
|
|
-----------------------------
|
2013-12-21 10:18:41 -05:00
|
|
|
|
2014-01-14 02:51:52 -05:00
|
|
|
The install script will setup the following key bindings.
|
2013-12-21 10:18:41 -05:00
|
|
|
|
2014-03-13 01:29:27 -04:00
|
|
|
### bash/zsh
|
2013-12-21 10:18:41 -05:00
|
|
|
|
|
|
|
- `CTRL-T` - Paste the selected file path(s) into the command line
|
|
|
|
- `CTRL-R` - Paste the selected command from history into the command line
|
|
|
|
- `ALT-C` - cd into the selected directory
|
2013-11-08 11:16:39 -05:00
|
|
|
|
2014-03-13 01:29:27 -04:00
|
|
|
The source code can be found in `~/.fzf.bash` and in `~/.fzf.zsh`.
|
2013-11-08 11:16:39 -05:00
|
|
|
|
2013-12-14 08:29:57 -05:00
|
|
|
Auto-completion
|
|
|
|
---------------
|
2013-11-19 11:29:36 -05:00
|
|
|
|
|
|
|
Disclaimer: *Auto-completion feature is currently experimental, it can change
|
|
|
|
over time*
|
|
|
|
|
|
|
|
### bash
|
|
|
|
|
2013-11-29 04:08:22 -05:00
|
|
|
#### Files and directories
|
|
|
|
|
2013-11-29 03:49:48 -05: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 `**`.
|
2013-11-23 06:09:56 -05:00
|
|
|
|
|
|
|
- `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>`
|
2013-11-19 11:29:36 -05:00
|
|
|
|
|
|
|
```sh
|
2013-11-19 11:42:57 -05:00
|
|
|
# Files under current directory
|
|
|
|
# - You can select multiple items with TAB key
|
2013-11-19 11:29:36 -05:00
|
|
|
vim **<TAB>
|
2013-11-19 11:42:57 -05:00
|
|
|
|
|
|
|
# Files under parent directory
|
2013-11-23 06:09:56 -05:00
|
|
|
vim ../**<TAB>
|
|
|
|
|
|
|
|
# Files under parent directory that match `fzf`
|
|
|
|
vim ../fzf**<TAB>
|
2013-11-19 11:42:57 -05:00
|
|
|
|
|
|
|
# Files under your home directory
|
2013-11-19 11:29:36 -05:00
|
|
|
vim ~/**<TAB>
|
|
|
|
|
2013-11-19 11:42:57 -05:00
|
|
|
|
|
|
|
# Directories under current directory (single-selection)
|
2013-11-19 11:29:36 -05:00
|
|
|
cd **<TAB>
|
2013-11-19 11:42:57 -05:00
|
|
|
|
2013-11-23 06:09:56 -05:00
|
|
|
# Directories under ~/github that match `fzf`
|
|
|
|
cd ~/github/fzf**<TAB>
|
2013-11-19 11:29:36 -05:00
|
|
|
```
|
|
|
|
|
2013-11-29 04:08:22 -05:00
|
|
|
#### Process IDs
|
|
|
|
|
|
|
|
Fuzzy completion for PIDs is provided for kill command. In this case
|
2013-11-29 03:49:48 -05: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>
|
|
|
|
```
|
|
|
|
|
2013-11-29 04:08:22 -05:00
|
|
|
#### Host names
|
|
|
|
|
2013-11-29 04:09:51 -05:00
|
|
|
For ssh and telnet commands, fuzzy completion for host names is provided. The
|
2013-12-23 09:16:07 -05:00
|
|
|
names are extracted from /etc/hosts and ~/.ssh/config.
|
2013-11-29 04:08:22 -05:00
|
|
|
|
|
|
|
```sh
|
2013-12-23 09:16:07 -05:00
|
|
|
ssh **<TAB>
|
|
|
|
telnet **<TAB>
|
2013-11-29 04:08:22 -05:00
|
|
|
```
|
|
|
|
|
2013-11-19 11:42:57 -05:00
|
|
|
#### Settings
|
2013-11-19 11:29:36 -05:00
|
|
|
|
|
|
|
```sh
|
2013-11-19 11:42:57 -05:00
|
|
|
# Use ~~ as the trigger sequence instead of the default **
|
2013-11-19 11:29:36 -05:00
|
|
|
export FZF_COMPLETION_TRIGGER='~~'
|
2013-11-19 11:42:57 -05:00
|
|
|
|
|
|
|
# Options to fzf command
|
|
|
|
export FZF_COMPLETION_OPTS='+c -x'
|
2013-11-19 11:29:36 -05:00
|
|
|
```
|
|
|
|
|
|
|
|
### zsh
|
|
|
|
|
2013-11-19 11:42:57 -05:00
|
|
|
TODO :smiley:
|
|
|
|
|
|
|
|
(Pull requests are appreciated.)
|
2013-11-19 11:29:36 -05:00
|
|
|
|
2014-01-07 03:07:02 -05:00
|
|
|
Usage as Vim plugin
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
If you install fzf as a Vim plugin, `: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 -m /tmp
|
|
|
|
```
|
|
|
|
|
|
|
|
You can override the source command which produces input to fzf.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:fzf_source = 'find . -type f'
|
|
|
|
```
|
|
|
|
|
|
|
|
And you can predefine default options to fzf command.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:fzf_options = '--no-color --extended'
|
|
|
|
```
|
|
|
|
|
|
|
|
For more advanced uses, you can call `fzf#run` function as follows.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
:call fzf#run('tabedit', '-m +c')
|
|
|
|
```
|
|
|
|
|
|
|
|
Most of the time, you will prefer native Vim plugins with better integration
|
|
|
|
with Vim. The only reason one might consider using fzf in Vim is its speed. For
|
|
|
|
a very large list of files, fzf is significantly faster and it does not block.
|
|
|
|
|
2013-11-10 05:51:32 -05:00
|
|
|
Tips
|
|
|
|
----
|
|
|
|
|
2014-03-08 20:43:59 -05:00
|
|
|
### Rendering issues
|
|
|
|
|
|
|
|
If you have any rendering issues, check the followings:
|
|
|
|
|
|
|
|
1. Make sure `$TERM` is correctly set. fzf will use 256-color only if it
|
|
|
|
contains `256` (e.g. `xterm-256color`)
|
2014-03-08 21:52:35 -05:00
|
|
|
2. If you're on screen or tmux, `$TERM` should be either `screen` or
|
2014-03-08 20:43:59 -05:00
|
|
|
`screen-256color`
|
|
|
|
3. Some terminal emulators (e.g. mintty) have problem displaying default
|
|
|
|
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.
|
|
|
|
4. If you still have problem, try `--no-256` option or even `--no-color`.
|
|
|
|
5. Ruby 1.9 or above is required for correctly displaying unicode characters.
|
2013-11-10 05:51:32 -05:00
|
|
|
|
2013-12-21 10:22:23 -05:00
|
|
|
### Ranking algorithm
|
|
|
|
|
|
|
|
fzf sorts the result first by the length of the matched substring, then by the
|
|
|
|
length of the whole string. However it only does so when the number of matches
|
|
|
|
is less than the limit which is by default 1000, in order to avoid the cost of
|
|
|
|
sorting a large list and limit the response time of the query.
|
|
|
|
|
|
|
|
This limit can be adjusted with `-s` option, or with the environment variable
|
2014-01-21 22:03:17 -05:00
|
|
|
`FZF_DEFAULT_OPTS`.
|
2013-12-21 10:22:23 -05:00
|
|
|
|
|
|
|
```sh
|
2014-01-21 22:03:17 -05:00
|
|
|
export FZF_DEFAULT_OPTS="--sort 20000"
|
2013-12-21 10:22:23 -05:00
|
|
|
```
|
|
|
|
|
2013-10-22 21:26:55 -04:00
|
|
|
License
|
|
|
|
-------
|
|
|
|
|
|
|
|
MIT
|
|
|
|
|
|
|
|
Author
|
|
|
|
------
|
|
|
|
|
|
|
|
Junegunn Choi
|
|
|
|
|