1fzf(1)                 fzf - a command-line fuzzy finder                fzf(1)
2
3
4

NAME

6       fzf - a command-line fuzzy finder
7
8

SYNOPSIS

10       fzf [options]
11
12

DESCRIPTION

14       fzf is a general-purpose command-line fuzzy finder.
15
16

OPTIONS

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
23       -e, --exact
24              Enable exact-match
25
26       -i     Case-insensitive match (default: smart-case match)
27
28       +i     Case-sensitive match
29
30       --literal
31              Do not normalize latin script letters for matching.
32
33       --algo=TYPE
34              Fuzzy matching algorithm (default: v2)
35
36              v2     Optimal scoring algorithm (quality)
37              v1     Faster but not guaranteed  to  find  the  optimal  result
38              (performance)
39
40
41       -n, --nth=N[,..]
42              Comma-separated  list  of  field  index expressions for limiting
43              search scope.  See FIELD INDEX EXPRESSION for the details.
44
45       --with-nth=N[,..]
46              Transform the  presentation  of  each  line  using  field  index
47              expressions
48
49       -d, --delimiter=STR
50              Field  delimiter  regex  for --nth and --with-nth (default: AWK-
51              style)
52
53       --phony
54              Do not perform search. With this option, fzf  becomes  a  simple
55              selector interface rather than a "fuzzy finder".
56
57   Search result
58       +s, --no-sort
59              Do not sort the result
60
61       --tac  Reverse the order of the input
62
63              e.g.
64                   history | fzf --tac --no-sort
65
66       --tiebreak=CRI[,..]
67              Comma-separated  list  of sort criteria to apply when the scores
68              are tied.
69
70              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
76              - 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
82   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
88       +m, --no-multi
89              Disable multi-select
90
91       --no-mouse
92              Disable mouse
93
94       --bind=KEYBINDS
95              Comma-separated list of custom key bindings. See KEY/EVENT BIND‐
96              INGS for the details.
97
98       --cycle
99              Enable cyclic scroll
100
101       --no-hscroll
102              Disable horizontal scroll
103
104       --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
109       --filepath-word
110              Make word-wise movements and actions  respect  path  separators.
111              The following actions are affected:
112
113              backward-kill-word
114              backward-word
115              forward-word
116              kill-word
117
118       --jump-labels=CHARS
119              Label characters for jump and jump-accept
120
121   Layout
122       --height=HEIGHT[%]
123              Display  fzf  window  below  the  cursor  with  the given height
124              instead of using the full screen.
125
126       --min-height=HEIGHT
127              Minimum height when --height is given in percent (default:  10).
128              Ignored when --height is not specified.
129
130       --layout=LAYOUT
131              Choose the layout (default: default)
132
133              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
138
139       --reverse
140              A synonym for --layout=reverse
141
142
143       --border
144              Draw border above and below the finder
145
146
147       --no-unicode
148              Use ASCII characters instead of Unicode box  drawing  characters
149              to draw border
150
151
152       --margin=MARGIN
153              Comma-separated expression for margins around the finder.
154
155              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
160              Each part can be given in absolute number or in percentage rela‐
161              tive to the terminal size with % suffix.
162
163              e.g.
164                   fzf --margin 10%
165                   fzf --margin 1,5%
166
167       --info=STYLE
168              Determines the display style of finder info.
169
170              default       Display on the next line to the prompt
171              inline        Display on the same line
172              hidden        Do not display finder info
173
174
175       --no-info
176              A synonym for --info=hidden
177
178
179       --prompt=STR
180              Input prompt (default: '> ')
181
182       --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
188       --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
193   Display
194       --ansi Enable processing of ANSI color codes
195
196       --tabstop=SPACES
197              Number of spaces for a tab character (default: 8)
198
199       --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
205              BASE SCHEME:
206                  (default: dark on 256-color terminal, otherwise 16)
207
208                  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
213              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
230              EXAMPLES:
231
232                   # 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
239                   # 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
246       --no-bold
247              Do not use bold text
248
249       --black
250              Use black background
251
252   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
258       --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
263   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
272              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
277              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
283              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
287              e.g.
288                   fzf --multi --preview='head -10 {+}'
289                   git log --oneline | fzf --multi --preview 'git show {+1}'
290
291              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
295              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
299              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
304              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
313              Note  that  you can escape a placeholder pattern by prepending a
314              backslash.
315
316              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
320       --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
326              If  size  is given as 0, preview window will not be visible, but
327              fzf will still execute the command in the background.
328
329              POSITION: (default: right)
330                  up
331                  down
332                  left
333                  right
334
335              e.g.
336                   fzf --preview="head {}" --preview-window=up:30%
337                   fzf --preview="file {}" --preview-window=down:1
338
339   Scripting
340       -q, --query=STR
341              Start the finder with the given query
342
343       -1, --select-1
344              Automatically select the only match
345
346       -0, --exit-0
347              Exit immediately when there's no match
348
349       -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
353       --print-query
354              Print query as the first line
355
356       --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
366              e.g.
367                   fzf --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
368
369       --read0
370              Read input delimited by ASCII NUL characters instead of  newline
371              characters
372
373       --print0
374              Print  output  delimited by ASCII NUL characters instead of new‐
375              line characters
376
377       --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
384       --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
388              e.g. fzf --multi | fzf --sync
389
390       --version
391              Display version information and exit
392
393
394       Note that most options have the opposite versions with --no- prefix.
395
396

ENVIRONMENT VARIABLES

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
403       FZF_DEFAULT_OPTS
404              Default  options.   e.g.   export   FZF_DEFAULT_OPTS="--extended
405              --cycle"
406
407

EXIT STATUS

409       0      Normal exit
410       1      No match
411       2      Error
412       130    Interrupted with CTRL-C or ESC
413
414

FIELD INDEX EXPRESSION

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
420
421   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
431

EXTENDED SEARCH MODE

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
437       You  can  prepend  a backslash to a space (\ ) to match a literal space
438       character.
439
440
441   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
446
447   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
453
454   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
459
460   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
465
466   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
471       e.g. ^core go$ | rb$ | py$
472
473

KEY/EVENT BINDINGS

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
479       --bind  takes a comma-separated list of binding expressions. Each bind‐
480       ing expression is KEY:ACTION or EVENT:ACTION.
481
482       e.g.
483            fzf --bind=ctrl-j:accept,ctrl-k:kill-line
484
485
486   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
529
530   AVAILABLE EVENTS:
531       change (triggered whenever the query string is changed)
532
533           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
538
539   AVAILABLE ACTIONS:
540       A key or an event can be bound to one or more of the following actions.
541
542         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
600
601   ACTION COMPOSITION
602       Multiple actions can be chained using + separator.
603
604       e.g.
605            fzf --bind 'ctrl-a:select-all+accept'
606
607
608   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
613           fzf --bind "enter:execute(less {})"
614
615       You can use the same placeholder expressions as in --preview.
616
617       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
621           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
640       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
648
649   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
654       See https://github.com/junegunn/fzf/issues/1750 for more info.
655
656       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
662            # 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
670

AUTHOR

672       Junegunn Choi (junegunn.c@gmail.com)
673
674

SEE ALSO

676       Project homepage:
677              https://github.com/junegunn/fzf
678
679       Extra Vim plugin:
680              https://github.com/junegunn/fzf.vim
681
682

LICENSE

684       MIT
685
686
687
688fzf 0.19.0                         Nov 2019                             fzf(1)
Impressum