fzf/README.md

787 lines
25 KiB
Markdown
Raw Normal View History

2021-01-15 01:21:08 +00:00
<img src="https://raw.githubusercontent.com/junegunn/i/master/fzf.png" height="170" alt="fzf - a command-line fuzzy finder"> [![github-actions](https://github.com/junegunn/fzf/workflows/Test%20fzf%20on%20Linux/badge.svg)](https://github.com/junegunn/fzf/actions)
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
<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
----
- Portable, no dependencies
2015-03-15 01:57:09 +00:00
- Blazingly fast
- The most comprehensive feature set
- Flexible layout
2015-03-15 01:57:09 +00:00
- Batteries included
- Vim/Neovim plugin, key bindings, and fuzzy auto-completion
2013-10-23 01:26:55 +00:00
Table of Contents
-----------------
2020-10-05 10:16:40 +00:00
<!-- vim-markdown-toc GFM -->
* [Installation](#installation)
2023-01-13 12:10:18 +00:00
* [Using Homebrew](#using-homebrew)
* [Using git](#using-git)
* [Using Linux package managers](#using-linux-package-managers)
* [Windows](#windows)
* [As Vim plugin](#as-vim-plugin)
2020-10-05 10:16:40 +00:00
* [Upgrading fzf](#upgrading-fzf)
* [Building fzf](#building-fzf)
* [Usage](#usage)
2023-01-22 17:23:25 +00:00
* [Using the finder](#using-the-finder)
* [Layout](#layout)
* [Search syntax](#search-syntax)
* [Environment variables](#environment-variables)
* [Options](#options)
* [Demo](#demo)
2020-10-05 10:16:40 +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)
2023-01-22 17:23:25 +00:00
* [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)
* [Custom fuzzy completion](#custom-fuzzy-completion)
2020-10-05 10:16:40 +00:00
* [Vim plugin](#vim-plugin)
* [Advanced topics](#advanced-topics)
2023-01-13 12:10:18 +00:00
* [Performance](#performance)
* [Executing external programs](#executing-external-programs)
* [Turning into a different process](#turning-into-a-different-process)
2023-01-13 12:10:18 +00:00
* [Reloading the candidate list](#reloading-the-candidate-list)
* [1. Update the list of processes by pressing CTRL-R](#1-update-the-list-of-processes-by-pressing-ctrl-r)
* [2. Switch between sources by pressing CTRL-D or CTRL-F](#2-switch-between-sources-by-pressing-ctrl-d-or-ctrl-f)
* [3. Interactive ripgrep integration](#3-interactive-ripgrep-integration)
* [Preview window](#preview-window)
2020-10-05 10:16:40 +00:00
* [Tips](#tips)
* [Respecting `.gitignore`](#respecting-gitignore)
* [Fish shell](#fish-shell)
2020-10-05 10:16:40 +00:00
* [Related projects](#related-projects)
* [License](#license)
<!-- vim-markdown-toc -->
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
- `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
2020-10-26 16:46:43 +00:00
[bin]: https://github.com/junegunn/fzf/releases
2015-02-17 04:15:16 +00:00
### Using Homebrew
2015-02-17 04:15:16 +00:00
2021-11-28 13:28:32 +00:00
You can use [Homebrew](https://brew.sh/) (on macOS or Linux)
2017-11-21 17:58:54 +00:00
to install fzf.
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
# 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
```
### Using Linux package managers
| Package Manager | Linux Distribution | Command |
| --- | --- | --- |
| APK | Alpine Linux | `sudo apk add fzf` |
| APT | Debian 9+/Ubuntu 19.10+ | `sudo apt install fzf` |
| Conda | | `conda install -c conda-forge fzf` |
| DNF | Fedora | `sudo dnf install fzf` |
| Nix | NixOS, etc. | `nix-env -iA nixpkgs.fzf` |
| Pacman | Arch Linux | `sudo pacman -S fzf` |
| pkg | FreeBSD | `pkg install fzf` |
| pkgin | NetBSD | `pkgin install fzf` |
| pkg_add | OpenBSD | `pkg_add fzf` |
| Portage | Gentoo | `emerge --ask app-shells/fzf` |
| XBPS | Void Linux | `sudo xbps-install -S fzf` |
| Zypper | openSUSE | `sudo zypper install fzf` |
> :warning: **Key bindings (CTRL-T / CTRL-R / ALT-C) and fuzzy auto-completion
> may not be enabled by default.**
>
> Refer to the package documentation for more information. (e.g. `apt show fzf`)
2021-11-18 06:46:30 +00:00
[![Packaging status](https://repology.org/badge/vertical-allrepos/fzf.svg)](https://repology.org/project/fzf/versions)
### Windows
Pre-built binaries for Windows can be downloaded [here][bin]. fzf is also
2023-02-15 07:47:12 +00:00
available via [Chocolatey][choco], [Scoop][scoop], and [Winget][winget]:
2023-02-15 07:47:12 +00:00
| Package manager | Command |
| --- | --- |
| Chocolatey | `choco install fzf` |
| Scoop | `scoop install fzf` |
| Winget | `winget install fzf` |
[choco]: https://chocolatey.org/packages/fzf
[scoop]: https://github.com/ScoopInstaller/Main/blob/master/bucket/fzf.json
2023-02-15 07:47:12 +00:00
[winget]: https://github.com/microsoft/winget-pkgs/tree/master/manifests/j/junegunn/fzf
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
If you use
[vim-plug](https://github.com/junegunn/vim-plug), add this line to your Vim
configuration file:
2013-10-23 01:26:55 +00:00
2014-03-04 02:25:50 +00:00
```vim
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
2014-03-04 02:25:50 +00:00
```
2013-10-23 01:26:55 +00:00
`fzf#install()` makes sure that you have the latest binary, but it's optional,
so you can omit it if you use a plugin manager that doesn't support hooks.
2014-09-02 04:06:05 +00:00
For more installation options, see [README-VIM.md](README-VIM.md).
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
2017-01-31 12:43:41 +00:00
while. Please follow the instruction below depending on the installation
method used.
- git: `cd ~/.fzf && git pull && ./install`
- brew: `brew update; brew upgrade fzf`
- macports: `sudo port upgrade fzf`
- 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
-----
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
vim $(fzf)
2013-10-23 01:26:55 +00:00
```
> *:bulb: A more robust solution would be to use `xargs` but we've presented
> the above as it's easier to grasp*
> ```sh
> fzf --print0 | xargs -0 -o vim
> ```
>
> *:bulb: fzf also has the ability to turn itself into a different process.*
>
> ```sh
> fzf --bind 'enter:become(vim {})'
> ```
>
> *See [Turning into a different process](#turning-into-a-different-process)
> for more information.*
2023-01-22 17:23:25 +00:00
### Using the finder
2013-11-09 18:56:18 +00:00
- `CTRL-K` / `CTRL-J` (or `CTRL-P` / `CTRL-N`) 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
2023-01-22 17:23:25 +00:00
### Layout
2017-01-07 16:30:31 +00:00
fzf by default starts in fullscreen mode, but you can make it start below the
cursor with `--height` option.
```sh
vim $(fzf --height 40%)
```
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
default. For example,
2017-01-07 16:30:31 +00:00
```sh
export FZF_DEFAULT_OPTS='--height 40% --layout=reverse --border'
2017-01-07 16:30:31 +00:00
```
2023-01-22 17:23:25 +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`
| 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` |
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.
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$
```
2023-01-22 17:23:25 +00:00
### Environment variables
2015-06-21 16:35:36 +00:00
- `FZF_DEFAULT_COMMAND`
- Default command to use when input is tty
- e.g. `export FZF_DEFAULT_COMMAND='fd --type f'`
2021-02-03 10:40:05 +00:00
- > :warning: This variable is not used by shell extensions due to the
> slight difference in requirements.
>
> (e.g. `CTRL-T` runs `$FZF_CTRL_T_COMMAND` instead, `vim **<tab>` runs
> `_fzf_compgen_path()`, and `cd **<tab>` runs `_fzf_compgen_dir()`)
>
> The available options are described later in this document.
2015-06-21 16:35:36 +00:00
- `FZF_DEFAULT_OPTS`
2015-11-03 18:14:38 +00:00
- Default options
- e.g. `export FZF_DEFAULT_OPTS="--layout=reverse --inline-info"`
2015-06-21 16:35:36 +00:00
2023-01-22 17:23:25 +00:00
### Options
2016-10-31 15:39:02 +00:00
See the man page (`man fzf`) for the full list of options.
2023-01-22 17:23:25 +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
2021-04-08 01:06:26 +00:00
* [Wiki page of examples](https://github.com/junegunn/fzf/wiki/examples)
* *Disclaimer: The examples on this page are maintained by the community
and are not thoroughly tested*
* [Advanced fzf examples](https://github.com/junegunn/fzf/blob/master/ADVANCED.md)
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 [LAYOUT OPTIONS] [--] [FZF OPTIONS]
# See available options
fzf-tmux --help
2016-05-02 15:07:53 +00:00
# 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 `-[pudlr]`
2016-05-02 15:07:53 +00:00
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
-----------------------------
The install script will setup the following key bindings for bash, zsh, and
fish.
2018-11-09 07:50:16 +00:00
- `CTRL-T` - Paste the selected files and directories onto the command-line
- Set `FZF_CTRL_T_COMMAND` to override the default command
- Set `FZF_CTRL_T_OPTS` to pass additional options to fzf
2023-01-13 12:10:18 +00:00
```sh
2023-01-22 17:21:16 +00:00
# Preview file content using bat (https://github.com/sharkdp/bat)
2023-01-13 12:10:18 +00:00
export FZF_CTRL_T_OPTS="
--preview 'bat -n --color=always {}'
--bind 'ctrl-/:change-preview-window(down|hidden|)'"
```
2018-11-09 07:50:16 +00:00
- `CTRL-R` - Paste the selected command from history onto the command-line
- If you want to see the commands in chronological order, press `CTRL-R`
again which toggles sorting by relevance
- Set `FZF_CTRL_R_OPTS` to pass additional options to fzf
2023-01-13 12:10:18 +00:00
```sh
# CTRL-/ to toggle small preview window to see the full command
# CTRL-Y to copy the command into clipboard using pbcopy
export FZF_CTRL_R_OPTS="
--preview 'echo {}' --preview-window up:3:hidden:wrap
--bind 'ctrl-/:toggle-preview'
--bind 'ctrl-y:execute-silent(echo -n {2..} | pbcopy)+abort'
--color header:italic
--header 'Press CTRL-Y to copy command into clipboard'"
```
- `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
- Set `FZF_ALT_C_OPTS` to pass additional options to fzf
2023-01-13 12:10:18 +00:00
```sh
# Print tree structure in the preview window
export FZF_ALT_C_OPTS="--preview 'tree -C {}'"
```
2013-11-08 16:16:39 +00:00
If you're on a tmux session, you can start fzf in a tmux split-pane or in
a tmux popup window by setting `FZF_TMUX_OPTS` (e.g. `export FZF_TMUX_OPTS='-p80%,60%'`).
See `fzf-tmux --help` for available options.
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
---------------------------------
2023-01-22 17:23:25 +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 `**`.
- `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>`
```sh
# Files under the current directory
2013-11-19 16:42:57 +00:00
# - 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>
```
2023-01-22 17:23:25 +00:00
### Process IDs
Fuzzy completion for PIDs is provided for kill command.
2013-11-29 08:49:48 +00:00
```sh
# Can select multiple processes with <TAB> or <Shift-TAB> keys
kill -9 **<TAB>
2013-11-29 08:49:48 +00:00
```
2023-01-22 17:23:25 +00:00
### Host names
For ssh and telnet commands, fuzzy completion for hostnames is provided. The
names are extracted from /etc/hosts and ~/.ssh/config.
```sh
ssh **<TAB>
telnet **<TAB>
```
2023-01-22 17:23:25 +00:00
### Environment variables / Aliases
```sh
unset **<TAB>
export **<TAB>
unalias **<TAB>
```
2023-01-22 17:23:25 +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
2021-02-17 07:44:54 +00:00
export FZF_COMPLETION_OPTS='--border --info=inline'
# Use fd (https://github.com/sharkdp/fd) instead of the default find
# command for listing path candidates.
# - The first argument to the function ($1) is the base path to start traversal
# - See the source code (completion.{bash,zsh}) for the details.
2016-01-19 16:39:55 +00:00
_fzf_compgen_path() {
fd --hidden --follow --exclude ".git" . "$1"
}
# Use fd to generate the list for directory completion
_fzf_compgen_dir() {
fd --type d --hidden --follow --exclude ".git" . "$1"
}
2023-01-13 12:10:18 +00:00
# Advanced customization of fzf options via _fzf_comprun function
# - The first argument to the function is the name of the command.
# - You should make sure to pass the rest of the arguments to fzf.
_fzf_comprun() {
local command=$1
shift
case "$command" in
2023-01-13 12:10:18 +00:00
cd) fzf --preview 'tree -C {} | head -200' "$@" ;;
export|unset) fzf --preview "eval 'echo \$'{}" "$@" ;;
ssh) fzf --preview 'dig {}' "$@" ;;
*) fzf --preview 'bat -n --color=always {}' "$@" ;;
esac
}
```
2023-01-22 17:23:25 +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
commands as well by using `_fzf_setup_completion` helper function.
```sh
# usage: _fzf_setup_completion path|dir|var|alias|host COMMANDS...
_fzf_setup_completion path ag git kubectl
_fzf_setup_completion dir tree
```
2023-01-22 17:23:25 +00:00
### Custom fuzzy completion
_**(Custom completion API is experimental and subject to change)**_
For a command named _"COMMAND"_, define `_fzf_complete_COMMAND` function using
`_fzf_complete` helper.
```sh
# Custom fuzzy completion for "doge" command
# e.g. doge **<TAB>
_fzf_complete_doge() {
_fzf_complete --multi --reverse --prompt="doge> " -- "$@" < <(
echo very
echo wow
echo such
echo doge
)
}
```
- The arguments before `--` are the options to fzf.
- After `--`, simply pass the original completion arguments unchanged (`"$@"`).
- Then, write a set of commands that generates the completion candidates and
feed its output to the function using process substitution (`< <(...)`).
zsh will automatically pick up the function using the naming convention but in
bash you have to manually associate the function with the command using the
`complete` command.
```sh
[ -n "$BASH" ] && complete -F _fzf_complete_doge -o default -o bashdefault doge
```
If you need to post-process the output from fzf, define
`_fzf_complete_COMMAND_post` as follows.
```sh
_fzf_complete_foo() {
_fzf_complete --multi --reverse --header-lines=3 -- "$@" < <(
ls -al
)
}
_fzf_complete_foo_post() {
awk '{print $NF}'
}
[ -n "$BASH" ] && complete -F _fzf_complete_foo -o default -o bashdefault foo
```
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).
2017-07-29 08:08:51 +00:00
Advanced topics
---------------
### Performance
2023-01-13 12:10:18 +00:00
fzf is fast. Performance should not be a problem in most use cases. However,
you might want to be aware of the options that can affect performance.
2017-07-29 08:08:51 +00:00
- `--ansi` tells fzf to extract and parse ANSI color codes in the input, and it
2017-07-29 08:08:51 +00:00
makes the initial scanning slower. So it's not recommended that you add it
to your `$FZF_DEFAULT_OPTS`.
- `--nth` makes fzf slower because it has to tokenize each line.
2017-07-29 08:08:51 +00:00
- `--with-nth` makes fzf slower as fzf has to tokenize and reassemble each
line.
### 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.
### Turning into a different process
`become(...)` is similar to `execute(...)`/`execute-silent(...)` described
above, but instead of executing the command and coming back to fzf on
complete, it turns fzf into a new process for the command.
```sh
fzf --bind 'enter:become(vim {})'
```
Compared to the seemingly equivalent command substitution `vim "$(fzf)"`, this
approach has several advantages:
* Vim will not open an empty file when you terminate fzf with
<kbd>CTRL-C</kbd>
* Vim will not open an empty file when you press <kbd>ENTER</kbd> on an empty
result
* Can handle multiple selections even when they have whitespaces
```sh
fzf --multi --bind 'enter:become(vim {+})'
```
To be fair, running `fzf --print0 | xargs -0 -o vim` instead of `vim "$(fzf)"`
resolves all of the issues mentioned. Nonetheless, `become(...)` still offers
additional benefits in different scenarios.
* You can set up multiple bindings to handle the result in different ways
without any wrapping script
```sh
fzf --bind 'enter:become(vim {}),ctrl-e:become(emacs {})'
```
* Previously, you would have to use `--expect=ctrl-e` and check the first
line of the output of fzf
* You can easily build the subsequent command using the field index
expressions of fzf
```sh
# Open the file in Vim and go to the line
git grep --line-number . |
fzf --delimiter : --nth 3.. --bind 'enter:become(vim {1} +{2})'
```
2020-10-05 10:16:40 +00:00
### Reloading the candidate list
By binding `reload` action to a key or an event, you can make fzf dynamically
reload the candidate list. See https://github.com/junegunn/fzf/issues/1750 for
more details.
#### 1. Update the list of processes by pressing CTRL-R
```sh
ps -ef |
fzf --bind 'ctrl-r:reload(ps -ef)' \
2020-10-05 10:16:40 +00:00
--header 'Press CTRL-R to reload' --header-lines=1 \
--height=50% --layout=reverse
```
#### 2. Switch between sources by pressing CTRL-D or CTRL-F
```sh
FZF_DEFAULT_COMMAND='find . -type f' \
fzf --bind 'ctrl-d:reload(find . -type d),ctrl-f:reload(eval "$FZF_DEFAULT_COMMAND")' \
2020-10-05 10:16:40 +00:00
--height=50% --layout=reverse
```
#### 3. Interactive ripgrep integration
The following example uses fzf as the selector interface for ripgrep. We bound
`reload` action to `change` event, so every time you type on fzf, the ripgrep
2020-10-05 10:16:40 +00:00
process will restart with the updated query string denoted by the placeholder
2021-08-14 11:33:22 +00:00
expression `{q}`. Also, note that we used `--disabled` option so that fzf
doesn't perform any secondary filtering.
2020-10-05 10:16:40 +00:00
```sh
: | rg_prefix='rg --column --line-number --no-heading --color=always --smart-case' \
fzf --bind 'start:reload:$rg_prefix ""' \
--bind 'change:reload:$rg_prefix {q} || true' \
--bind 'enter:become(vim {1} +{2})' \
--ansi --disabled \
--height=50% --layout=reverse
2020-10-05 10:16:40 +00:00
```
If ripgrep doesn't find any matches, it will exit with a non-zero exit status,
and fzf will warn you about it. To suppress the warning message, we added
`|| true` to the command, so that it always exits with 0.
See ["Using fzf as interactive Ripgrep launcher"](https://github.com/junegunn/fzf/blob/master/ADVANCED.md#using-fzf-as-interactive-ripgrep-launcher)
for more sophisticated examples.
2022-01-03 04:52:46 +00:00
2017-07-29 08:08:51 +00:00
### Preview window
When the `--preview` option is set, fzf automatically starts an external process
with the current line as the argument and shows the result in the split window.
Your `$SHELL` is used to execute the command with `$SHELL -c COMMAND`.
The window can be scrolled using the mouse or custom key bindings.
2017-07-29 08:08:51 +00:00
2017-07-29 08:12:46 +00:00
```bash
# {} is replaced with the single-quoted string of the focused line
2017-07-29 08:08:51 +00:00
fzf --preview 'cat {}'
```
2019-12-13 03:43:34 +00:00
Preview window supports ANSI colors, so you can use any program that
syntax-highlights the content of a file, such as
[Bat](https://github.com/sharkdp/bat) or
[Highlight](http://www.andre-simon.de/doku/highlight/en/highlight.php):
2017-07-29 08:08:51 +00:00
2017-07-29 08:12:46 +00:00
```bash
2023-01-13 12:10:18 +00:00
fzf --preview 'bat --color=always {}' --preview-window '~3'
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 \
2021-04-06 13:53:59 +00:00
--preview 'file {}' --preview-window up,1,border-horizontal \
2023-01-13 12:10:18 +00:00
--bind 'ctrl-/:change-preview-window(50%|hidden|)' \
2019-12-17 16:07:25 +00:00
--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.
2022-08-23 04:29:41 +00:00
More advanced examples can be found [here](https://github.com/junegunn/fzf/blob/master/ADVANCED.md).
2017-07-29 08:08:51 +00:00
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 --line-range :500 {}"'
2019-12-13 03:43:34 +00:00
# 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
----
### Respecting `.gitignore`
2014-04-06 06:25:58 +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
# Feed the output of fd into fzf
2022-08-08 04:38:21 +00:00
fd --type f --strip-cwd-prefix | fzf
2014-04-06 06:25:58 +00:00
# Setting fd as the default source for fzf
2022-08-08 04:38:21 +00:00
export FZF_DEFAULT_COMMAND='fd --type f --strip-cwd-prefix'
2014-04-06 06:25:58 +00:00
# Now fzf (w/o pipe) will use fd instead of find
2014-04-06 06:25:58 +00:00
fzf
# 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
```
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
2022-08-08 04:38:21 +00:00
export FZF_DEFAULT_COMMAND='fd --type f --strip-cwd-prefix --hidden --follow --exclude .git'
2016-09-12 19:11:28 +00:00
```
### Fish shell
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
```sh
ls /var/
```
2019-12-13 03:43:34 +00:00
will list all files and directories under `/var/`.
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
set -g FZF_CTRL_T_COMMAND "command find -L \$dir -type f 2> /dev/null | sed '1d; s#^\./##'"
```
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
2023-01-16 16:19:59 +00:00
Copyright (c) 2013-2023 Junegunn Choi