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 Search result
54 +s, --no-sort
55 Do not sort the result
56 --tac Reverse the order of the input
58 e.g. history | fzf --tac --no-sort
60 --tiebreak=CRI[,..]
62 Comma-separated list of sort criteria to apply when the scores
63 are tied.
64 length Prefers line with shorter length
66 begin Prefers line with matched substring closer to the begin‐
67 ning
68 end Prefers line with matched substring closer to the end
69 index Prefers line that appeared earlier in the input stream
70 - Each criterion should appear only once in the list
72 - index is only allowed at the end of the list
73 - index is implicitly appended to the list when not specified
74 - Default is length (or equivalently length,index)
75 - If end is found in the list, fzf will scan each line backwards
76 Interface
78 -m, --multi
79 Enable multi-select with tab/shift-tab
80 +m, --no-multi
82 Disable multi-select
83 --no-mouse
85 Disable mouse
86 --bind=KEYBINDS
88 Comma-separated list of custom key bindings. See KEY BINDINGS
89 for the details.
90 --cycle
92 Enable cyclic scroll
93 --no-hscroll
95 Disable horizontal scroll
96 --hscroll-off=COL
98 Number of screen columns to keep to the right of the highlighted
99 substring (default: 10). Setting it to a large value will cause
100 the text to be positioned on the center of the screen.
101 --filepath-word
103 Make word-wise movements and actions respect path separators.
104 The following actions are affected:
105 backward-kill-word
107 backward-word
108 forward-word
109 kill-word
110 --jump-labels=CHARS
112 Label characters for jump and jump-accept
113 Layout
115 --height=HEIGHT[%]
116 Display fzf window below the cursor with the given height
117 instead of using the full screen.
118 --min-height=HEIGHT
120 Minimum height when --height is given in percent (default: 10).
121 Ignored when --height is not specified.
122 --layout=LAYOUT
124 Choose the layout (default: default)
125 default Display from the bottom of the screen
127 reverse Display from the top of the screen
128 reverse-list Display from the top of the screen, prompt at the
129 bottom
130 --reverse
133 A synonym for --layout=reverse
134 --border
137 Draw border above and below the finder
138 --no-unicode
141 Use ASCII characters instead of Unicode box drawing characters
142 to draw border
143 --margin=MARGIN
146 Comma-separated expression for margins around the finder.
147 TRBL Same margin for top, right, bottom, and left
149 TB,RL Vertical, horizontal margin
150 T,RL,B Top, horizontal, bottom margin
151 T,R,B,L Top, right, bottom, left margin
152 Each part can be given in absolute number or in percentage rela‐
154 tive to the terminal size with % suffix.
155 e.g. fzf --margin 10%
157 fzf --margin 1,5%
158 --inline-info
160 Display finder info inline with the query
161 --prompt=STR
163 Input prompt (default: '> ')
164 --header=STR
166 The given string will be printed as the sticky header. The lines
167 are displayed in the given order from top to bottom regardless
168 of --layout option, and are not affected by --with-nth. ANSI
169 color codes are processed even when --ansi is not set.
170 --header-lines=N
172 The first N lines of the input are treated as the sticky header.
173 When --with-nth is set, the lines are transformed just like the
174 other lines that follow.
175 Display
177 --ansi Enable processing of ANSI color codes
178 --tabstop=SPACES
180 Number of spaces for a tab character (default: 8)
181 --color=[BASE_SCHEME][,COLOR:ANSI]
183 Color configuration. The name of the base color scheme is fol‐
184 lowed by custom color mappings. Ansi color code of -1 denotes
185 terminal default foreground/background color. You can also spec‐
186 ify 24-bit color in #rrggbb format.
187 e.g. fzf --color=bg+:24
189 fzf --color=light,fg:232,bg:255,bg+:116,info:27
190 BASE SCHEME:
192 (default: dark on 256-color terminal, otherwise 16)
193 dark Color scheme for dark 256-color terminal
195 light Color scheme for light 256-color terminal
196 16 Color scheme for 16-color terminal
197 bw No colors
198 COLOR:
200 fg Text
201 bg Background
202 hl Highlighted substrings
203 fg+ Text (current line)
204 bg+ Background (current line)
205 gutter Gutter on the left (defaults to bg+)
206 hl+ Highlighted substrings (current line)
207 info Info
208 border Border of the preview window and horizontal separa‐
209 tors (--border)
210 prompt Prompt
211 pointer Pointer to the current line
212 marker Multi-select marker
213 spinner Streaming input indicator
214 header Header
215 --no-bold
217 Do not use bold text
218 --black
220 Use black background
221 History
223 --history=HISTORY_FILE
224 Load search history from the specified file and update the file
225 on completion. When enabled, CTRL-N and CTRL-P are automati‐
226 cally remapped to next-history and previous-history.
227 --history-size=N
229 Maximum number of entries in the history file (default: 1000).
230 The file is automatically truncated when the number of the lines
231 exceeds the value.
232 Preview
234 --preview=COMMAND
235 Execute the given command for the current line and display the
236 result on the preview window. {} in the command is the place‐
237 holder that is replaced to the single-quoted string of the cur‐
238 rent line. To transform the replacement string, specify field
239 index expressions between the braces (See FIELD INDEX EXPRESSION
240 for the details).
241 e.g. fzf --preview='head -$LINES {}'
243 ls -l | fzf --preview="echo user={3} when={-4..-2}; cat
244 {-1}" --header-lines=1
245 fzf exports $FZF_PREVIEW_LINES and $FZF_PREVIEW_COLUMNS so that
247 they represent the exact size of the preview window. (It also
248 overrides $LINES and $COLUMNS with the same values but they can
249 be reset by the default shell, so prefer to refer to the ones
250 with FZF_PREVIEW_ prefix.)
251 A placeholder expression starting with + flag will be replaced
253 to the space-separated list of the selected lines (or the cur‐
254 rent line if no selection was made) individually quoted.
255 e.g. fzf --multi --preview='head -10 {+}'
257 git log --oneline | fzf --multi --preview 'git show {+1}'
258 When using a field index expression, leading and trailing white‐
260 space is stripped from the replacement string. To preserve the
261 whitespace, use the s flag.
262 Also, {q} is replaced to the current query string, and {n} is
264 replaced to zero-based ordinal index of the line. Use {+n} if
265 you want all index numbers when multiple lines are selected.
266 Note that you can escape a placeholder pattern by prepending a
268 backslash.
269 Preview window will be updated even when there is no match for
271 the current query if any of the placeholder expressions evalu‐
272 ates to a non-empty string.
273 --preview-window=[POSITION][:SIZE[%]][:wrap][:hidden]
275 Determine the layout of the preview window. If the argument ends
276 with :hidden, the preview window will be hidden by default until
277 toggle-preview action is triggered. Long lines are truncated by
278 default. Line wrap can be enabled with :wrap flag.
279 If size is given as 0, preview window will not be visible, but
281 fzf will still execute the command in the background.
282 POSITION: (default: right)
284 up
285 down
286 left
287 right
288 e.g. fzf --preview="head {}" --preview-window=up:30%
290 fzf --preview="file {}" --preview-window=down:1
291 Scripting
293 -q, --query=STR
294 Start the finder with the given query
295 -1, --select-1
297 Automatically select the only match
298 -0, --exit-0
300 Exit immediately when there's no match
301 -f, --filter=STR
303 Filter mode. Do not start interactive finder. When used with
304 --no-sort, fzf becomes a fuzzy-version of grep.
305 --print-query
307 Print query as the first line
308 --expect=KEY[,..]
310 Comma-separated list of keys that can be used to complete fzf in
311 addition to the default enter key. When this option is set, fzf
312 will print the name of the key pressed as the first line of its
313 output (or as the second line if --print-query is also used).
314 The line will be empty if fzf is completed with the default
315 enter key. If --expect option is specified multiple times, fzf
316 will expect the union of the keys. --no-expect will clear the
317 list.
318 e.g. fzf --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
320 --read0
322 Read input delimited by ASCII NUL characters instead of newline
323 characters
324 --print0
326 Print output delimited by ASCII NUL characters instead of new‐
327 line characters
328 --no-clear
330 Do not clear finder interface on exit. If fzf was started in
331 full screen mode, it will not switch back to the original
332 screen, so you'll have to manually run tput rmcup to return.
333 This option can be used to avoid flickering of the screen when
334 your application needs to start fzf multiple times in order.
335 --sync Synchronous search for multi-staged filtering. If specified, fzf
337 will launch ncurses finder only after the input stream is com‐
338 plete.
339 e.g. fzf --multi | fzf --sync
341 --version
343 Display version information and exit
344 Note that most options have the opposite versions with --no- prefix.
347
350 FZF_DEFAULT_COMMAND
351 Default command to use when input is tty. On *nix systems, fzf
352 runs the command with sh -c, so make sure that it's POSIX-com‐
353 pliant.
354 FZF_DEFAULT_OPTS
356 Default options. e.g. export FZF_DEFAULT_OPTS="--extended
357 --cycle"
358
361 0 Normal exit
362 1 No match
363 2 Error
364 130 Interrupted with CTRL-C or ESC
365
368 A field index expression can be a non-zero integer or a range expres‐
369 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
370 of field index expressions.
371 Examples
374 1 The 1st field
375 2 The 2nd field
376 -1 The last field
377 -2 The 2nd to last field
378 3..5 From the 3rd field to the 5th field
379 2.. From the 2nd field to the last field
380 ..-3 From the 1st field to the 3rd to the last field
381 .. All the fields
382
385 Unless specified otherwise, fzf will start in "extended-search mode".
386 In this mode, you can specify multiple patterns delimited by spaces,
387 such as: 'wild ^music .mp3$ sbtrkt !rmx
388 You can prepend a backslash to a space (\ ) to match a literal space
390 character.
391 Exact-match (quoted)
394 A term that is prefixed by a single-quote character (') is interpreted
395 as an "exact-match" (or "non-fuzzy") term. fzf will search for the
396 exact occurrences of the string.
397 Anchored-match
400 A term can be prefixed by ^, or suffixed by $ to become an anchored-
401 match term. Then fzf will search for the lines that start with or end
402 with the given string. An anchored-match term is also an exact-match
403 term.
404 Negation
407 If a term is prefixed by !, fzf will exclude the lines that satisfy the
408 term from the result. In this case, fzf performs exact match by
409 default.
410 Exact-match by default
413 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
414 ing with ') every word, start fzf with -e or --exact option. Note that
415 when --exact is set, '-prefix "unquotes" the term.
416 OR operator
419 A single bar character term acts as an OR operator. For example, the
420 following query matches entries that start with core and end with
421 either go, rb, or py.
422 e.g. ^core go$ | rb$ | py$
424
427 You can customize key bindings of fzf with --bind option which takes a
428 comma-separated list of key binding expressions. Each key binding
429 expression follows the following format: KEY:ACTION
430 e.g. fzf --bind=ctrl-j:accept,ctrl-k:kill-line
432 AVAILABLE KEYS: (SYNONYMS)
434 ctrl-[a-z]
435 ctrl-space
436 ctrl-alt-[a-z]
437 alt-[a-z]
438 alt-[0-9]
439 f[1-12]
440 enter (return ctrl-m)
441 space
442 bspace (bs)
443 alt-up
444 alt-down
445 alt-left
446 alt-right
447 alt-enter
448 alt-space
449 alt-bspace (alt-bs)
450 alt-/
451 tab
452 btab (shift-tab)
453 esc
454 del
455 up
456 down
457 left
458 right
459 home
460 end
461 pgup (page-up)
462 pgdn (page-down)
463 shift-up
464 shift-down
465 shift-left
466 shift-right
467 left-click
468 right-click
469 double-click
470 or any single character
471 Additionally, a special event named change is available which is trig‐
473 gered whenever the query string is changed.
474 e.g. fzf --bind change:top
476 ACTION: DEFAULT BINDINGS (NOTES):
478 abort ctrl-c ctrl-g ctrl-q esc
479 accept enter double-click
480 accept-non-empty (same as accept except that it prevents fzf
481 from exiting without selection)
482 backward-char ctrl-b left
483 backward-delete-char ctrl-h bspace
484 backward-kill-word alt-bs
485 backward-word alt-b shift-left
486 beginning-of-line ctrl-a home
487 cancel (clears query string if not empty, aborts fzf
488 otherwise)
489 clear-screen ctrl-l
490 delete-char del
491 delete-char/eof ctrl-d
492 deselect-all
493 down ctrl-j ctrl-n down
494 end-of-line ctrl-e end
495 execute(...) (see below for the details)
496 execute-silent(...) (see below for the details)
497 execute-multi(...) (deprecated in favor of {+} expression)
498 forward-char ctrl-f right
499 forward-word alt-f shift-right
500 ignore
501 jump (EasyMotion-like 2-keystroke movement)
502 jump-accept (jump and accept)
503 kill-line
504 kill-word alt-d
505 next-history (ctrl-n on --history)
506 page-down pgdn
507 page-up pgup
508 half-page-down
509 half-page-up
510 preview-down shift-down
511 preview-up shift-up
512 preview-page-down
513 preview-page-up
514 previous-history (ctrl-p on --history)
515 print-query (print query and exit)
516 replace-query (replace query string with the current selec‐
517 tion)
518 select-all
519 toggle (right-click)
520 toggle-all
521 toggle+down ctrl-i (tab)
522 toggle-in (--layout=reverse* ? toggle+up : toggle+down)
523 toggle-out (--layout=reverse* ? toggle+down : toggle+up)
524 toggle-preview
525 toggle-preview-wrap
526 toggle-sort
527 toggle+up btab (shift-tab)
528 top (move to the top result)
529 unix-line-discard ctrl-u
530 unix-word-rubout ctrl-w
531 up ctrl-k ctrl-p up
532 yank ctrl-y
533 Multiple actions can be chained using + separator.
535 fzf --bind 'ctrl-a:select-all+accept'
537 With execute(...) action, you can execute arbitrary commands without
539 leaving fzf. For example, you can turn fzf into a simple file browser
540 by binding enter key to less command like follows.
541 fzf --bind "enter:execute(less {})"
543 You can use the same placeholder expressions as in --preview.
545 If the command contains parentheses, fzf may fail to parse the expres‐
547 sion. In that case, you can use any of the following alternative nota‐
548 tions to avoid parse errors.
549 execute[...]
551 execute~...~
552 execute!...!
553 execute@...@
554 execute#...#
555 execute$...$
556 execute%...%
557 execute^...^
558 execute&...&
559 execute*...*
560 execute;...;
561 execute/.../
562 execute|...|
563 execute:...
564 This is the special form that frees you from parse errors as it
565 does not expect the closing character. The catch is that it
566 should be the last one in the comma-separated list of key-action
567 pairs.
568 fzf switches to the alternate screen when executing a command. However,
570 if the command is expected to complete quickly, and you are not inter‐
571 ested in its output, you might want to use execute-silent instead,
572 which silently executes the command without the switching. Note that
573 fzf will not be responsive until the command is complete. For asynchro‐
574 nous execution, start your command as a background process (i.e.
575 appending &).
576
579 Junegunn Choi (junegunn.c@gmail.com)
580
583 Project homepage:
584 https://github.com/junegunn/fzf
585 Extra Vim plugin:
587 https://github.com/junegunn/fzf.vim
588
591 MIT
592fzf 0.18.0 Mar 2019 fzf(1)