Special thanks to:
### [Tuple, the premier screen sharing app for developers](https://tuple.app/fzf)
[Available for MacOS & Windows](https://tuple.app/fzf)
--- Special thanks to:
### [Warp, the intelligent terminal for developers](https://www.warp.dev/?utm_source=github&utm_medium=referral&utm_campaign=fzf)
[Available for MacOS, Linux, & Windows](https://www.warp.dev/?utm_source=github&utm_medium=referral&utm_campaign=fzf)
---
### [Tuple, the premier screen sharing app for developers](https://tuple.app/fzf)
[Available for MacOS & Windows](https://tuple.app/fzf)--- Special thanks to:
It's an interactive filter program for any kind of list; files, command
history, processes, hostnames, bookmarks, git commits, etc. It implements
a "fuzzy" matching algorithm, so you can quickly type in patterns with omitted
characters and still get the results you want.
Highlights
----------
- **Portable** — Distributed as a single binary for easy installation
- **Fast** — Optimized to process millions of items instantly
- **Versatile** — Fully customizable through an event-action binding mechanism
- **All-inclusive** — Comes with integrations for Bash, Zsh, Fish, Vim, and Neovim
Table of Contents
-----------------
* [Installation](#installation)
* [Using Homebrew](#using-homebrew)
* [Linux packages](#linux-packages)
* [Windows packages](#windows-packages)
* [Using git](#using-git)
* [Binary releases](#binary-releases)
* [Setting up shell integration](#setting-up-shell-integration)
* [Vim/Neovim plugin](#vimneovim-plugin)
* [Upgrading fzf](#upgrading-fzf)
* [Building fzf](#building-fzf)
* [Usage](#usage)
* [Using the finder](#using-the-finder)
* [Display modes](#display-modes)
* [`--height` mode](#--height-mode)
* [`--tmux` mode](#--tmux-mode)
* [Search syntax](#search-syntax)
* [Environment variables](#environment-variables)
* [Customizing the look](#customizing-the-look)
* [Options](#options)
* [Demo](#demo)
* [Examples](#examples)
* [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)
* [Customizing fzf options for completion](#customizing-fzf-options-for-completion)
* [Customizing completion source for paths and directories](#customizing-completion-source-for-paths-and-directories)
* [Supported commands](#supported-commands)
* [Custom fuzzy completion](#custom-fuzzy-completion)
* [Vim plugin](#vim-plugin)
* [Advanced topics](#advanced-topics)
* [Customizing for different types of input](#customizing-for-different-types-of-input)
* [Performance](#performance)
* [Executing external programs](#executing-external-programs)
* [Turning into a different process](#turning-into-a-different-process)
* [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)
* [Previewing an image](#previewing-an-image)
* [Tips](#tips)
* [Respecting `.gitignore`](#respecting-gitignore)
* [Fish shell](#fish-shell)
* [fzf Theme Playground](#fzf-theme-playground)
* [Related projects](#related-projects)
* [License](#license)
* [Sponsors :heart:](#sponsors-heart)
Installation
------------
### Using Homebrew
You can use [Homebrew](https://brew.sh/) (on macOS or Linux) to install fzf.
```sh
brew install fzf
```
> [!IMPORTANT]
> To set up shell integration (key bindings and fuzzy completion),
> see [the instructions below](#setting-up-shell-integration).
fzf is also available [via MacPorts][portfile]: `sudo port install fzf`
[portfile]: https://github.com/macports/macports-ports/blob/master/sysutils/fzf/Portfile
### Linux packages
| 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` |
| Spack | | `spack install fzf` |
| XBPS | Void Linux | `sudo xbps-install -S fzf` |
| Zypper | openSUSE | `sudo zypper install fzf` |
> [!IMPORTANT]
> To set up shell integration (key bindings and fuzzy completion),
> see [the instructions below](#setting-up-shell-integration).
[](https://repology.org/project/fzf/versions)
### Windows packages
On Windows, fzf is available via [Chocolatey][choco], [Scoop][scoop],
[Winget][winget], and [MSYS2][msys2]:
| Package manager | Command |
| --------------- | ------------------------------------- |
| Chocolatey | `choco install fzf` |
| Scoop | `scoop install fzf` |
| Winget | `winget install fzf` |
| MSYS2 (pacman) | `pacman -S $MINGW_PACKAGE_PREFIX-fzf` |
[choco]: https://chocolatey.org/packages/fzf
[scoop]: https://github.com/ScoopInstaller/Main/blob/master/bucket/fzf.json
[winget]: https://github.com/microsoft/winget-pkgs/tree/master/manifests/j/junegunn/fzf
[msys2]: https://packages.msys2.org/base/mingw-w64-fzf
### 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
```
The install script will add lines to your shell configuration file to modify
`$PATH` and set up shell integration.
### Binary releases
You can download the official fzf binaries from the releases page.
* https://github.com/junegunn/fzf/releases
### Setting up shell integration
Add the following line to your shell configuration file.
* bash
```sh
# Set up fzf key bindings and fuzzy completion
eval "$(fzf --bash)"
```
* zsh
```sh
# Set up fzf key bindings and fuzzy completion
source <(fzf --zsh)
```
* fish
```fish
# Set up fzf key bindings
fzf --fish | source
```
> [!NOTE]
> `--bash`, `--zsh`, and `--fish` options are only available in fzf 0.48.0 or
> later. If you have an older version of fzf, or want finer control, you can
> source individual script files in the [/shell](/shell) directory. The
> location of the files may vary depending on the package manager you use.
> Please refer to the package documentation for more information.
> (e.g. `apt show fzf`)
> [!TIP]
> You can disable CTRL-T, CTRL-R, or ALT-C bindings by setting the
> corresponding `*_COMMAND` variable to an empty string when sourcing the
> script. For example, to disable CTRL-R and ALT-C:
>
> * bash: `FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= eval "$(fzf --bash)"`
> * zsh: `FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= source <(fzf --zsh)`
> * fish: `fzf --fish | FZF_CTRL_R_COMMAND= FZF_ALT_C_COMMAND= source`
>
> Setting the variables after sourcing the script will have no effect.
### Vim/Neovim plugin
If you use [vim-plug](https://github.com/junegunn/vim-plug), add this to
your Vim configuration file:
```vim
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
```
* `junegunn/fzf` provides the basic library functions
* `fzf#install()` makes sure that you have the latest binary
* `junegunn/fzf.vim` is [a separate project](https://github.com/junegunn/fzf.vim)
that provides a variety of useful commands
To learn more about the Vim integration, see [README-VIM.md](README-VIM.md).
> [!TIP]
> If you use Neovim and prefer Lua-based plugins, check out
> [fzf-lua](https://github.com/ibhagwan/fzf-lua).
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 upgrade fzf`
- macports: `sudo port upgrade fzf`
- chocolatey: `choco upgrade fzf`
- vim-plug: `:PlugUpdate fzf`
Building fzf
------------
See [BUILD.md](BUILD.md).
Usage
-----
fzf will launch interactive finder, read the list from STDIN, and write the
selected item to STDOUT.
```sh
find * -type f | fzf > selected
```
Without STDIN pipe, fzf will traverse the file system under the current
directory to get the list of files.
```sh
vim $(fzf)
```
> [!NOTE]
> You can override the default behavior
> * Either by setting `$FZF_DEFAULT_COMMAND` to a command that generates the desired list
> * Or by setting `--walker`, `--walker-root`, and `--walker-skip` options in `$FZF_DEFAULT_OPTS`
> [!WARNING]
> 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
> ```
> [!TIP]
> 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.*
### Using the finder
- `CTRL-K` / `CTRL-J` (or `CTRL-P` / `CTRL-N`) 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
### Display modes
fzf by default runs in fullscreen mode, but there are other display modes.
#### `--height` mode
With `--height HEIGHT[%]`, fzf will start below the cursor with the given height.
```sh
fzf --height 40%
```
`reverse` layout and `--border` goes well with this option.
```sh
fzf --height 40% --layout reverse --border
```
By prepending `~` to the height, you're setting the maximum height.
```sh
# Will take as few lines as possible to display the list
seq 3 | fzf --height ~100%
seq 3000 | fzf --height ~100%
```
Height value can be a negative number.
```sh
# Screen height - 3
fzf --height -3
```
#### `--tmux` mode
With `--tmux` option, fzf will start in a tmux popup.
```sh
# --tmux [center|top|bottom|left|right][,SIZE[%]][,SIZE[%][,border-native]]
fzf --tmux center # Center, 50% width and height
fzf --tmux 80% # Center, 80% width and height
fzf --tmux 100%,50% # Center, 100% width and 50% height
fzf --tmux left,40% # Left, 40% width
fzf --tmux left,40%,90% # Left, 40% width, 90% height
fzf --tmux top,40% # Top, 40% height
fzf --tmux bottom,80%,40% # Bottom, 80% width, 40% height
```
`--tmux` is silently ignored when you're not on tmux.
> [!NOTE]
> If you're stuck with an old version of tmux that doesn't support popup,
> or if you want to open fzf in a regular tmux pane, check out
> [fzf-tmux](bin/fzf-tmux) script.
> [!TIP]
> You can add these options to `$FZF_DEFAULT_OPTS` so that they're applied by
> default. For example,
>
> ```sh
> # Open in tmux popup if on tmux, otherwise use --height mode
> export FZF_DEFAULT_OPTS='--height 40% --tmux bottom,40% --layout reverse --border top'
> ```
### 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
!fire`
| Token | Match type | Description |
| --------- | -------------------------------------- | ------------------------------------------ |
| `sbtrkt` | fuzzy-match | Items that match `sbtrkt` |
| `'wild` | exact-match (quoted) | Items that include `wild` |
| `'wild'` | exact-boundary-match (quoted both ends) | Items that include `wild` at word boundaries |
| `^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` |
If you don't prefer fuzzy matching and do not wish to "quote" every word,
start fzf with `-e` or `--exact` option. Note that when `--exact` is set,
`'`-prefix "unquotes" the term.
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$
```
### Environment variables
- `FZF_DEFAULT_COMMAND`
- Default command to use when input is tty
- e.g. `export FZF_DEFAULT_COMMAND='fd --type f'`
- `FZF_DEFAULT_OPTS`
- Default options
- e.g. `export FZF_DEFAULT_OPTS="--layout=reverse --inline-info"`
- `FZF_DEFAULT_OPTS_FILE`
- If you prefer to manage default options in a file, set this variable to
point to the location of the file
- e.g. `export FZF_DEFAULT_OPTS_FILE=~/.fzfrc`
> [!WARNING]
> `FZF_DEFAULT_COMMAND` is not used by shell integration due to the
> slight difference in requirements.
>
> * `CTRL-T` runs `$FZF_CTRL_T_COMMAND` to get a list of files and directories
> * `ALT-C` runs `$FZF_ALT_C_COMMAND` to get a list of directories
> * `vim ~/**
|
| `full` | 
|
| `minimal` | 
|
Here's an example based on the `full` preset:
```sh
git ls-files | fzf --style full \
--border --padding 1,2 \
--border-label ' Demo ' --input-label ' Input ' --header-label ' File Type ' \
--preview 'fzf-preview.sh {}' \
--bind 'result:transform-list-label:
if [[ -z $FZF_QUERY ]]; then
echo " $FZF_MATCH_COUNT items "
else
echo " $FZF_MATCH_COUNT matches for [$FZF_QUERY] "
fi
' \
--bind 'focus:transform-preview-label:[[ -n {} ]] && printf " Previewing [%s] " {}' \
--bind 'focus:+transform-header:file --brief {} || echo "No file selected"' \
--bind 'ctrl-r:change-list-label( Reloading the list )+reload(sleep 2; git ls-files)' \
--color 'border:#aaaaaa,label:#cccccc' \
--color 'preview-border:#9999cc,preview-label:#ccccff' \
--color 'list-border:#669966,list-label:#99cc99' \
--color 'input-border:#996666,input-label:#ffcccc' \
--color 'header-border:#6699cc,header-label:#99ccff'
```
### Options
See the man page (`fzf --man` or `man fzf`) for the full list of options.
### Demo
If you learn by watching videos, check out this screencast by [@samoshkin](https://github.com/samoshkin) to explore `fzf` features.
Examples
--------
* [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)
Key bindings for command-line
-----------------------------
By [setting up shell integration](#setting-up-shell-integration), you can use
the following key bindings in bash, zsh, and fish.
- `CTRL-T` - Paste the selected files and directories onto the command-line
- The list is generated using `--walker file,dir,follow,hidden` option
- You can override the behavior by setting `FZF_CTRL_T_COMMAND` to a custom command that generates the desired list
- Or you can set `--walker*` options in `FZF_CTRL_T_OPTS`
- Set `FZF_CTRL_T_OPTS` to pass additional options to fzf
```sh
# Preview file content using bat (https://github.com/sharkdp/bat)
export FZF_CTRL_T_OPTS="
--walker-skip .git,node_modules,target
--preview 'bat -n --color=always {}'
--bind 'ctrl-/:change-preview-window(down|hidden|)'"
```
- Can be disabled by setting `FZF_CTRL_T_COMMAND` to an empty string when
sourcing the script
- `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
- Press `ALT-R` to toggle "raw" mode where you can see the surrounding items
of a match. In this mode, you can press `CTRL-N` and `CTRL-P` to move
between the matching items only.
- Press `CTRL-/` or `ALT-/` to toggle line wrapping
- Set `FZF_CTRL_R_OPTS` to pass additional options to fzf
```sh
# CTRL-Y to copy the command into clipboard using pbcopy
export FZF_CTRL_R_OPTS="
--bind 'ctrl-y:execute-silent(echo -n {2..} | pbcopy)+abort'
--color header:italic
--header 'Press CTRL-Y to copy command into clipboard'"
```
- Can be disabled by setting `FZF_CTRL_R_COMMAND` to an empty string when
sourcing the script
- Custom override via a non-empty `FZF_CTRL_R_COMMAND` is not yet supported and will emit a warning
- `ALT-C` - cd into the selected directory
- The list is generated using `--walker dir,follow,hidden` option
- Set `FZF_ALT_C_COMMAND` to override the default command
- Or you can set `--walker-*` options in `FZF_ALT_C_OPTS`
- Set `FZF_ALT_C_OPTS` to pass additional options to fzf
```sh
# Print tree structure in the preview window
export FZF_ALT_C_OPTS="
--walker-skip .git,node_modules,target
--preview 'tree -C {}'"
```
- Can be disabled by setting `FZF_ALT_C_COMMAND` to an empty string when
sourcing the script
Display modes for these bindings can be separately configured via
`FZF_{CTRL_T,CTRL_R,ALT_C}_OPTS` or globally via `FZF_DEFAULT_OPTS`.
(e.g. `FZF_CTRL_R_OPTS='--tmux bottom,60% --height 60% --border top'`)
More tips can be found on [the wiki page](https://github.com/junegunn/fzf/wiki/Configuring-shell-key-bindings).
Fuzzy completion for bash and zsh
---------------------------------
### Files and directories
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]**
junegunn-fzf-78af442/SECURITY.md 0000664 0000000 0000000 00000002372 15072725200 0016264 0 ustar 00root root 0000000 0000000 # Security Reporting
If you wish to report a security vulnerability privately, we appreciate your diligence. Please follow the guidelines below to submit your report.
## Reporting
To report a security vulnerability, please provide the following information:
1. **PROJECT**
- https://github.com/junegunn/fzf
2. **PUBLIC**
- Indicate whether this vulnerability has already been publicly discussed or disclosed.
- If so, provide relevant links.
3. **DESCRIPTION**
- Provide a detailed description of the security vulnerability.
- Include as much information as possible to help us understand and address the issue.
Send this information, along with any additional relevant details, to