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 (equivalent to --no-color)
212 COLOR:
214 fg Text
215 bg Background
216 preview-fg Preview window text
217 preview-bg Preview window background
218 hl Highlighted substrings
219 fg+ Text (current line)
220 bg+ Background (current line)
221 gutter Gutter on the left (defaults to bg+)
222 hl+ Highlighted substrings (current line)
223 info Info
224 border Border of the preview window and horizontal sepa‐
225 rators (--border)
226 prompt Prompt
227 pointer Pointer to the current line
228 marker Multi-select marker
229 spinner Streaming input indicator
230 header Header
231 EXAMPLES:
233 # Seoul256 theme with 8-bit colors
235 # (https://github.com/junegunn/seoul256.vim)
236 fzf --color='bg:237,bg+:236,info:143,border:240,spin‐
237 ner:108' \
238 --color='hl:65,fg:252,header:65,fg+:252' \
239 --color='pointer:161,marker:168,prompt:110,hl+:108'
240 # Seoul256 theme with 24-bit colors
242 fzf --color='bg:#4B4B4B,bg+:#3F3F3F,info:#BDBB72,bor‐
243 der:#6B6B6B,spinner:#98BC99' \
244 --color='hl:#719872,fg:#D9D9D9,header:#719872,fg+:#D9D9D9'
245 \
246 --color='pointer:#E12672,marker:#E17899,prompt:#98BEDE,hl+:#98BC99'
247 --no-bold
249 Do not use bold text
250 --black
252 Use black background
253 History
255 --history=HISTORY_FILE
256 Load search history from the specified file and update the file
257 on completion. When enabled, CTRL-N and CTRL-P are automati‐
258 cally remapped to next-history and previous-history.
259 --history-size=N
261 Maximum number of entries in the history file (default: 1000).
262 The file is automatically truncated when the number of the lines
263 exceeds the value.
264 Preview
266 --preview=COMMAND
267 Execute the given command for the current line and display the
268 result on the preview window. {} in the command is the place‐
269 holder that is replaced to the single-quoted string of the cur‐
270 rent line. To transform the replacement string, specify field
271 index expressions between the braces (See FIELD INDEX EXPRESSION
272 for the details).
273 e.g.
275 fzf --preview='head -$LINES {}'
276 ls -l | fzf --preview="echo user={3} when={-4..-2}; cat
277 {-1}" --header-lines=1
278 fzf exports $FZF_PREVIEW_LINES and $FZF_PREVIEW_COLUMNS so that
280 they represent the exact size of the preview window. (It also
281 overrides $LINES and $COLUMNS with the same values but they can
282 be reset by the default shell, so prefer to refer to the ones
283 with FZF_PREVIEW_ prefix.)
284 A placeholder expression starting with + flag will be replaced
286 to the space-separated list of the selected lines (or the cur‐
287 rent line if no selection was made) individually quoted.
288 e.g.
290 fzf --multi --preview='head -10 {+}'
291 git log --oneline | fzf --multi --preview 'git show {+1}'
292 When using a field index expression, leading and trailing white‐
294 space is stripped from the replacement string. To preserve the
295 whitespace, use the s flag.
296 Also, {q} is replaced to the current query string, and {n} is
298 replaced to zero-based ordinal index of the line. Use {+n} if
299 you want all index numbers when multiple lines are selected.
300 A placeholder expression with f flag is replaced to the path of
302 a temporary file that holds the evaluated list. This is useful
303 when you multi-select a large number of items and the length of
304 the evaluated string may exceed ARG_MAX.
305 e.g.
307 # Press CTRL-A to select 100K items and see the sum of all
308 the numbers.
309 # This won't work properly without 'f' flag due to ARG_MAX
310 limit.
311 seq 100000 | fzf --multi --bind ctrl-a:select-all \
312 --preview "awk '{sum+=} END {print sum}'
313 {+f}"
314 Note that you can escape a placeholder pattern by prepending a
316 backslash.
317 Preview window will be updated even when there is no match for
319 the current query if any of the placeholder expressions evalu‐
320 ates to a non-empty string.
321 --preview-window=[POSITION][:SIZE[%]][:noborder][:wrap][:hidden]
323 Determines the layout of the preview window. If the argument
324 contains :hidden, the preview window will be hidden by default
325 until toggle-preview action is triggered. Long lines are trun‐
326 cated by default. Line wrap can be enabled with :wrap flag.
327 If size is given as 0, preview window will not be visible, but
329 fzf will still execute the command in the background.
330 POSITION: (default: right)
332 up
333 down
334 left
335 right
336 e.g.
338 fzf --preview="head {}" --preview-window=up:30%
339 fzf --preview="file {}" --preview-window=down:1
340 Scripting
342 -q, --query=STR
343 Start the finder with the given query
344 -1, --select-1
346 Automatically select the only match
347 -0, --exit-0
349 Exit immediately when there's no match
350 -f, --filter=STR
352 Filter mode. Do not start interactive finder. When used with
353 --no-sort, fzf becomes a fuzzy-version of grep.
354 --print-query
356 Print query as the first line
357 --expect=KEY[,..]
359 Comma-separated list of keys that can be used to complete fzf in
360 addition to the default enter key. When this option is set, fzf
361 will print the name of the key pressed as the first line of its
362 output (or as the second line if --print-query is also used).
363 The line will be empty if fzf is completed with the default
364 enter key. If --expect option is specified multiple times, fzf
365 will expect the union of the keys. --no-expect will clear the
366 list.
367 e.g.
369 fzf --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
370 --read0
372 Read input delimited by ASCII NUL characters instead of newline
373 characters
374 --print0
376 Print output delimited by ASCII NUL characters instead of new‐
377 line characters
378 --no-clear
380 Do not clear finder interface on exit. If fzf was started in
381 full screen mode, it will not switch back to the original
382 screen, so you'll have to manually run tput rmcup to return.
383 This option can be used to avoid flickering of the screen when
384 your application needs to start fzf multiple times in order.
385 --sync Synchronous search for multi-staged filtering. If specified, fzf
387 will launch ncurses finder only after the input stream is com‐
388 plete.
389 e.g. fzf --multi | fzf --sync
391 --version
393 Display version information and exit
394 Note that most options have the opposite versions with --no- prefix.
397
400 FZF_DEFAULT_COMMAND
401 Default command to use when input is tty. On *nix systems, fzf
402 runs the command with sh -c, so make sure that it's POSIX-com‐
403 pliant.
404 FZF_DEFAULT_OPTS
406 Default options. e.g. export FZF_DEFAULT_OPTS="--extended
407 --cycle"
408
411 0 Normal exit
412 1 No match
413 2 Error
414 130 Interrupted with CTRL-C or ESC
415
418 A field index expression can be a non-zero integer or a range expres‐
419 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
420 of field index expressions.
421 Examples
424 1 The 1st field
425 2 The 2nd field
426 -1 The last field
427 -2 The 2nd to last field
428 3..5 From the 3rd field to the 5th field
429 2.. From the 2nd field to the last field
430 ..-3 From the 1st field to the 3rd to the last field
431 .. All the fields
432
435 Unless specified otherwise, fzf will start in "extended-search mode".
436 In this mode, you can specify multiple patterns delimited by spaces,
437 such as: 'wild ^music .mp3$ sbtrkt !rmx
438 You can prepend a backslash to a space (\ ) to match a literal space
440 character.
441 Exact-match (quoted)
444 A term that is prefixed by a single-quote character (') is interpreted
445 as an "exact-match" (or "non-fuzzy") term. fzf will search for the
446 exact occurrences of the string.
447 Anchored-match
450 A term can be prefixed by ^, or suffixed by $ to become an anchored-
451 match term. Then fzf will search for the lines that start with or end
452 with the given string. An anchored-match term is also an exact-match
453 term.
454 Negation
457 If a term is prefixed by !, fzf will exclude the lines that satisfy the
458 term from the result. In this case, fzf performs exact match by
459 default.
460 Exact-match by default
463 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
464 ing with ') every word, start fzf with -e or --exact option. Note that
465 when --exact is set, '-prefix "unquotes" the term.
466 OR operator
469 A single bar character term acts as an OR operator. For example, the
470 following query matches entries that start with core and end with
471 either go, rb, or py.
472 e.g. ^core go$ | rb$ | py$
474
477 --bind option allows you to bind a key or an event to one or more
478 actions. You can use it to customize key bindings or implement dynamic
479 behaviors.
480 --bind takes a comma-separated list of binding expressions. Each bind‐
482 ing expression is KEY:ACTION or EVENT:ACTION.
483 e.g.
485 fzf --bind=ctrl-j:accept,ctrl-k:kill-line
486 AVAILABLE KEYS: (SYNONYMS)
489 ctrl-[a-z]
490 ctrl-space
491 ctrl-\
492 ctrl-]
493 ctrl-^ (ctrl-6)
494 ctrl-/ (ctrl-_)
495 ctrl-alt-[a-z]
496 alt-[a-z]
497 alt-[0-9]
498 f[1-12]
499 enter (return ctrl-m)
500 space
501 bspace (bs)
502 alt-up
503 alt-down
504 alt-left
505 alt-right
506 alt-enter
507 alt-space
508 alt-bspace (alt-bs)
509 alt-/
510 tab
511 btab (shift-tab)
512 esc
513 del
514 up
515 down
516 left
517 right
518 home
519 end
520 pgup (page-up)
521 pgdn (page-down)
522 shift-up
523 shift-down
524 shift-left
525 shift-right
526 left-click
527 right-click
528 double-click
529 or any single character
530 AVAILABLE EVENTS:
533 change (triggered whenever the query string is changed)
534 e.g.
536 # Moves cursor to the top (or bottom depending on --layout)
537 whenever the query is changed
538 fzf --bind change:top
539 AVAILABLE ACTIONS:
542 A key or an event can be bound to one or more of the following actions.
543 ACTION: DEFAULT BINDINGS (NOTES):
545 abort ctrl-c ctrl-g ctrl-q esc
546 accept enter double-click
547 accept-non-empty (same as accept except that it prevents fzf
548 from exiting without selection)
549 backward-char ctrl-b left
550 backward-delete-char ctrl-h bspace
551 backward-kill-word alt-bs
552 backward-word alt-b shift-left
553 beginning-of-line ctrl-a home
554 cancel (clear query string if not empty, abort fzf
555 otherwise)
556 clear-screen ctrl-l
557 clear-selection (clear multi-selection)
558 clear-query (clear query string)
559 delete-char del
560 delete-char/eof ctrl-d
561 deselect-all (deselect all matches)
562 down ctrl-j ctrl-n down
563 end-of-line ctrl-e end
564 execute(...) (see below for the details)
565 execute-silent(...) (see below for the details)
566 execute-multi(...) (deprecated in favor of {+} expression)
567 forward-char ctrl-f right
568 forward-word alt-f shift-right
569 ignore
570 jump (EasyMotion-like 2-keystroke movement)
571 jump-accept (jump and accept)
572 kill-line
573 kill-word alt-d
574 next-history (ctrl-n on --history)
575 page-down pgdn
576 page-up pgup
577 half-page-down
578 half-page-up
579 preview-down shift-down
580 preview-up shift-up
581 preview-page-down
582 preview-page-up
583 previous-history (ctrl-p on --history)
584 print-query (print query and exit)
585 reload(...) (see below for the details)
586 replace-query (replace query string with the current selec‐
587 tion)
588 select-all (select all matches)
589 toggle (right-click)
590 toggle-all (toggle all matches)
591 toggle+down ctrl-i (tab)
592 toggle-in (--layout=reverse* ? toggle+up : toggle+down)
593 toggle-out (--layout=reverse* ? toggle+down : toggle+up)
594 toggle-preview
595 toggle-preview-wrap
596 toggle-sort
597 toggle+up btab (shift-tab)
598 top (move to the top result)
599 unix-line-discard ctrl-u
600 unix-word-rubout ctrl-w
601 up ctrl-k ctrl-p up
602 yank ctrl-y
603 ACTION COMPOSITION
606 Multiple actions can be chained using + separator.
607 e.g.
609 fzf --bind 'ctrl-a:select-all+accept'
610 COMMAND EXECUTION
613 With execute(...) action, you can execute arbitrary commands without
614 leaving fzf. For example, you can turn fzf into a simple file browser
615 by binding enter key to less command like follows.
616 fzf --bind "enter:execute(less {})"
618 You can use the same placeholder expressions as in --preview.
620 If the command contains parentheses, fzf may fail to parse the expres‐
622 sion. In that case, you can use any of the following alternative nota‐
623 tions to avoid parse errors.
624 execute[...]
626 execute~...~
627 execute!...!
628 execute@...@
629 execute#...#
630 execute$...$
631 execute%...%
632 execute^...^
633 execute&...&
634 execute*...*
635 execute;...;
636 execute/.../
637 execute|...|
638 execute:...
639 The last one is the special form that frees you from parse
640 errors as it does not expect the closing character. The catch is
641 that it should be the last one in the comma-separated list of
642 key-action pairs.
643 fzf switches to the alternate screen when executing a command. However,
645 if the command is expected to complete quickly, and you are not inter‐
646 ested in its output, you might want to use execute-silent instead,
647 which silently executes the command without the switching. Note that
648 fzf will not be responsive until the command is complete. For asynchro‐
649 nous execution, start your command as a background process (i.e.
650 appending &).
651 RELOAD INPUT
654 reload(...) action is used to dynamically update the input list without
655 restarting fzf. It takes the same command template with placeholder
656 expressions as execute(...).
657 See https://github.com/junegunn/fzf/issues/1750 for more info.
659 e.g.
661 # Update the list of processes by pressing CTRL-R
662 ps -ef | fzf --bind 'ctrl-r:reload(ps -ef)' --header 'Press CTRL-R
663 to reload' \
664 --header-lines=1 --layout=reverse
665 # Integration with ripgrep
667 RG_PREFIX="rg --column --line-number --no-heading --color=always
668 --smart-case "
669 INITIAL_QUERY="foobar"
670 FZF_DEFAULT_COMMAND="$RG_PREFIX '$INITIAL_QUERY'" \
671 fzf --bind "change:reload:$RG_PREFIX {q} || true" \
672 --ansi --phony --query "$INITIAL_QUERY"
673
676 Junegunn Choi (junegunn.c@gmail.com)
677
680 Project homepage:
681 https://github.com/junegunn/fzf
682 Extra Vim plugin:
684 https://github.com/junegunn/fzf.vim
685
688 MIT
689fzf 0.20.0 Dec 2019 fzf(1)