2018-01-05 17:46:09 +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)
|
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
|
|
|
|
2017-07-23 13:07:24 +00:00
|
|
|
<img src="https://raw.githubusercontent.com/junegunn/i/master/fzf-preview.png" width=640>
|
|
|
|
|
|
|
|
It's an interactive Unix filter for command-line that can be used with any
|
|
|
|
list; files, command history, processes, hostnames, bookmarks, git commits,
|
|
|
|
etc.
|
2013-10-28 06:50:46 +00:00
|
|
|
|
2015-03-15 01:57:09 +00:00
|
|
|
Pros
|
|
|
|
----
|
|
|
|
|
2017-07-23 13:07:24 +00:00
|
|
|
- Portable, no dependencies
|
2015-03-15 01:57:09 +00:00
|
|
|
- Blazingly fast
|
|
|
|
- The most comprehensive feature set
|
2017-07-23 13:07:24 +00:00
|
|
|
- Flexible layout
|
2015-03-15 01:57:09 +00:00
|
|
|
- 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
|
|
|
|
2017-05-20 10:08:56 +00:00
|
|
|
Table of Contents
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
* [Installation](#installation)
|
2017-08-17 07:57:02 +00:00
|
|
|
* [Using Homebrew or Linuxbrew](#using-homebrew-or-linuxbrew)
|
2017-11-21 17:58:54 +00:00
|
|
|
* [Using git](#using-git)
|
2019-12-01 14:48:48 +00:00
|
|
|
* [Using Linux package managers](#using-linux-package-managers)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [Windows](#windows)
|
2019-12-05 14:03:46 +00:00
|
|
|
* [As Vim plugin](#as-vim-plugin)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [Upgrading fzf](#upgrading-fzf)
|
|
|
|
* [Building fzf](#building-fzf)
|
|
|
|
* [Usage](#usage)
|
|
|
|
* [Using the finder](#using-the-finder)
|
|
|
|
* [Layout](#layout)
|
|
|
|
* [Search syntax](#search-syntax)
|
|
|
|
* [Environment variables](#environment-variables)
|
|
|
|
* [Options](#options)
|
2019-04-18 09:49:30 +00:00
|
|
|
* [Demo](#demo)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [Examples](#examples)
|
|
|
|
* [fzf-tmux script](#fzf-tmux-script)
|
|
|
|
* [Key bindings for command line](#key-bindings-for-command-line)
|
|
|
|
* [Fuzzy completion for bash and zsh](#fuzzy-completion-for-bash-and-zsh)
|
|
|
|
* [Files and directories](#files-and-directories)
|
|
|
|
* [Process IDs](#process-ids)
|
|
|
|
* [Host names](#host-names)
|
|
|
|
* [Environment variables / Aliases](#environment-variables--aliases)
|
|
|
|
* [Settings](#settings)
|
|
|
|
* [Supported commands](#supported-commands)
|
|
|
|
* [Vim plugin](#vim-plugin)
|
2017-07-29 08:08:51 +00:00
|
|
|
* [Advanced topics](#advanced-topics)
|
|
|
|
* [Performance](#performance)
|
2017-07-29 08:10:00 +00:00
|
|
|
* [Executing external programs](#executing-external-programs)
|
2017-07-29 08:08:51 +00:00
|
|
|
* [Preview window](#preview-window)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [Tips](#tips)
|
2017-11-08 14:54:46 +00:00
|
|
|
* [Respecting .gitignore](#respecting-gitignore)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [Fish shell](#fish-shell)
|
2018-09-26 17:52:52 +00:00
|
|
|
* [Related projects](#related-projects)
|
2017-05-20 10:08:56 +00:00
|
|
|
* [<a href="LICENSE">License</a>](#license)
|
|
|
|
|
2013-10-23 01:26:55 +00:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
2016-09-12 19:11:28 +00:00
|
|
|
fzf project consists of the following components:
|
2015-02-17 04:15:16 +00:00
|
|
|
|
|
|
|
- `fzf` executable
|
2015-03-07 00:08:41 +00:00
|
|
|
- `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-05-09 11:15:14 +00:00
|
|
|
- Fuzzy auto-completion (bash, zsh)
|
2015-04-11 02:28:30 +00:00
|
|
|
- Vim/Neovim plugin
|
2015-02-17 04:15:16 +00:00
|
|
|
|
2016-09-12 19:11:28 +00:00
|
|
|
You can [download fzf executable][bin] alone if you don't need the extra
|
|
|
|
stuff.
|
2015-02-17 04:15:16 +00:00
|
|
|
|
|
|
|
[bin]: https://github.com/junegunn/fzf-bin/releases
|
|
|
|
|
2017-08-17 07:57:02 +00:00
|
|
|
### Using Homebrew or Linuxbrew
|
2015-02-17 04:15:16 +00:00
|
|
|
|
2017-11-21 17:58:54 +00:00
|
|
|
You can use [Homebrew](http://brew.sh/) or [Linuxbrew](http://linuxbrew.sh/)
|
|
|
|
to install fzf.
|
2013-11-19 16:29:36 +00:00
|
|
|
|
2015-02-17 04:15:16 +00:00
|
|
|
```sh
|
2015-11-03 18:13:22 +00:00
|
|
|
brew install fzf
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2017-09-17 08:12:20 +00:00
|
|
|
# To install useful key bindings and fuzzy completion:
|
|
|
|
$(brew --prefix)/opt/fzf/install
|
2015-02-17 04:15:16 +00:00
|
|
|
```
|
2014-03-31 01:15:38 +00:00
|
|
|
|
2019-03-18 09:45:57 +00:00
|
|
|
fzf is also available [via MacPorts][portfile]: `sudo port install fzf`
|
|
|
|
|
|
|
|
[portfile]: https://github.com/macports/macports-ports/blob/master/sysutils/fzf/Portfile
|
|
|
|
|
2017-11-21 17:58:54 +00:00
|
|
|
### Using git
|
|
|
|
|
|
|
|
Alternatively, you can "git clone" this repository to any directory and run
|
|
|
|
[install](https://github.com/junegunn/fzf/blob/master/install) script.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
|
|
|
|
~/.fzf/install
|
|
|
|
```
|
|
|
|
|
2019-12-05 14:03:46 +00:00
|
|
|
### Using Linux package managers
|
|
|
|
|
|
|
|
| Distro | Command |
|
|
|
|
| --- | --- |
|
|
|
|
| Alpine Linux | `sudo apk add fzf` |
|
|
|
|
| Arch Linux | `sudo pacman -S fzf` |
|
|
|
|
| Debian | `sudo apt-get install fzf` |
|
|
|
|
| Fedora | `sudo dnf install fzf` |
|
|
|
|
| FreeBSD | `pkg install fzf` |
|
|
|
|
| NixOS | `nix-env -iA nixpkgs.fzf` |
|
|
|
|
| openSUSE | `sudo zypper install fzf` |
|
|
|
|
|
|
|
|
Shell extensions (key bindings and fuzzy auto-completion) and Vim/Neovim
|
|
|
|
plugin may or may not be enabled by default depending on the package manager.
|
|
|
|
Refer to the package documentation for more information.
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
|
|
Pre-built binaries for Windows can be downloaded [here][bin]. fzf is also
|
|
|
|
available via [Chocolatey][choco] and [Scoop][scoop]:
|
|
|
|
|
|
|
|
| Package manager | Command |
|
|
|
|
| --- | --- |
|
|
|
|
| Chocolatey | `choco install fzf` |
|
|
|
|
| Scoop | `scoop install fzf` |
|
|
|
|
|
|
|
|
[choco]: https://chocolatey.org/packages/fzf
|
|
|
|
[scoop]: https://github.com/ScoopInstaller/Main/blob/master/bucket/fzf.json
|
|
|
|
|
|
|
|
Known issues and limitations on Windows can be found on [the wiki
|
|
|
|
page][windows-wiki].
|
|
|
|
|
|
|
|
[windows-wiki]: https://github.com/junegunn/fzf/wiki/Windows
|
|
|
|
|
2017-04-01 03:00:30 +00:00
|
|
|
### As Vim plugin
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2017-11-21 17:58:54 +00:00
|
|
|
Once you have fzf installed, you can enable it inside Vim simply by adding the
|
2019-12-05 14:03:46 +00:00
|
|
|
directory to `&runtimepath` in your Vim configuration file. The path may
|
|
|
|
differ depending on the package manager.
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2014-03-04 02:25:50 +00:00
|
|
|
```vim
|
2017-11-21 17:58:54 +00:00
|
|
|
" If installed using Homebrew
|
|
|
|
set rtp+=/usr/local/opt/fzf
|
|
|
|
|
2016-09-12 19:11:28 +00:00
|
|
|
" If installed using git
|
2014-03-04 02:25:50 +00:00
|
|
|
set rtp+=~/.fzf
|
2017-11-21 17:58:54 +00:00
|
|
|
```
|
2016-09-12 19:11:28 +00:00
|
|
|
|
2017-11-21 17:58:54 +00:00
|
|
|
If you use [vim-plug](https://github.com/junegunn/vim-plug), the same can be
|
|
|
|
written as:
|
|
|
|
|
|
|
|
```vim
|
2016-09-12 19:11:28 +00:00
|
|
|
" If installed using Homebrew
|
2017-11-21 17:58:54 +00:00
|
|
|
Plug '/usr/local/opt/fzf'
|
|
|
|
|
|
|
|
" If installed using git
|
|
|
|
Plug '~/.fzf'
|
2014-03-04 02:25:50 +00:00
|
|
|
```
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2017-11-21 17:58:54 +00:00
|
|
|
But instead of separately installing fzf on your system (using Homebrew or
|
|
|
|
"git clone") and enabling it on Vim (adding it to `&runtimepath`), you can use
|
|
|
|
vim-plug to do both.
|
2014-09-02 04:06:05 +00:00
|
|
|
|
|
|
|
```vim
|
2018-11-09 07:50:16 +00:00
|
|
|
" PlugInstall and PlugUpdate will clone fzf in ~/.fzf and run the install script
|
2015-10-23 05:56:27 +00:00
|
|
|
Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }
|
2017-11-21 17:58:54 +00:00
|
|
|
" Both options are optional. You don't have to install fzf in ~/.fzf
|
2018-11-09 07:50:16 +00:00
|
|
|
" and you don't have to run the install script if you use fzf only in Vim.
|
2014-09-02 04:06:05 +00:00
|
|
|
```
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2017-01-31 12:43:41 +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 used.
|
|
|
|
|
|
|
|
- git: `cd ~/.fzf && git pull && ./install`
|
|
|
|
- brew: `brew update; brew reinstall fzf`
|
2017-03-29 16:59:41 +00:00
|
|
|
- chocolatey: `choco upgrade fzf`
|
2017-01-31 12:43:41 +00:00
|
|
|
- vim-plug: `:PlugUpdate fzf`
|
|
|
|
|
2016-11-27 06:16:53 +00:00
|
|
|
Building fzf
|
|
|
|
------------
|
|
|
|
|
|
|
|
See [BUILD.md](BUILD.md).
|
|
|
|
|
2013-10-23 01:26:55 +00:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2017-04-05 17:08:49 +00:00
|
|
|
fzf will launch interactive finder, read the list from STDIN, and write the
|
2013-10-23 01:26:55 +00:00
|
|
|
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
|
2013-11-06 11:54:02 +00:00
|
|
|
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
|
|
|
|
2016-11-08 14:41:46 +00:00
|
|
|
- `CTRL-J` / `CTRL-K` (or `CTRL-N` / `CTRL-P`) to move cursor up and down
|
2015-03-06 09:57:36 +00:00
|
|
|
- `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
|
2014-03-06 11:52:38 +00:00
|
|
|
|
2017-01-07 16:30:31 +00:00
|
|
|
#### Layout
|
|
|
|
|
|
|
|
fzf by default starts in fullscreen mode, but you can make it start below the
|
|
|
|
cursor with `--height` option.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
vim $(fzf --height 40%)
|
|
|
|
```
|
|
|
|
|
2018-06-09 16:41:50 +00:00
|
|
|
Also check out `--reverse` and `--layout` options if you prefer
|
|
|
|
"top-down" layout instead of the default "bottom-up" layout.
|
2017-01-07 16:30:31 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
vim $(fzf --height 40% --reverse)
|
|
|
|
```
|
|
|
|
|
|
|
|
You can add these options to `$FZF_DEFAULT_OPTS` so that they're applied by
|
2017-02-04 12:51:22 +00:00
|
|
|
default. For example,
|
2017-01-07 16:30:31 +00:00
|
|
|
|
|
|
|
```sh
|
2018-06-09 16:41:50 +00:00
|
|
|
export FZF_DEFAULT_OPTS='--height 40% --layout=reverse --border'
|
2017-01-07 16:30:31 +00:00
|
|
|
```
|
|
|
|
|
2015-11-03 18:16:36 +00:00
|
|
|
#### Search syntax
|
|
|
|
|
|
|
|
Unless otherwise specified, fzf starts in "extended-search mode" where you can
|
|
|
|
type in multiple search terms delimited by spaces. e.g. `^music .mp3$ sbtrkt
|
2016-10-03 17:17:36 +00:00
|
|
|
!fire`
|
|
|
|
|
2018-03-06 07:33:33 +00:00
|
|
|
| Token | Match type | Description |
|
|
|
|
| --------- | -------------------------- | ------------------------------------ |
|
|
|
|
| `sbtrkt` | fuzzy-match | Items that match `sbtrkt` |
|
|
|
|
| `'wild` | exact-match (quoted) | Items that include `wild` |
|
|
|
|
| `^music` | prefix-exact-match | Items that start with `music` |
|
|
|
|
| `.mp3$` | suffix-exact-match | Items that end with `.mp3` |
|
|
|
|
| `!fire` | inverse-exact-match | Items that do not include `fire` |
|
|
|
|
| `!^music` | inverse-prefix-exact-match | Items that do not start with `music` |
|
|
|
|
| `!.mp3$` | inverse-suffix-exact-match | Items that do not end with `.mp3` |
|
2013-11-15 11:40:57 +00:00
|
|
|
|
2015-09-12 04:31:07 +00:00
|
|
|
If you don't prefer fuzzy matching and do not wish to "quote" every word,
|
2015-11-03 13:49:32 +00:00
|
|
|
start fzf with `-e` or `--exact` option. Note that when `--exact` is set,
|
|
|
|
`'`-prefix "unquotes" the term.
|
2014-03-04 12:29:45 +00:00
|
|
|
|
2015-11-08 15:58:20 +00:00
|
|
|
A single bar character term acts as an OR operator. For example, the following
|
|
|
|
query matches entries that start with `core` and end with either `go`, `rb`,
|
|
|
|
or `py`.
|
|
|
|
|
|
|
|
```
|
|
|
|
^core go$ | rb$ | py$
|
|
|
|
```
|
|
|
|
|
2015-06-21 16:35:36 +00:00
|
|
|
#### Environment variables
|
|
|
|
|
|
|
|
- `FZF_DEFAULT_COMMAND`
|
|
|
|
- Default command to use when input is tty
|
2017-10-29 14:34:26 +00:00
|
|
|
- e.g. `export FZF_DEFAULT_COMMAND='fd --type f'`
|
2015-06-21 16:35:36 +00:00
|
|
|
- `FZF_DEFAULT_OPTS`
|
2015-11-03 18:14:38 +00:00
|
|
|
- Default options
|
2018-06-09 16:41:50 +00:00
|
|
|
- e.g. `export FZF_DEFAULT_OPTS="--layout=reverse --inline-info"`
|
2015-06-21 16:35:36 +00:00
|
|
|
|
2016-10-31 15:39:02 +00:00
|
|
|
#### Options
|
|
|
|
|
|
|
|
See the man page (`man fzf`) for the full list of options.
|
|
|
|
|
2019-04-18 09:49:30 +00:00
|
|
|
#### Demo
|
|
|
|
If you learn by watching videos, check out this screencast by [@samoshkin](https://github.com/samoshkin) to explore `fzf` features.
|
|
|
|
|
|
|
|
<a title="fzf - command-line fuzzy finder" href="https://www.youtube.com/watch?v=qgG5Jhi_Els">
|
|
|
|
<img src="https://i.imgur.com/vtG8olE.png" width="640">
|
|
|
|
</a>
|
|
|
|
|
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
|
|
|
|
2016-05-02 15:07:53 +00:00
|
|
|
`fzf-tmux` script
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
[fzf-tmux](bin/fzf-tmux) is a bash script that opens fzf in a tmux pane.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
# usage: fzf-tmux [-u|-d [HEIGHT[%]]] [-l|-r [WIDTH[%]]] [--] [FZF OPTIONS]
|
|
|
|
# (-[udlr]: up/down/left/right)
|
|
|
|
|
|
|
|
# select git branches in horizontal split below (15 lines)
|
|
|
|
git branch | fzf-tmux -d 15
|
|
|
|
|
|
|
|
# select multiple words in vertical split on the left (20% of screen width)
|
|
|
|
cat /usr/share/dict/words | fzf-tmux -l 20% --multi --reverse
|
|
|
|
```
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2017-01-07 16:30:31 +00:00
|
|
|
Alternatively, you can use `--height HEIGHT[%]` option not to start fzf in
|
|
|
|
fullscreen mode.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
fzf --height 40%
|
|
|
|
```
|
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
Key bindings for command-line
|
2013-12-21 15:22:23 +00:00
|
|
|
-----------------------------
|
2013-12-21 15:18:41 +00:00
|
|
|
|
2014-05-04 03:52:33 +00:00
|
|
|
The install script will setup the following key bindings for bash, zsh, and
|
|
|
|
fish.
|
2013-12-21 15:18:41 +00:00
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
- `CTRL-T` - Paste the selected files and directories onto the command-line
|
2015-06-25 16:00:58 +00:00
|
|
|
- Set `FZF_CTRL_T_COMMAND` to override the default command
|
2016-06-12 11:37:17 +00:00
|
|
|
- Set `FZF_CTRL_T_OPTS` to pass additional options
|
2018-11-09 07:50:16 +00:00
|
|
|
- `CTRL-R` - Paste the selected command from history onto the command-line
|
2017-03-03 03:20:01 +00:00
|
|
|
- If you want to see the commands in chronological order, press `CTRL-R`
|
|
|
|
again which toggles sorting by relevance
|
2016-06-12 11:37:17 +00:00
|
|
|
- Set `FZF_CTRL_R_OPTS` to pass additional options
|
2013-12-21 15:18:41 +00:00
|
|
|
- `ALT-C` - cd into the selected directory
|
2016-05-02 15:07:53 +00:00
|
|
|
- Set `FZF_ALT_C_COMMAND` to override the default command
|
2016-06-12 11:37:17 +00:00
|
|
|
- Set `FZF_ALT_C_OPTS` to pass additional options
|
2013-11-08 16:16:39 +00:00
|
|
|
|
2017-01-07 16:30:31 +00:00
|
|
|
If you're on a tmux session, you can start fzf in a split pane by setting
|
|
|
|
`FZF_TMUX` to 1, and change the height of the pane with `FZF_TMUX_HEIGHT`
|
|
|
|
(e.g. `20`, `50%`).
|
2014-03-27 16:39:20 +00:00
|
|
|
|
2014-05-04 03:52:33 +00:00
|
|
|
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.
|
|
|
|
|
2016-11-15 14:44:04 +00:00
|
|
|
More tips can be found on [the wiki page](https://github.com/junegunn/fzf/wiki/Configuring-shell-key-bindings).
|
|
|
|
|
2015-05-09 11:15:14 +00:00
|
|
|
Fuzzy completion for bash and zsh
|
|
|
|
---------------------------------
|
2013-11-19 16:29:36 +00:00
|
|
|
|
2013-11-29 09:08:22 +00:00
|
|
|
#### 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 `**`.
|
2013-11-23 11:09:56 +00:00
|
|
|
|
|
|
|
- `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>`
|
2013-11-19 16:29:36 +00:00
|
|
|
|
|
|
|
```sh
|
2013-11-19 16:42:57 +00:00
|
|
|
# Files under current directory
|
|
|
|
# - You can select multiple items with TAB key
|
2013-11-19 16:29:36 +00:00
|
|
|
vim **<TAB>
|
2013-11-19 16:42:57 +00:00
|
|
|
|
|
|
|
# Files under parent directory
|
2013-11-23 11:09:56 +00:00
|
|
|
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
|
2013-11-19 16:29:36 +00:00
|
|
|
vim ~/**<TAB>
|
|
|
|
|
2013-11-19 16:42:57 +00:00
|
|
|
|
|
|
|
# Directories under current directory (single-selection)
|
2013-11-19 16:29:36 +00:00
|
|
|
cd **<TAB>
|
2013-11-19 16:42:57 +00:00
|
|
|
|
2013-11-23 11:09:56 +00:00
|
|
|
# Directories under ~/github that match `fzf`
|
|
|
|
cd ~/github/fzf**<TAB>
|
2013-11-19 16:29:36 +00:00
|
|
|
```
|
|
|
|
|
2013-11-29 09:08:22 +00:00
|
|
|
#### Process IDs
|
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
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>
|
|
|
|
```
|
|
|
|
|
2013-11-29 09:08:22 +00:00
|
|
|
#### Host names
|
|
|
|
|
2013-11-29 09:09:51 +00:00
|
|
|
For ssh and telnet commands, fuzzy completion for host names is provided. The
|
2013-12-23 14:16:07 +00:00
|
|
|
names are extracted from /etc/hosts and ~/.ssh/config.
|
2013-11-29 09:08:22 +00:00
|
|
|
|
|
|
|
```sh
|
2013-12-23 14:16:07 +00:00
|
|
|
ssh **<TAB>
|
|
|
|
telnet **<TAB>
|
2013-11-29 09:08:22 +00:00
|
|
|
```
|
|
|
|
|
2014-07-14 03:48:31 +00:00
|
|
|
#### Environment variables / Aliases
|
|
|
|
|
|
|
|
```sh
|
|
|
|
unset **<TAB>
|
|
|
|
export **<TAB>
|
|
|
|
unalias **<TAB>
|
|
|
|
```
|
|
|
|
|
2013-11-19 16:42:57 +00:00
|
|
|
#### Settings
|
2013-11-19 16:29:36 +00:00
|
|
|
|
|
|
|
```sh
|
2013-11-19 16:42:57 +00:00
|
|
|
# Use ~~ as the trigger sequence instead of the default **
|
2013-11-19 16:29:36 +00:00
|
|
|
export FZF_COMPLETION_TRIGGER='~~'
|
2013-11-19 16:42:57 +00:00
|
|
|
|
|
|
|
# Options to fzf command
|
|
|
|
export FZF_COMPLETION_OPTS='+c -x'
|
2016-01-19 16:09:58 +00:00
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
# Use fd (https://github.com/sharkdp/fd) instead of the default find
|
2017-10-23 04:19:10 +00:00
|
|
|
# command for listing path candidates.
|
2017-10-29 14:34:26 +00:00
|
|
|
# - The first argument to the function ($1) is the base path to start traversal
|
2016-01-19 16:09:58 +00:00
|
|
|
# - See the source code (completion.{bash,zsh}) for the details.
|
2016-01-19 16:39:55 +00:00
|
|
|
_fzf_compgen_path() {
|
2017-10-29 14:34:26 +00:00
|
|
|
fd --hidden --follow --exclude ".git" . "$1"
|
2017-10-14 07:18:46 +00:00
|
|
|
}
|
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
# Use fd to generate the list for directory completion
|
2017-10-14 07:18:46 +00:00
|
|
|
_fzf_compgen_dir() {
|
2017-10-29 14:34:26 +00:00
|
|
|
fd --type d --hidden --follow --exclude ".git" . "$1"
|
2016-01-19 16:09:58 +00:00
|
|
|
}
|
2013-11-19 16:29:36 +00:00
|
|
|
```
|
|
|
|
|
2015-11-12 04:47:52 +00:00
|
|
|
#### Supported commands
|
|
|
|
|
|
|
|
On bash, fuzzy completion is enabled only for a predefined set of commands
|
|
|
|
(`complete | grep _fzf` to see the list). But you can enable it for other
|
2019-12-06 03:03:34 +00:00
|
|
|
commands as well by using `_fzf_setup_completion` helper function.
|
2015-11-12 04:47:52 +00:00
|
|
|
|
|
|
|
```sh
|
2019-12-20 09:39:22 +00:00
|
|
|
# usage: _fzf_setup_completion path|dir|var|alias|host COMMANDS...
|
2019-12-06 03:03:34 +00:00
|
|
|
_fzf_setup_completion path ag git kubectl
|
|
|
|
_fzf_setup_completion dir tree
|
2015-11-12 04:47:52 +00:00
|
|
|
```
|
|
|
|
|
2017-04-01 03:00:30 +00:00
|
|
|
Vim plugin
|
|
|
|
----------
|
2014-01-07 08:07:02 +00:00
|
|
|
|
2017-04-01 03:00:30 +00:00
|
|
|
See [README-VIM.md](README-VIM.md).
|
2016-07-25 17:35:40 +00:00
|
|
|
|
2017-07-29 08:08:51 +00:00
|
|
|
Advanced topics
|
|
|
|
---------------
|
|
|
|
|
|
|
|
### Performance
|
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
fzf is fast and is [getting even faster][perf]. Performance should not be
|
2017-07-29 08:08:51 +00:00
|
|
|
a problem in most use cases. However, you might want to be aware of the
|
|
|
|
options that affect the performance.
|
|
|
|
|
|
|
|
- `--ansi` tells fzf to extract and parse ANSI color codes in the input and it
|
|
|
|
makes the initial scanning slower. So it's not recommended that you add it
|
|
|
|
to your `$FZF_DEFAULT_OPTS`.
|
|
|
|
- `--nth` makes fzf slower as fzf has to tokenize each line.
|
|
|
|
- `--with-nth` makes fzf slower as fzf has to tokenize and reassemble each
|
|
|
|
line.
|
|
|
|
- If you absolutely need better performance, you can consider using
|
2018-11-09 07:50:16 +00:00
|
|
|
`--algo=v1` (the default being `v2`) to make fzf use a faster greedy
|
2017-07-29 08:08:51 +00:00
|
|
|
algorithm. However, this algorithm is not guaranteed to find the optimal
|
|
|
|
ordering of the matches and is not recommended.
|
|
|
|
|
2017-09-07 03:38:34 +00:00
|
|
|
[perf]: https://junegunn.kr/images/fzf-0.17.0.png
|
2017-07-29 08:08:51 +00:00
|
|
|
|
|
|
|
### Executing external programs
|
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
You can set up key bindings for starting external processes without leaving
|
|
|
|
fzf (`execute`, `execute-silent`).
|
2017-07-29 08:08:51 +00:00
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
```bash
|
|
|
|
# Press F1 to open the file with less without leaving fzf
|
2017-07-29 08:08:51 +00:00
|
|
|
# Press CTRL-Y to copy the line to clipboard and aborts fzf (requires pbcopy)
|
|
|
|
fzf --bind 'f1:execute(less -f {}),ctrl-y:execute-silent(echo {} | pbcopy)+abort'
|
|
|
|
```
|
|
|
|
|
|
|
|
See *KEY BINDINGS* section of the man page for details.
|
|
|
|
|
|
|
|
### Preview window
|
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
When `--preview` option is set, fzf automatically starts an external process with
|
2017-07-29 08:08:51 +00:00
|
|
|
the current line as the argument and shows the result in the split window.
|
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
```bash
|
2017-07-29 08:08:51 +00:00
|
|
|
# {} is replaced to the single-quoted string of the focused line
|
|
|
|
fzf --preview 'cat {}'
|
|
|
|
```
|
|
|
|
|
2018-11-09 07:50:16 +00:00
|
|
|
Since the preview window is updated only after the process is complete, it's
|
2017-07-29 08:08:51 +00:00
|
|
|
important that the command finishes quickly.
|
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
```bash
|
2017-07-29 08:08:51 +00:00
|
|
|
# Use head instead of cat so that the command doesn't take too long to finish
|
|
|
|
fzf --preview 'head -100 {}'
|
|
|
|
```
|
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
Preview window supports ANSI colors, so you can use any program that
|
2017-07-29 08:08:51 +00:00
|
|
|
syntax-highlights the content of a file.
|
|
|
|
|
2019-03-29 01:31:17 +00:00
|
|
|
- Bat: https://github.com/sharkdp/bat
|
2017-07-29 08:08:51 +00:00
|
|
|
- Highlight: http://www.andre-simon.de/doku/highlight/en/highlight.php
|
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
```bash
|
2019-12-13 03:43:34 +00:00
|
|
|
fzf --preview 'bat --style=numbers --color=always {} | head -500'
|
2017-07-29 08:08:51 +00:00
|
|
|
```
|
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
You can customize the size, position, and border of the preview window using
|
2019-12-17 16:07:25 +00:00
|
|
|
`--preview-window` option, and the foreground and background color of it with
|
|
|
|
`--color` option. For example,
|
2017-07-29 08:08:51 +00:00
|
|
|
|
2017-07-29 08:12:46 +00:00
|
|
|
```bash
|
2019-12-17 16:07:25 +00:00
|
|
|
fzf --height 40% --layout reverse --info inline --border \
|
|
|
|
--preview 'file {}' --preview-window down:1:noborder \
|
|
|
|
--color 'fg:#bbccdd,fg+:#ddeeff,bg:#334455,preview-bg:#223344,border:#778899'
|
2017-07-29 08:08:51 +00:00
|
|
|
```
|
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
See the man page (`man fzf`) for the full list of options.
|
|
|
|
|
2018-09-04 03:24:46 +00:00
|
|
|
For more advanced examples, see [Key bindings for git with fzf][fzf-git]
|
|
|
|
([code](https://gist.github.com/junegunn/8b572b8d4b5eddd8b85e5f4d40f17236)).
|
2017-07-29 08:08:51 +00:00
|
|
|
|
|
|
|
[fzf-git]: https://junegunn.kr/2016/07/fzf-git/
|
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
----
|
|
|
|
|
|
|
|
Since fzf is a general-purpose text filter rather than a file finder, **it is
|
|
|
|
not a good idea to add `--preview` option to your `$FZF_DEFAULT_OPTS`**.
|
|
|
|
|
|
|
|
```sh
|
|
|
|
# *********************
|
|
|
|
# ** DO NOT DO THIS! **
|
|
|
|
# *********************
|
|
|
|
export FZF_DEFAULT_OPTS='--preview "bat --style=numbers --color=always {} | head -500"'
|
|
|
|
|
|
|
|
# bat doesn't work with any input other than the list of files
|
|
|
|
ps -ef | fzf
|
|
|
|
seq 100 | fzf
|
|
|
|
history | fzf
|
|
|
|
```
|
|
|
|
|
2013-11-10 10:51:32 +00:00
|
|
|
Tips
|
|
|
|
----
|
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
#### Respecting `.gitignore`
|
2014-04-06 06:25:58 +00:00
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
You can use [fd](https://github.com/sharkdp/fd),
|
|
|
|
[ripgrep](https://github.com/BurntSushi/ripgrep), or [the silver
|
|
|
|
searcher](https://github.com/ggreer/the_silver_searcher) instead of the
|
|
|
|
default find command to traverse the file system while respecting
|
|
|
|
`.gitignore`.
|
2014-04-06 06:25:58 +00:00
|
|
|
|
|
|
|
```sh
|
2017-10-29 14:34:26 +00:00
|
|
|
# Feed the output of fd into fzf
|
|
|
|
fd --type f | fzf
|
2014-04-06 06:25:58 +00:00
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
# Setting fd as the default source for fzf
|
|
|
|
export FZF_DEFAULT_COMMAND='fd --type f'
|
2014-04-06 06:25:58 +00:00
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
# Now fzf (w/o pipe) will use fd instead of find
|
2014-04-06 06:25:58 +00:00
|
|
|
fzf
|
2015-06-30 04:17:48 +00:00
|
|
|
|
|
|
|
# To apply the command to CTRL-T as well
|
|
|
|
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"
|
2014-04-06 06:25:58 +00:00
|
|
|
```
|
|
|
|
|
2017-10-29 14:34:26 +00:00
|
|
|
If you want the command to follow symbolic links, and don't want it to exclude
|
|
|
|
hidden files, use the following command:
|
2016-09-12 19:11:28 +00:00
|
|
|
|
|
|
|
```sh
|
2017-10-29 14:34:26 +00:00
|
|
|
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'
|
2016-09-12 19:11:28 +00:00
|
|
|
```
|
|
|
|
|
2015-03-06 09:57:36 +00:00
|
|
|
#### Fish shell
|
2014-05-02 02:27:32 +00:00
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
`CTRL-T` key binding of fish, unlike those of bash and zsh, will use the last
|
|
|
|
token on the command-line as the root directory for the recursive search. For
|
|
|
|
instance, hitting `CTRL-T` at the end of the following command-line
|
2016-12-14 06:37:27 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
ls /var/
|
|
|
|
```
|
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
will list all files and directories under `/var/`.
|
2016-12-14 06:37:27 +00:00
|
|
|
|
|
|
|
When using a custom `FZF_CTRL_T_COMMAND`, use the unexpanded `$dir` variable to
|
|
|
|
make use of this feature. `$dir` defaults to `.` when the last token is not a
|
|
|
|
valid directory. Example:
|
|
|
|
|
|
|
|
```sh
|
2017-06-22 16:50:45 +00:00
|
|
|
set -g FZF_CTRL_T_COMMAND "command find -L \$dir -type f 2> /dev/null | sed '1d; s#^\./##'"
|
2014-05-02 02:27:32 +00:00
|
|
|
```
|
|
|
|
|
2018-09-26 17:52:52 +00:00
|
|
|
Related projects
|
|
|
|
----------------
|
|
|
|
|
|
|
|
https://github.com/junegunn/fzf/wiki/Related-projects
|
|
|
|
|
2017-01-07 17:09:31 +00:00
|
|
|
[License](LICENSE)
|
|
|
|
------------------
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2017-01-07 17:09:31 +00:00
|
|
|
The MIT License (MIT)
|
2013-10-23 01:26:55 +00:00
|
|
|
|
2019-12-13 03:43:34 +00:00
|
|
|
Copyright (c) 2019 Junegunn Choi
|