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 --algo=TYPE
34 Fuzzy matching algorithm (default: v2)
35 v2 Optimal scoring algorithm (quality)
37 v1 Faster but not guaranteed to find the optimal result
38 (performance)
39 -n, --nth=N[,..]
42 Comma-separated list of field index expressions for limiting
43 search scope. See FIELD INDEX EXPRESSION for the details.
44 --with-nth=N[,..]
46 Transform the presentation of each line using field index
47 expressions
48 -d, --delimiter=STR
50 Field delimiter regex for --nth and --with-nth (default: AWK-
51 style)
52 --phony
54 Do not perform search. With this option, fzf becomes a simple
55 selector interface rather than a "fuzzy finder".
56 Search result
58 +s, --no-sort
59 Do not sort the result
60 --tac Reverse the order of the input
62 e.g.
64 history | fzf --tac --no-sort
65 --tiebreak=CRI[,..]
67 Comma-separated list of sort criteria to apply when the scores
68 are tied.
69 length Prefers line with shorter length
71 begin Prefers line with matched substring closer to the begin‐
72 ning
73 end Prefers line with matched substring closer to the end
74 index Prefers line that appeared earlier in the input stream
75 - Each criterion should appear only once in the list
77 - index is only allowed at the end of the list
78 - index is implicitly appended to the list when not specified
79 - Default is length (or equivalently length,index)
80 - If end is found in the list, fzf will scan each line backwards
81 Interface
83 -m, --multi
84 Enable multi-select with tab/shift-tab. It optionally takes an
85 integer argument which denotes the maximum number of items that
86 can be selected.
87 +m, --no-multi
89 Disable multi-select
90 --no-mouse
92 Disable mouse
93 --bind=KEYBINDS
95 Comma-separated list of custom key bindings. See KEY/EVENT BIND‐
96 INGS for the details.
97 --cycle
99 Enable cyclic scroll
100 --no-hscroll
102 Disable horizontal scroll
103 --hscroll-off=COL
105 Number of screen columns to keep to the right of the highlighted
106 substring (default: 10). Setting it to a large value will cause
107 the text to be positioned on the center of the screen.
108 --filepath-word
110 Make word-wise movements and actions respect path separators.
111 The following actions are affected:
112 backward-kill-word
114 backward-word
115 forward-word
116 kill-word
117 --jump-labels=CHARS
119 Label characters for jump and jump-accept
120 Layout
122 --height=HEIGHT[%]
123 Display fzf window below the cursor with the given height
124 instead of using the full screen.
125 --min-height=HEIGHT
127 Minimum height when --height is given in percent (default: 10).
128 Ignored when --height is not specified.
129 --layout=LAYOUT
131 Choose the layout (default: default)
132 default Display from the bottom of the screen
134 reverse Display from the top of the screen
135 reverse-list Display from the top of the screen, prompt at the
136 bottom
137 --reverse
140 A synonym for --layout=reverse
141 --border
144 Draw border above and below the finder
145 --no-unicode
148 Use ASCII characters instead of Unicode box drawing characters
149 to draw border
150 --margin=MARGIN
153 Comma-separated expression for margins around the finder.
154 TRBL Same margin for top, right, bottom, and left
156 TB,RL Vertical, horizontal margin
157 T,RL,B Top, horizontal, bottom margin
158 T,R,B,L Top, right, bottom, left margin
159 Each part can be given in absolute number or in percentage rela‐
161 tive to the terminal size with % suffix.
162 e.g.
164 fzf --margin 10%
165 fzf --margin 1,5%
166 --info=STYLE
168 Determines the display style of finder info.
169 default Display on the next line to the prompt
171 inline Display on the same line
172 hidden Do not display finder info
173 --no-info
176 A synonym for --info=hidden
177 --prompt=STR
180 Input prompt (default: '> ')
181 --header=STR
183 The given string will be printed as the sticky header. The lines
184 are displayed in the given order from top to bottom regardless
185 of --layout option, and are not affected by --with-nth. ANSI
186 color codes are processed even when --ansi is not set.
187 --header-lines=N
189 The first N lines of the input are treated as the sticky header.
190 When --with-nth is set, the lines are transformed just like the
191 other lines that follow.
192 Display
194 --ansi Enable processing of ANSI color codes
195 --tabstop=SPACES
197 Number of spaces for a tab character (default: 8)
198 --color=[BASE_SCHEME][,COLOR:ANSI]
200 Color configuration. The name of the base color scheme is fol‐
201 lowed by custom color mappings. Ansi color code of -1 denotes
202 terminal default foreground/background color. You can also spec‐
203 ify 24-bit color in #rrggbb format.
204 BASE SCHEME:
206 (default: dark on 256-color terminal, otherwise 16)
207 dark Color scheme for dark 256-color terminal
209 light Color scheme for light 256-color terminal
210 16 Color scheme for 16-color terminal
211 bw No colors
212 COLOR:
214 fg Text
215 bg Background
216 hl Highlighted substrings
217 fg+ Text (current line)
218 bg+ Background (current line)
219 gutter Gutter on the left (defaults to bg+)
220 hl+ Highlighted substrings (current line)
221 info Info
222 border Border of the preview window and horizontal separa‐
223 tors (--border)
224 prompt Prompt
225 pointer Pointer to the current line
226 marker Multi-select marker
227 spinner Streaming input indicator
228 header Header
229 EXAMPLES:
231 # Seoul256 theme with 8-bit colors
233 # (https://github.com/junegunn/seoul256.vim)
234 fzf --color='bg:237,bg+:236,info:143,border:240,spin‐
235 ner:108' \
236 --color='hl:65,fg:252,header:65,fg+:252' \
237 --color='pointer:161,marker:168,prompt:110,hl+:108'
238 # Seoul256 theme with 24-bit colors
240 fzf --color='bg:#4B4B4B,bg+:#3F3F3F,info:#BDBB72,bor‐
241 der:#6B6B6B,spinner:#98BC99' \
242 --color='hl:#719872,fg:#D9D9D9,header:#719872,fg+:#D9D9D9'
243 \
244 --color='pointer:#E12672,marker:#E17899,prompt:#98BEDE,hl+:#98BC99'
245 --no-bold
247 Do not use bold text
248 --black
250 Use black background
251 History
253 --history=HISTORY_FILE
254 Load search history from the specified file and update the file
255 on completion. When enabled, CTRL-N and CTRL-P are automati‐
256 cally remapped to next-history and previous-history.
257 --history-size=N
259 Maximum number of entries in the history file (default: 1000).
260 The file is automatically truncated when the number of the lines
261 exceeds the value.
262 Preview
264 --preview=COMMAND
265 Execute the given command for the current line and display the
266 result on the preview window. {} in the command is the place‐
267 holder that is replaced to the single-quoted string of the cur‐
268 rent line. To transform the replacement string, specify field
269 index expressions between the braces (See FIELD INDEX EXPRESSION
270 for the details).
271 e.g.
273 fzf --preview='head -$LINES {}'
274 ls -l | fzf --preview="echo user={3} when={-4..-2}; cat
275 {-1}" --header-lines=1
276 fzf exports $FZF_PREVIEW_LINES and $FZF_PREVIEW_COLUMNS so that
278 they represent the exact size of the preview window. (It also
279 overrides $LINES and $COLUMNS with the same values but they can
280 be reset by the default shell, so prefer to refer to the ones
281 with FZF_PREVIEW_ prefix.)
282 A placeholder expression starting with + flag will be replaced
284 to the space-separated list of the selected lines (or the cur‐
285 rent line if no selection was made) individually quoted.
286 e.g.
288 fzf --multi --preview='head -10 {+}'
289 git log --oneline | fzf --multi --preview 'git show {+1}'
290 When using a field index expression, leading and trailing white‐
292 space is stripped from the replacement string. To preserve the
293 whitespace, use the s flag.
294 Also, {q} is replaced to the current query string, and {n} is
296 replaced to zero-based ordinal index of the line. Use {+n} if
297 you want all index numbers when multiple lines are selected.
298 A placeholder expression with f flag is replaced to the path of
300 a temporary file that holds the evaluated list. This is useful
301 when you multi-select a large number of items and the length of
302 the evaluated string may exceed ARG_MAX.
303 e.g.
305 # Press CTRL-A to select 100K items and see the sum of all
306 the numbers.
307 # This won't work properly without 'f' flag due to ARG_MAX
308 limit.
309 seq 100000 | fzf --multi --bind ctrl-a:select-all \
310 --preview "awk '{sum+=} END {print sum}'
311 {+f}"
312 Note that you can escape a placeholder pattern by prepending a
314 backslash.
315 Preview window will be updated even when there is no match for
317 the current query if any of the placeholder expressions evalu‐
318 ates to a non-empty string.
319 --preview-window=[POSITION][:SIZE[%]][:noborder][:wrap][:hidden]
321 Determines the layout of the preview window. If the argument
322 contains :hidden, the preview window will be hidden by default
323 until toggle-preview action is triggered. Long lines are trun‐
324 cated by default. Line wrap can be enabled with :wrap flag.
325 If size is given as 0, preview window will not be visible, but
327 fzf will still execute the command in the background.
328 POSITION: (default: right)
330 up
331 down
332 left
333 right
334 e.g.
336 fzf --preview="head {}" --preview-window=up:30%
337 fzf --preview="file {}" --preview-window=down:1
338 Scripting
340 -q, --query=STR
341 Start the finder with the given query
342 -1, --select-1
344 Automatically select the only match
345 -0, --exit-0
347 Exit immediately when there's no match
348 -f, --filter=STR
350 Filter mode. Do not start interactive finder. When used with
351 --no-sort, fzf becomes a fuzzy-version of grep.
352 --print-query
354 Print query as the first line
355 --expect=KEY[,..]
357 Comma-separated list of keys that can be used to complete fzf in
358 addition to the default enter key. When this option is set, fzf
359 will print the name of the key pressed as the first line of its
360 output (or as the second line if --print-query is also used).
361 The line will be empty if fzf is completed with the default
362 enter key. If --expect option is specified multiple times, fzf
363 will expect the union of the keys. --no-expect will clear the
364 list.
365 e.g.
367 fzf --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
368 --read0
370 Read input delimited by ASCII NUL characters instead of newline
371 characters
372 --print0
374 Print output delimited by ASCII NUL characters instead of new‐
375 line characters
376 --no-clear
378 Do not clear finder interface on exit. If fzf was started in
379 full screen mode, it will not switch back to the original
380 screen, so you'll have to manually run tput rmcup to return.
381 This option can be used to avoid flickering of the screen when
382 your application needs to start fzf multiple times in order.
383 --sync Synchronous search for multi-staged filtering. If specified, fzf
385 will launch ncurses finder only after the input stream is com‐
386 plete.
387 e.g. fzf --multi | fzf --sync
389 --version
391 Display version information and exit
392 Note that most options have the opposite versions with --no- prefix.
395
398 FZF_DEFAULT_COMMAND
399 Default command to use when input is tty. On *nix systems, fzf
400 runs the command with sh -c, so make sure that it's POSIX-com‐
401 pliant.
402 FZF_DEFAULT_OPTS
404 Default options. e.g. export FZF_DEFAULT_OPTS="--extended
405 --cycle"
406
409 0 Normal exit
410 1 No match
411 2 Error
412 130 Interrupted with CTRL-C or ESC
413
416 A field index expression can be a non-zero integer or a range expres‐
417 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
418 of field index expressions.
419 Examples
422 1 The 1st field
423 2 The 2nd field
424 -1 The last field
425 -2 The 2nd to last field
426 3..5 From the 3rd field to the 5th field
427 2.. From the 2nd field to the last field
428 ..-3 From the 1st field to the 3rd to the last field
429 .. All the fields
430
433 Unless specified otherwise, fzf will start in "extended-search mode".
434 In this mode, you can specify multiple patterns delimited by spaces,
435 such as: 'wild ^music .mp3$ sbtrkt !rmx
436 You can prepend a backslash to a space (\ ) to match a literal space
438 character.
439 Exact-match (quoted)
442 A term that is prefixed by a single-quote character (') is interpreted
443 as an "exact-match" (or "non-fuzzy") term. fzf will search for the
444 exact occurrences of the string.
445 Anchored-match
448 A term can be prefixed by ^, or suffixed by $ to become an anchored-
449 match term. Then fzf will search for the lines that start with or end
450 with the given string. An anchored-match term is also an exact-match
451 term.
452 Negation
455 If a term is prefixed by !, fzf will exclude the lines that satisfy the
456 term from the result. In this case, fzf performs exact match by
457 default.
458 Exact-match by default
461 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
462 ing with ') every word, start fzf with -e or --exact option. Note that
463 when --exact is set, '-prefix "unquotes" the term.
464 OR operator
467 A single bar character term acts as an OR operator. For example, the
468 following query matches entries that start with core and end with
469 either go, rb, or py.
470 e.g. ^core go$ | rb$ | py$
472
475 --bind option allows you to bind a key or an event to one or more
476 actions. You can use it to customize key bindings or implement dynamic
477 behaviors.
478 --bind takes a comma-separated list of binding expressions. Each bind‐
480 ing expression is KEY:ACTION or EVENT:ACTION.
481 e.g.
483 fzf --bind=ctrl-j:accept,ctrl-k:kill-line
484 AVAILABLE KEYS: (SYNONYMS)
487 ctrl-[a-z]
488 ctrl-space
489 ctrl-\
490 ctrl-]
491 ctrl-^ (ctrl-6)
492 ctrl-/ (ctrl-_)
493 ctrl-alt-[a-z]
494 alt-[a-z]
495 alt-[0-9]
496 f[1-12]
497 enter (return ctrl-m)
498 space
499 bspace (bs)
500 alt-up
501 alt-down
502 alt-left
503 alt-right
504 alt-enter
505 alt-space
506 alt-bspace (alt-bs)
507 alt-/
508 tab
509 btab (shift-tab)
510 esc
511 del
512 up
513 down
514 left
515 right
516 home
517 end
518 pgup (page-up)
519 pgdn (page-down)
520 shift-up
521 shift-down
522 shift-left
523 shift-right
524 left-click
525 right-click
526 double-click
527 or any single character
528 AVAILABLE EVENTS:
531 change (triggered whenever the query string is changed)
532 e.g.
534 # Moves cursor to the top (or bottom depending on --layout)
535 whenever the query is changed
536 fzf --bind change:top
537 AVAILABLE ACTIONS:
540 A key or an event can be bound to one or more of the following actions.
541 ACTION: DEFAULT BINDINGS (NOTES):
543 abort ctrl-c ctrl-g ctrl-q esc
544 accept enter double-click
545 accept-non-empty (same as accept except that it prevents fzf
546 from exiting without selection)
547 backward-char ctrl-b left
548 backward-delete-char ctrl-h bspace
549 backward-kill-word alt-bs
550 backward-word alt-b shift-left
551 beginning-of-line ctrl-a home
552 cancel (clears query string if not empty, aborts fzf
553 otherwise)
554 clear-screen ctrl-l
555 delete-char del
556 delete-char/eof ctrl-d
557 deselect-all
558 down ctrl-j ctrl-n down
559 end-of-line ctrl-e end
560 execute(...) (see below for the details)
561 execute-silent(...) (see below for the details)
562 execute-multi(...) (deprecated in favor of {+} expression)
563 forward-char ctrl-f right
564 forward-word alt-f shift-right
565 ignore
566 jump (EasyMotion-like 2-keystroke movement)
567 jump-accept (jump and accept)
568 kill-line
569 kill-word alt-d
570 next-history (ctrl-n on --history)
571 page-down pgdn
572 page-up pgup
573 half-page-down
574 half-page-up
575 preview-down shift-down
576 preview-up shift-up
577 preview-page-down
578 preview-page-up
579 previous-history (ctrl-p on --history)
580 print-query (print query and exit)
581 reload(...) (see below for the details)
582 replace-query (replace query string with the current selec‐
583 tion)
584 select-all
585 toggle (right-click)
586 toggle-all
587 toggle+down ctrl-i (tab)
588 toggle-in (--layout=reverse* ? toggle+up : toggle+down)
589 toggle-out (--layout=reverse* ? toggle+down : toggle+up)
590 toggle-preview
591 toggle-preview-wrap
592 toggle-sort
593 toggle+up btab (shift-tab)
594 top (move to the top result)
595 unix-line-discard ctrl-u
596 unix-word-rubout ctrl-w
597 up ctrl-k ctrl-p up
598 yank ctrl-y
599 ACTION COMPOSITION
602 Multiple actions can be chained using + separator.
603 e.g.
605 fzf --bind 'ctrl-a:select-all+accept'
606 COMMAND EXECUTION
609 With execute(...) action, you can execute arbitrary commands without
610 leaving fzf. For example, you can turn fzf into a simple file browser
611 by binding enter key to less command like follows.
612 fzf --bind "enter:execute(less {})"
614 You can use the same placeholder expressions as in --preview.
616 If the command contains parentheses, fzf may fail to parse the expres‐
618 sion. In that case, you can use any of the following alternative nota‐
619 tions to avoid parse errors.
620 execute[...]
622 execute~...~
623 execute!...!
624 execute@...@
625 execute#...#
626 execute$...$
627 execute%...%
628 execute^...^
629 execute&...&
630 execute*...*
631 execute;...;
632 execute/.../
633 execute|...|
634 execute:...
635 The last one is the special form that frees you from parse
636 errors as it does not expect the closing character. The catch is
637 that it should be the last one in the comma-separated list of
638 key-action pairs.
639 fzf switches to the alternate screen when executing a command. However,
641 if the command is expected to complete quickly, and you are not inter‐
642 ested in its output, you might want to use execute-silent instead,
643 which silently executes the command without the switching. Note that
644 fzf will not be responsive until the command is complete. For asynchro‐
645 nous execution, start your command as a background process (i.e.
646 appending &).
647 RELOAD INPUT
650 reload(...) action is used to dynamically update the input list without
651 restarting fzf. It takes the same command template with placeholder
652 expressions as execute(...).
653 See https://github.com/junegunn/fzf/issues/1750 for more info.
655 e.g.
657 # Update the list of processes by pressing CTRL-R
658 ps -ef | fzf --bind 'ctrl-r:reload(ps -ef)' --header 'Press CTRL-R
659 to reload' \
660 --header-lines=1 --layout=reverse
661 # Integration with ripgrep
663 RG_PREFIX="rg --column --line-number --no-heading --color=always
664 --smart-case "
665 INITIAL_QUERY="foobar"
666 FZF_DEFAULT_COMMAND="$RG_PREFIX '$INITIAL_QUERY'" \
667 fzf --bind "change:reload:$RG_PREFIX {q} || true" \
668 --ansi --phony --query "$INITIAL_QUERY"
669
672 Junegunn Choi (junegunn.c@gmail.com)
673
676 Project homepage:
677 https://github.com/junegunn/fzf
678 Extra Vim plugin:
680 https://github.com/junegunn/fzf.vim
681
684 MIT
685fzf 0.19.0 Nov 2019 fzf(1)