1fzf(1) fzf - a command-line fuzzy finder fzf(1)
2
6 fzf - a command-line fuzzy finder
7
10 fzf [options]
11
14 fzf is a general-purpose command-line fuzzy finder.
15
18 Search mode
19 -x, --extended
20 Extended-search mode. Since 0.10.9, this is enabled by default.
21 You can disable it with +x or --no-extended.
22 -e, --exact
24 Enable exact-match
25 -i Case-insensitive match (default: smart-case match)
27 +i Case-sensitive match
29 --literal
31 Do not normalize latin script letters for matching.
32 --scheme=SCHEME
34 Choose scoring scheme tailored for different types of input.
35 default Generic scoring scheme designed to work well with any
37 type of input
38 path Scoring scheme well suited for file paths
39 history Scoring scheme well suited for command history or any
40 input where chronological ordering is important
41 Sets --tiebreak=index as well.
42 --algo=TYPE
44 Fuzzy matching algorithm (default: v2)
45 v2 Optimal scoring algorithm (quality)
47 v1 Faster but not guaranteed to find the optimal result
48 (performance)
49 -n, --nth=N[,..]
52 Comma-separated list of field index expressions for limiting
53 search scope. See FIELD INDEX EXPRESSION for the details.
54 --with-nth=N[,..]
56 Transform the presentation of each line using field index ex‐
57 pressions
58 -d, --delimiter=STR
60 Field delimiter regex for --nth and --with-nth (default: AWK-
61 style)
62 --disabled
64 Do not perform search. With this option, fzf becomes a simple
65 selector interface rather than a "fuzzy finder". You can later
66 enable the search using enable-search or toggle-search action.
67 Search result
69 +s, --no-sort
70 Do not sort the result
71 --track
73 Make fzf track the current selection when the result list is up‐
74 dated. This can be useful when browsing logs using fzf with
75 sorting disabled. It is not recommended to use this option with
76 --tac as the resulting behavior can be confusing. Also, consider
77 using track action instead of this option.
78 e.g.
80 git log --oneline --graph --color=always | nl |
81 fzf --ansi --track --no-sort --layout=reverse-list
82 --tac Reverse the order of the input
84 e.g.
86 history | fzf --tac --no-sort
87 --tiebreak=CRI[,..]
89 Comma-separated list of sort criteria to apply when the scores
90 are tied.
91 length Prefers line with shorter length
93 chunk Prefers line with shorter matched chunk (delimited by
94 whitespaces)
95 begin Prefers line with matched substring closer to the begin‐
96 ning
97 end Prefers line with matched substring closer to the end
98 index Prefers line that appeared earlier in the input stream
99 - Each criterion should appear only once in the list
101 - index is only allowed at the end of the list
102 - index is implicitly appended to the list when not specified
103 - Default is length (or equivalently length,index)
104 - If end is found in the list, fzf will scan each line backwards
105 Interface
107 -m, --multi
108 Enable multi-select with tab/shift-tab. It optionally takes an
109 integer argument which denotes the maximum number of items that
110 can be selected.
111 +m, --no-multi
113 Disable multi-select
114 --no-mouse
116 Disable mouse
117 --bind=KEYBINDS
119 Comma-separated list of custom key bindings. See KEY/EVENT BIND‐
120 INGS for the details.
121 --cycle
123 Enable cyclic scroll
124 --keep-right
126 Keep the right end of the line visible when it's too long. Ef‐
127 fective only when the query string is empty.
128 --scroll-off=LINES
130 Number of screen lines to keep above or below when scrolling to
131 the top or to the bottom (default: 0).
132 --no-hscroll
134 Disable horizontal scroll
135 --hscroll-off=COLS
137 Number of screen columns to keep to the right of the highlighted
138 substring (default: 10). Setting it to a large value will cause
139 the text to be positioned on the center of the screen.
140 --filepath-word
142 Make word-wise movements and actions respect path separators.
143 The following actions are affected:
144 backward-kill-word
146 backward-word
147 forward-word
148 kill-word
149 --jump-labels=CHARS
151 Label characters for jump and jump-accept
152 Layout
154 --height=[~]HEIGHT[%]
155 Display fzf window below the cursor with the given height in‐
156 stead of using the full screen. When prefixed with ~, fzf will
157 automatically determine the height in the range according to the
158 input size. Note that adaptive height is not compatible with
159 top/bottom margin and padding given in percent size.
160 --min-height=HEIGHT
162 Minimum height when --height is given in percent (default: 10).
163 Ignored when --height is not specified.
164 --layout=LAYOUT
166 Choose the layout (default: default)
167 default Display from the bottom of the screen
169 reverse Display from the top of the screen
170 reverse-list Display from the top of the screen, prompt at the
171 bottom
172 --reverse
175 A synonym for --layout=reverse
176 --border[=BORDER_OPT]
179 Draw border around the finder
180 rounded Border with rounded corners (default)
182 sharp Border with sharp corners
183 bold Border with bold lines
184 double Border with double lines
185 block Border using block elements; suitable when using
186 different background colors
187 thinblock Border using legacy computing symbols; may not be
188 displayed on some terminals
189 horizontal Horizontal lines above and below the finder
190 vertical Vertical lines on each side of the finder
191 top (up)
192 bottom (down)
193 left
194 right
195 none
196 If you use a terminal emulator where each box-drawing character
198 takes 2 columns, try setting RUNEWIDTH_EASTASIAN environment
199 variable to 0 or 1. If the border is still not properly ren‐
200 dered, set --no-unicode.
201 --border-label[=LABEL]
204 Label to print on the horizontal border line. Should be used
205 with one of the following --border options.
206 * rounded
208 * sharp
209 * bold
210 * double
211 * horizontal
212 * top (up)
213 * bottom (down)
214 e.g.
216 # ANSI color codes are supported
217 # (with https://github.com/busyloop/lolcat)
218 label=$(curl -s http://metaphorpsum.com/sentences/1 | lolcat
219 -f)
220 # Border label at the center
222 fzf --height=10 --border --border-label="╢ $label ╟"
223 --color=label:italic:black
224 # Left-aligned (positive integer)
226 fzf --height=10 --border --border-label="╢ $label ╟" --border-
227 label-pos=3 --color=label:italic:black
228 # Right-aligned (negative integer) on the bottom line (:bot‐
230 tom)
231 fzf --height=10 --border --border-label="╢ $label ╟" --border-
232 label-pos=-3:bottom --color=label:italic:black
233 --border-label-pos[=N[:top|bottom]]
236 Position of the border label on the border line. Specify a posi‐
237 tive integer as the column position from the left. Specify a
238 negative integer to right-align the label. Label is printed on
239 the top border line by default, add :bottom to put it on the
240 border line on the bottom. The default value 0 (or center) will
241 put the label at the center of the border line.
242 --no-unicode
245 Use ASCII characters instead of Unicode drawing characters to
246 draw borders, the spinner and the horizontal separator.
247 --margin=MARGIN
250 Comma-separated expression for margins around the finder.
251 TRBL Same margin for top, right, bottom, and left
253 TB,RL Vertical, horizontal margin
254 T,RL,B Top, horizontal, bottom margin
255 T,R,B,L Top, right, bottom, left margin
256 Each part can be given in absolute number or in percentage rela‐
258 tive to the terminal size with % suffix.
259 e.g.
261 fzf --margin 10%
262 fzf --margin 1,5%
263 --padding=PADDING
265 Comma-separated expression for padding inside the border. Pad‐
266 ding is distinguishable from margin only when --border option is
267 used.
268 e.g.
270 fzf --margin 5% --padding 5% --border --preview 'cat {}' \
271 --color bg:#222222,preview-bg:#333333
272 TRBL Same padding for top, right, bottom, and left
274 TB,RL Vertical, horizontal padding
275 T,RL,B Top, horizontal, bottom padding
276 T,R,B,L Top, right, bottom, left padding
277 --info=STYLE
280 Determines the display style of finder info (match counters).
281 default Display on the next line to the prompt
283 right Display on the right end of the next line to
284 the prompt
285 inline Display on the same line with the default sepa‐
286 rator ' < '
287 inline:SEPARATOR Display on the same line with a non-default
288 separator
289 inline-right Display on the right end of the same line
290 hidden Do not display finder info
291 --no-info
294 A synonym for --info=hidden
295 --separator=STR
298 The given string will be repeated to form the horizontal separa‐
299 tor on the info line (default: '─' or '-' depending on --no-uni‐
300 code).
301 ANSI color codes are supported.
303 --no-separator
306 Do not display horizontal separator on the info line. A synonym
307 for --separator=''
308 --scrollbar=CHAR1[CHAR2]
311 Use the given character to render scrollbar. (default: '│' or
312 ':' depending on --no-unicode). The optional CHAR2 is used to
313 render scrollbar of the preview window.
314 --no-scrollbar
317 Do not display scrollbar. A synonym for --scrollbar=''
318 --prompt=STR
321 Input prompt (default: '> ')
322 --pointer=STR
324 Pointer to the current line (default: '>')
325 --marker=STR
327 Multi-select marker (default: '>')
328 --header=STR
330 The given string will be printed as the sticky header. The lines
331 are displayed in the given order from top to bottom regardless
332 of --layout option, and are not affected by --with-nth. ANSI
333 color codes are processed even when --ansi is not set.
334 --header-lines=N
336 The first N lines of the input are treated as the sticky header.
337 When --with-nth is set, the lines are transformed just like the
338 other lines that follow.
339 --header-first
341 Print header before the prompt line
342 --ellipsis=STR
344 Ellipsis to show when line is truncated (default: '..')
345 Display
347 --ansi Enable processing of ANSI color codes
348 --tabstop=SPACES
350 Number of spaces for a tab character (default: 8)
351 --color=[BASE_SCHEME][,COLOR_NAME[:ANSI_COLOR][:ANSI_ATTRIBUTES]]...
353 Color configuration. The name of the base color scheme is fol‐
354 lowed by custom color mappings.
355 BASE SCHEME:
357 (default: dark on 256-color terminal, otherwise 16)
358 dark Color scheme for dark 256-color terminal
360 light Color scheme for light 256-color terminal
361 16 Color scheme for 16-color terminal
362 bw No colors (equivalent to --no-color)
363 COLOR NAMES:
365 fg Text
366 preview-fg Preview window text
367 bg Background
368 preview-bg Preview window background
369 hl Highlighted substrings
370 fg+ Text (current line)
371 bg+ Background (current line)
372 gutter Gutter on the left
373 hl+ Highlighted substrings (current line)
374 query Query string
375 disabled Query string when search is disabled
376 (--disabled)
377 info Info line (match counters)
378 border Border around the window (--border and
379 --preview)
380 scrollbar Scrollbar
381 preview-border Border around the preview window (--pre‐
382 view)
383 preview-scrollbar Scrollbar
384 separator Horizontal separator on info line
385 label Border label (--border-label and --pre‐
386 view-label)
387 preview-label Border label of the preview window
388 (--preview-label)
389 prompt Prompt
390 pointer Pointer to the current line
391 marker Multi-select marker
392 spinner Streaming input indicator
393 header Header
394 ANSI COLORS:
396 -1 Default terminal foreground/background color
397 (or the original color of the text)
398 0 ~ 15 16 base colors
399 black
400 red
401 green
402 yellow
403 blue
404 magenta
405 cyan
406 white
407 bright-black (gray | grey)
408 bright-red
409 bright-green
410 bright-yellow
411 bright-blue
412 bright-magenta
413 bright-cyan
414 bright-white
415 16 ~ 255 ANSI 256 colors
416 #rrggbb 24-bit colors
417 ANSI ATTRIBUTES: (Only applies to foreground colors)
419 regular Clears previously set attributes; should precede
420 the other ones
421 bold
422 underline
423 reverse
424 dim
425 italic
426 strikethrough
427 EXAMPLES:
429 # Seoul256 theme with 8-bit colors
431 # (https://github.com/junegunn/seoul256.vim)
432 fzf --color='bg:237,bg+:236,info:143,border:240,spin‐
433 ner:108' \
434 --color='hl:65,fg:252,header:65,fg+:252' \
435 --color='pointer:161,marker:168,prompt:110,hl+:108'
436 # Seoul256 theme with 24-bit colors
438 fzf --color='bg:#4B4B4B,bg+:#3F3F3F,info:#BDBB72,bor‐
439 der:#6B6B6B,spinner:#98BC99' \
440 --color='hl:#719872,fg:#D9D9D9,header:#719872,fg+:#D9D9D9'
441 \
442 --color='pointer:#E12672,marker:#E17899,prompt:#98BEDE,hl+:#98BC99'
443 --no-bold
445 Do not use bold text
446 --black
448 Use black background
449 History
451 --history=HISTORY_FILE
452 Load search history from the specified file and update the file
453 on completion. When enabled, CTRL-N and CTRL-P are automati‐
454 cally remapped to next-history and prev-history.
455 --history-size=N
457 Maximum number of entries in the history file (default: 1000).
458 The file is automatically truncated when the number of the lines
459 exceeds the value.
460 Preview
462 --preview=COMMAND
463 Execute the given command for the current line and display the
464 result on the preview window. {} in the command is the place‐
465 holder that is replaced to the single-quoted string of the cur‐
466 rent line. To transform the replacement string, specify field
467 index expressions between the braces (See FIELD INDEX EXPRESSION
468 for the details).
469 e.g.
471 fzf --preview='head -$LINES {}'
472 ls -l | fzf --preview="echo user={3} when={-4..-2}; cat
473 {-1}" --header-lines=1
474 fzf exports $FZF_PREVIEW_LINES and $FZF_PREVIEW_COLUMNS so that
476 they represent the exact size of the preview window. (It also
477 overrides $LINES and $COLUMNS with the same values but they can
478 be reset by the default shell, so prefer to refer to the ones
479 with FZF_PREVIEW_ prefix.)
480 fzf also exports $FZF_PREVIEW_TOP and $FZF_PREVIEW_LEFT so that
482 the preview command can determine the position of the preview
483 window.
484 A placeholder expression starting with + flag will be replaced
486 to the space-separated list of the selected lines (or the cur‐
487 rent line if no selection was made) individually quoted.
488 e.g.
490 fzf --multi --preview='head -10 {+}'
491 git log --oneline | fzf --multi --preview 'git show {+1}'
492 When using a field index expression, leading and trailing white‐
494 space is stripped from the replacement string. To preserve the
495 whitespace, use the s flag.
496 Also, {q} is replaced to the current query string, and {n} is
498 replaced to zero-based ordinal index of the line. Use {+n} if
499 you want all index numbers when multiple lines are selected.
500 A placeholder expression with f flag is replaced to the path of
502 a temporary file that holds the evaluated list. This is useful
503 when you multi-select a large number of items and the length of
504 the evaluated string may exceed ARG_MAX.
505 e.g.
507 # Press CTRL-A to select 100K items and see the sum of all
508 the numbers.
509 # This won't work properly without 'f' flag due to ARG_MAX
510 limit.
511 seq 100000 | fzf --multi --bind ctrl-a:select-all \
512 --preview "awk '{sum+=\$1} END {print
513 sum}' {+f}"
514 Note that you can escape a placeholder pattern by prepending a
516 backslash.
517 Preview window will be updated even when there is no match for
519 the current query if any of the placeholder expressions evalu‐
520 ates to a non-empty string or {q} is in the command template.
521 Since 0.24.0, fzf can render partial preview content before the
523 preview command completes. ANSI escape sequence for clearing the
524 display (CSI 2 J) is supported, so you can use it to implement
525 preview window that is constantly updating.
526 e.g.
528 fzf --preview 'for i in $(seq 100000); do
529 (( i % 200 == 0 )) && printf "\033[2J"
530 echo "$i"
531 sleep 0.01
532 done'
533 fzf has experimental support for Kitty graphics protocol and
535 Sixel graphics. The following example uses
536 https://github.com/junegunn/fzf/blob/master/bin/fzf-preview.sh
537 script to render an image using either of the protocols inside
538 the preview window.
539 e.g.
541 fzf --preview='fzf-preview.sh {}'
542 --preview-label[=LABEL]
546 Label to print on the horizontal border line of the preview win‐
547 dow. Should be used with one of the following --preview-window
548 options.
549 * border-rounded (default on non-Windows platforms)
551 * border-sharp (default on Windows)
552 * border-bold
553 * border-double
554 * border-block
555 * border-thinblock
556 * border-horizontal
557 * border-top
558 * border-bottom
559 --preview-label-pos[=N[:top|bottom]]
562 Position of the border label on the border line of the preview
563 window. Specify a positive integer as the column position from
564 the left. Specify a negative integer to right-align the label.
565 Label is printed on the top border line by default, add :bottom
566 to put it on the border line on the bottom. The default value 0
567 (or center) will put the label at the center of the border line.
568 --preview-window=[POSITION][,SIZE[%]][,border-BOR‐
571 DER_OPT][,[no]wrap][,[no]follow][,[no]cycle][,[no]hidden][,+SCROLL[OFF‐
572 SETS][/DENOM]][,~HEADER_LINES][,default][,<SIZE_THRESHOLD(ALTERNA‐
573 TIVE_LAYOUT)]
574 POSITION: (default: right)
576 up
577 down
578 left
579 right
580 Determines the layout of the preview window.
582 * If the argument contains :hidden, the preview window will be
584 hidden by default until toggle-preview action is triggered.
585 * If size is given as 0, preview window will not be visible, but
587 fzf will still execute the command in the background.
588 * Long lines are truncated by default. Line wrap can be enabled
590 with wrap flag.
591 * Preview window will automatically scroll to the bottom when
593 follow flag is set, similarly to how tail -f works.
594 e.g.
596 fzf --preview-window follow --preview 'for i in
597 $(seq 100000); do
598 echo "$i"
599 sleep 0.01
600 (( i % 300 == 0 )) && printf "\033[2J"
601 done'
602 * Cyclic scrolling is enabled with cycle flag.
604 * To change the style of the border of the preview window, spec‐
606 ify one of the options for --border with border- prefix. e.g.
607 border-rounded (border with rounded edges, default), border-
608 sharp (border with sharp edges), border-left, border-none, etc.
609 * [:+SCROLL[OFFSETS][/DENOM]] determines the initial scroll off‐
611 set of the preview window.
612 - SCROLL can be either a numeric integer or a single-field in‐
614 dex expression that refers to a numeric integer.
615 - The optional OFFSETS part is for adjusting the base offset.
617 It should be given as a series of signed integers (-INTEGER or
618 +INTEGER).
619 - The final /DENOM part is for specifying a fraction of the
621 preview window height.
622 * ~HEADER_LINES keeps the top N lines as the fixed header so
624 that they are always visible.
625 * default resets all options previously set to the default.
627 e.g.
629 # Non-default scroll window positions and sizes
630 fzf --preview="head {}" --preview-window=up,30%
631 fzf --preview="file {}" --preview-window=down,1
632 # Initial scroll offset is set to the line number of
634 each line of
635 # git grep output *minus* 5 lines (-5)
636 git grep --line-number '' |
637 fzf --delimiter : --preview 'nl {1}' --preview-
638 window '+{2}-5'
639 # Preview with bat, matching line in the middle of
641 the window below
642 # the fixed header of the top 3 lines
643 #
644 # ~3 Top 3 lines as the fixed header
645 # +{2} Base scroll offset extracted from the sec‐
646 ond field
647 # +3 Extra offset to compensate for the 3-line
648 header
649 # /2 Put in the middle of the preview area
650 #
651 git grep --line-number '' |
652 fzf --delimiter : \
653 --preview 'bat --style=full --color=always
654 --highlight-line {2} {1}' \
655 --preview-window '~3,+{2}+3/2'
656 # Display top 3 lines as the fixed header
658 fzf --preview 'bat --style=full --color=always {}'
659 --preview-window '~3'
660 * You can specify an alternative set of options that are used
662 only when the size
663 of the preview window is below a certain threshold. Note that
664 only one
665 alternative layout is allowed.
666 e.g.
668 fzf --preview 'cat {}' --preview-window 'right,bor‐
669 der-left,<30(up,30%,border-bottom)'
670 Scripting
673 -q, --query=STR
674 Start the finder with the given query
675 -1, --select-1
677 If there is only one match for the initial query (--query), do
678 not start interactive finder and automatically select the only
679 match
680 -0, --exit-0
682 If there is no match for the initial query (--query), do not
683 start interactive finder and exit immediately
684 -f, --filter=STR
686 Filter mode. Do not start interactive finder. When used with
687 --no-sort, fzf becomes a fuzzy-version of grep.
688 --print-query
690 Print query as the first line
691 --expect=KEY[,..]
693 Comma-separated list of keys that can be used to complete fzf in
694 addition to the default enter key. When this option is set, fzf
695 will print the name of the key pressed as the first line of its
696 output (or as the second line if --print-query is also used).
697 The line will be empty if fzf is completed with the default en‐
698 ter key. If --expect option is specified multiple times, fzf
699 will expect the union of the keys. --no-expect will clear the
700 list.
701 e.g.
703 fzf --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
704 --read0
706 Read input delimited by ASCII NUL characters instead of newline
707 characters
708 --print0
710 Print output delimited by ASCII NUL characters instead of new‐
711 line characters
712 --no-clear
714 Do not clear finder interface on exit. If fzf was started in
715 full screen mode, it will not switch back to the original
716 screen, so you'll have to manually run tput rmcup to return.
717 This option can be used to avoid flickering of the screen when
718 your application needs to start fzf multiple times in order.
719 (Note that in most cases, it is preferable to use reload action
720 instead.)
721 e.g.
723 foo=$(seq 100 | fzf --no-clear) || (
724 # Need to manually switch back to the main screen when
725 cancelled
726 tput rmcup
727 exit 1
728 ) && seq "$foo" 100 | fzf
729 --sync Synchronous search for multi-staged filtering. If specified, fzf
732 will launch ncurses finder only after the input stream is com‐
733 plete.
734 e.g. fzf --multi | fzf --sync
736 --listen[=[ADDR:]PORT] --listen-unsafe[=[ADDR:]PORT]
738 Start HTTP server and listen on the given address. It allows ex‐
739 ternal processes to send actions to perform via POST method.
740 - If the port number is omitted or given as 0, fzf will automat‐
742 ically choose a port and export it as FZF_PORT environment vari‐
743 able to the child processes
744 - If FZF_API_KEY environment variable is set, the server would
746 require sending an API key with the same value in the x-api-key
747 HTTP header
748 - FZF_API_KEY is required for a non-localhost listen address
750 - To allow remote process execution, use --listen-unsafe
752 e.g.
754 # Start HTTP server on port 6266
755 fzf --listen 6266
756 # Get program state in JSON format (experimental)
758 curl localhost:6266
759 # Send action to the server
761 curl -XPOST localhost:6266 -d 'reload(seq 100)+change-
762 prompt(hundred> )'
763 # Start HTTP server on port 6266 with remote connections
765 allowed
766 # * Listening on non-localhost address requires using an
767 API key
768 export FZF_API_KEY="$(head -c 32 /dev/urandom | base64)"
769 fzf --listen 0.0.0.0:6266
770 # Send an authenticated action
772 curl -XPOST localhost:6266 -H "x-api-key: $FZF_API_KEY" -d
773 'change-query(yo)'
774 # Choose port automatically and export it as $FZF_PORT to
776 the child process
777 fzf --listen --bind 'start:execute-silent:echo $FZF_PORT >
778 /tmp/fzf-port'
779 --version
782 Display version information and exit
783 Note that most options have the opposite versions with --no- prefix.
786
789 FZF_DEFAULT_COMMAND
790 Default command to use when input is tty. On *nix systems, fzf
791 runs the command with $SHELL -c if SHELL is set, otherwise with
792 sh -c, so in this case make sure that the command is POSIX-com‐
793 pliant.
794 FZF_DEFAULT_OPTS
796 Default options. e.g. export FZF_DEFAULT_OPTS="--extended --cy‐
797 cle"
798 FZF_API_KEY
800 Can be used to require an API key when using --listen option. If
801 not set, no authentication will be required by the server. You
802 can set this value if you need to protect against DNS rebinding
803 and privilege escalation attacks.
804
807 0 Normal exit
808 1 No match
809 2 Error
810 130 Interrupted with CTRL-C or ESC
811
814 A field index expression can be a non-zero integer or a range expres‐
815 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
816 of field index expressions.
817 Examples
820 1 The 1st field
821 2 The 2nd field
822 -1 The last field
823 -2 The 2nd to last field
824 3..5 From the 3rd field to the 5th field
825 2.. From the 2nd field to the last field
826 ..-3 From the 1st field to the 3rd to the last field
827 .. All the fields
828
831 Unless specified otherwise, fzf will start in "extended-search mode".
832 In this mode, you can specify multiple patterns delimited by spaces,
833 such as: 'wild ^music .mp3$ sbtrkt !rmx
834 You can prepend a backslash to a space (\ ) to match a literal space
836 character.
837 Exact-match (quoted)
840 A term that is prefixed by a single-quote character (') is interpreted
841 as an "exact-match" (or "non-fuzzy") term. fzf will search for the ex‐
842 act occurrences of the string.
843 Anchored-match
846 A term can be prefixed by ^, or suffixed by $ to become an anchored-
847 match term. Then fzf will search for the lines that start with or end
848 with the given string. An anchored-match term is also an exact-match
849 term.
850 Negation
853 If a term is prefixed by !, fzf will exclude the lines that satisfy the
854 term from the result. In this case, fzf performs exact match by de‐
855 fault.
856 Exact-match by default
859 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
860 ing with ') every word, start fzf with -e or --exact option. Note that
861 when --exact is set, '-prefix "unquotes" the term.
862 OR operator
865 A single bar character term acts as an OR operator. For example, the
866 following query matches entries that start with core and end with ei‐
867 ther go, rb, or py.
868 e.g. ^core go$ | rb$ | py$
870
873 --bind option allows you to bind a key or an event to one or more ac‐
874 tions. You can use it to customize key bindings or implement dynamic
875 behaviors.
876 --bind takes a comma-separated list of binding expressions. Each bind‐
878 ing expression is KEY:ACTION or EVENT:ACTION.
879 e.g.
881 fzf --bind=ctrl-j:accept,ctrl-k:kill-line
882 AVAILABLE KEYS: (SYNONYMS)
885 ctrl-[a-z]
886 ctrl-space
887 ctrl-delete
888 ctrl-\
889 ctrl-]
890 ctrl-^ (ctrl-6)
891 ctrl-/ (ctrl-_)
892 ctrl-alt-[a-z]
893 alt-[*] (Any case-sensitive single character is allowed)
894 f[1-12]
895 enter (return ctrl-m)
896 space
897 bspace (bs)
898 alt-up
899 alt-down
900 alt-left
901 alt-right
902 alt-enter
903 alt-space
904 alt-bspace (alt-bs)
905 tab
906 btab (shift-tab)
907 esc
908 del
909 up
910 down
911 left
912 right
913 home
914 end
915 insert
916 pgup (page-up)
917 pgdn (page-down)
918 shift-up
919 shift-down
920 shift-left
921 shift-right
922 shift-delete
923 alt-shift-up
924 alt-shift-down
925 alt-shift-left
926 alt-shift-right
927 left-click
928 right-click
929 double-click
930 scroll-up
931 scroll-down
932 preview-scroll-up
933 preview-scroll-down
934 shift-left-click
935 shift-right-click
936 shift-scroll-up
937 shift-scroll-down
938 or any single character
939 AVAILABLE EVENTS:
942 start
943 Triggered only once when fzf finder starts. Since fzf consumes
944 the input stream asynchronously, the input list is not available
945 unless you use --sync.
946 e.g.
948 # Move cursor to the last item and select all items
949 seq 1000 | fzf --multi --sync --bind start:last+select-all
950 load
951 Triggered when the input stream is complete and the initial pro‐
952 cessing of the list is complete.
953 e.g.
955 # Change the prompt to "loaded" when the input stream is
956 complete
957 (seq 10; sleep 1; seq 11 20) | fzf --prompt 'Loading> '
958 --bind 'load:change-prompt:Loaded> '
959 change
960 Triggered whenever the query string is changed
961 e.g.
963 # Move cursor to the first entry whenever the query is
964 changed
965 fzf --bind change:first
966 focus
967 Triggered when the focus changes due to a vertical cursor move‐
968 ment or a search result update.
969 e.g.
971 fzf --bind 'focus:transform-preview-label:echo [ {} ]'
972 --preview 'cat {}'
973 # Any action bound to the event runs synchronously and thus
975 can make the interface sluggish
976 # e.g. lolcat isn't one of the fastest programs, and every
977 cursor movement in
978 # fzf will be noticeably affected by its execution
979 time
980 fzf --bind 'focus:transform-preview-label:echo [ {} ] |
981 lolcat -f' --preview 'cat {}'
982 # Beware not to introduce an infinite loop
984 seq 10 | fzf --bind 'focus:up' --cycle
985 one
986 Triggered when there's only one match. one:accept binding is
987 comparable to --select-1 option, but the difference is that
988 --select-1 is only effective before the interactive finder
989 starts but one event is triggered by the interactive finder.
990 e.g.
992 # Automatically select the only match
993 seq 10 | fzf --bind one:accept
994 zero
995 Triggered when there's no match. zero:abort binding is compara‐
996 ble to --exit-0 option, but the difference is that --exit-0 is
997 only effective before the interactive finder starts but zero
998 event is triggered by the interactive finder.
999 e.g.
1001 # Reload the candidate list when there's no match
1002 echo $RANDOM | fzf --bind 'zero:reload(echo $RANDOM)+clear-
1003 query' --height 3
1004 backward-eof
1006 Triggered when the query string is already empty and you try to
1007 delete it backward.
1008 e.g.
1010 fzf --bind backward-eof:abort
1011 AVAILABLE ACTIONS:
1014 A key or an event can be bound to one or more of the following actions.
1015 ACTION: DEFAULT BINDINGS (NOTES):
1017 abort ctrl-c ctrl-g ctrl-q esc
1018 accept enter double-click
1019 accept-non-empty (same as accept except that it pre‐
1020 vents fzf from exiting without selection)
1021 backward-char ctrl-b left
1022 backward-delete-char ctrl-h bspace
1023 backward-delete-char/eof (same as backward-delete-char except
1024 aborts fzf if query is empty)
1025 backward-kill-word alt-bs
1026 backward-word alt-b shift-left
1027 become(...) (replace fzf process with the speci‐
1028 fied command; see below for the details)
1029 beginning-of-line ctrl-a home
1030 cancel (clear query string if not empty,
1031 abort fzf otherwise)
1032 change-border-label(...) (change --border-label to the given
1033 string)
1034 change-header(...) (change header to the given string;
1035 doesn't affect --header-lines)
1036 change-preview(...) (change --preview option)
1037 change-preview-label(...) (change --preview-label to the given
1038 string)
1039 change-preview-window(...) (change --preview-window option; ro‐
1040 tate through the multiple option sets separated by '|')
1041 change-prompt(...) (change prompt to the given string)
1042 change-query(...) (change query string to the given
1043 string)
1044 clear-screen ctrl-l
1045 clear-selection (clear multi-selection)
1046 close (close preview window if open, abort
1047 fzf otherwise)
1048 clear-query (clear query string)
1049 delete-char del
1050 delete-char/eof ctrl-d (same as delete-char except
1051 aborts fzf if query is empty)
1052 deselect
1053 deselect-all (deselect all matches)
1054 disable-search (disable search functionality)
1055 down ctrl-j ctrl-n down
1056 enable-search (enable search functionality)
1057 end-of-line ctrl-e end
1058 execute(...) (see below for the details)
1059 execute-silent(...) (see below for the details)
1060 first (move to the first match; same as
1061 pos(1))
1062 forward-char ctrl-f right
1063 forward-word alt-f shift-right
1064 ignore
1065 jump (EasyMotion-like 2-keystroke movement)
1066 jump-accept (jump and accept)
1067 kill-line
1068 kill-word alt-d
1069 last (move to the last match; same as
1070 pos(-1))
1071 next-history (ctrl-n on --history)
1072 next-selected (move to the next selected item)
1073 page-down pgdn
1074 page-up pgup
1075 half-page-down
1076 half-page-up
1077 hide-preview
1078 offset-down (similar to CTRL-E of Vim)
1079 offset-up (similar to CTRL-Y of Vim)
1080 pos(...) (move cursor to the numeric position;
1081 negative number to count from the end)
1082 prev-history (ctrl-p on --history)
1083 prev-selected (move to the previous selected item)
1084 preview(...) (see below for the details)
1085 preview-down shift-down
1086 preview-up shift-up
1087 preview-page-down
1088 preview-page-up
1089 preview-half-page-down
1090 preview-half-page-up
1091 preview-bottom
1092 preview-top
1093 print-query (print query and exit)
1094 put (put the character to the prompt)
1095 put(...) (put the given string to the prompt)
1096 refresh-preview
1097 rebind(...) (rebind bindings after unbind)
1098 reload(...) (see below for the details)
1099 reload-sync(...) (see below for the details)
1100 replace-query (replace query string with the current
1101 selection)
1102 select
1103 select-all (select all matches)
1104 show-preview
1105 toggle (right-click)
1106 toggle-all (toggle all matches)
1107 toggle+down ctrl-i (tab)
1108 toggle-header
1109 toggle-in (--layout=reverse* ? toggle+up : tog‐
1110 gle+down)
1111 toggle-out (--layout=reverse* ? toggle+down :
1112 toggle+up)
1113 toggle-preview
1114 toggle-preview-wrap
1115 toggle-search (toggle search functionality)
1116 toggle-sort
1117 toggle-track
1118 toggle+up btab (shift-tab)
1119 track (track the current item; automatically
1120 disabled if focus changes)
1121 transform-border-label(...) (transform border label using an ex‐
1122 ternal command)
1123 transform-header(...) (transform header using an external
1124 command)
1125 transform-preview-label(...) (transform preview label using an ex‐
1126 ternal command)
1127 transform-prompt(...) (transform prompt string using an ex‐
1128 ternal command)
1129 transform-query(...) (transform query string using an ex‐
1130 ternal command)
1131 unbind(...) (unbind bindings)
1132 unix-line-discard ctrl-u
1133 unix-word-rubout ctrl-w
1134 up ctrl-k ctrl-p up
1135 yank ctrl-y
1136 ACTION COMPOSITION
1139 Multiple actions can be chained using + separator.
1140 e.g.
1142 fzf --multi --bind 'ctrl-a:select-all+accept'
1143 fzf --multi --bind 'ctrl-a:select-all' --bind 'ctrl-a:+accept'
1144 ACTION ARGUMENT
1147 An action denoted with (...) suffix takes an argument.
1148 e.g.
1150 fzf --bind 'ctrl-a:change-prompt(NewPrompt> )'
1151 fzf --bind 'ctrl-v:preview(cat {})' --preview-window hidden
1152 If the argument contains parentheses, fzf may fail to parse the expres‐
1154 sion. In that case, you can use any of the following alternative nota‐
1155 tions to avoid parse errors.
1156 action-name[...]
1158 action-name{...}
1159 action-name<...>
1160 action-name~...~
1161 action-name!...!
1162 action-name@...@
1163 action-name#...#
1164 action-name$...$
1165 action-name%...%
1166 action-name^...^
1167 action-name&...&
1168 action-name*...*
1169 action-name;...;
1170 action-name/.../
1171 action-name|...|
1172 action-name:...
1173 The last one is the special form that frees you from parse er‐
1174 rors as it does not expect the closing character. The catch is
1175 that it should be the last one in the comma-separated list of
1176 key-action pairs.
1177 COMMAND EXECUTION
1180 With execute(...) action, you can execute arbitrary commands without
1181 leaving fzf. For example, you can turn fzf into a simple file browser
1182 by binding enter key to less command like follows.
1183 fzf --bind "enter:execute(less {})"
1185 You can use the same placeholder expressions as in --preview.
1187 fzf switches to the alternate screen when executing a command. However,
1189 if the command is expected to complete quickly, and you are not inter‐
1190 ested in its output, you might want to use execute-silent instead,
1191 which silently executes the command without the switching. Note that
1192 fzf will not be responsive until the command is complete. For asynchro‐
1193 nous execution, start your command as a background process (i.e. ap‐
1194 pending &).
1195 On *nix systems, fzf runs the command with $SHELL -c if SHELL is set,
1197 otherwise with sh -c, so in this case make sure that the command is
1198 POSIX-compliant.
1199 become(...) action is similar to execute(...), but it replaces the cur‐
1201 rent fzf process with the specified command using execve(2) system
1202 call.
1203 fzf --bind "enter:become(vim {})"
1205 become(...) is not supported on Windows.
1207 RELOAD INPUT
1210 reload(...) action is used to dynamically update the input list without
1211 restarting fzf. It takes the same command template with placeholder ex‐
1212 pressions as execute(...).
1213 See https://github.com/junegunn/fzf/issues/1750 for more info.
1215 e.g.
1217 # Update the list of processes by pressing CTRL-R
1218 ps -ef | fzf --bind 'ctrl-r:reload(ps -ef)' --header 'Press CTRL-R
1219 to reload' \
1220 --header-lines=1 --layout=reverse
1221 # Integration with ripgrep
1223 RG_PREFIX="rg --column --line-number --no-heading --color=always
1224 --smart-case "
1225 INITIAL_QUERY="foobar"
1226 FZF_DEFAULT_COMMAND="$RG_PREFIX '$INITIAL_QUERY'" \
1227 fzf --bind "change:reload:$RG_PREFIX {q} || true" \
1228 --ansi --disabled --query "$INITIAL_QUERY"
1229 reload-sync(...) is a synchronous version of reload that replaces the
1231 list only when the command is complete. This is useful when the command
1232 takes a while to produce the initial output and you don't want fzf to
1233 run against an empty list while the command is running.
1234 e.g.
1237 # You can still filter and select entries from the initial list
1238 for 3 seconds
1239 seq 100 | fzf --bind 'load:reload-sync(sleep 3; seq 1000)+un‐
1240 bind(load)'
1241 PREVIEW BINDING
1244 With preview(...) action, you can specify multiple different preview
1245 commands in addition to the default preview command given by --preview
1246 option.
1247 e.g.
1249 # Default preview command with an extra preview binding
1250 fzf --preview 'file {}' --bind '?:preview:cat {}'
1251 # A preview binding with no default preview command
1253 # (Preview window is initially empty)
1254 fzf --bind '?:preview:cat {}'
1255 # Preview window hidden by default, it appears when you first hit
1257 '?'
1258 fzf --bind '?:preview:cat {}' --preview-window hidden
1259 CHANGE PREVIEW WINDOW ATTRIBUTES
1262 change-preview-window action can be used to change the properties of
1263 the preview window. Unlike the --preview-window option, you can specify
1264 multiple sets of options separated by '|' characters.
1265 e.g.
1267 # Rotate through the options using CTRL-/
1268 fzf --preview 'cat {}' --bind 'ctrl-/:change-preview-win‐
1269 dow(right,70%|down,40%,border-horizontal|hidden|right)'
1270 # The default properties given by `--preview-window` are inher‐
1272 ited, so an empty string in the list is interpreted as the default
1273 fzf --preview 'cat {}' --preview-window 'right,40%,border-left'
1274 --bind 'ctrl-/:change-preview-window(70%|down,border-top|hidden|)'
1275 # This is equivalent to toggle-preview action
1277 fzf --preview 'cat {}' --bind 'ctrl-/:change-preview-window(hid‐
1278 den|)'
1279
1282 Junegunn Choi (junegunn.c@gmail.com)
1283
1286 Project homepage:
1287 https://github.com/junegunn/fzf
1288 Extra Vim plugin:
1290 https://github.com/junegunn/fzf.vim
1291
1294 MIT
1295fzf 0.44.1 Nov 2023 fzf(1)