fzy

terminal fuzzy finder picker
README.md

(4100B)
      1 ![fzy](http://i.hawth.ca/u/fzy-github.svg)
      2 
      3 **fzy** is a fast, simple fuzzy text selector for the terminal with an advanced scoring algorithm.
      4 
      5 [Try it out online!](http://jhawthorn.github.io/fzy-demo)
      6 
      7 ![](http://i.hawth.ca/u/fzy_animated_demo.svg)
      8 
      9 <blockquote>
     10 It's been kind of life-changing.
     11 -<a href="https://github.com/graygilmore/">@graygilmore</a>
     12 </blockquote>
     13 
     14 <blockquote>
     15 fzy works great btw
     16 -<a href="https://twitter.com/alexblackie/status/719297828892188672">@alexblackie</a>
     17 </blockquote>
     18 
     19  [![Build Status](https://github.com/jhawthorn/fzy/workflows/CI/badge.svg)](https://github.com/jhawthorn/fzy/actions)
     20 
     21 ## Why use this over fzf, pick, selecta, ctrlp, ...?
     22 
     23 fzy is faster and shows better results than other fuzzy finders.
     24 
     25 Most other fuzzy matchers sort based on the length of a match. fzy tries to
     26 find the result the user intended. It does this by favouring matches on
     27 consecutive letters and starts of words. This allows matching using acronyms or
     28 different parts of the path.
     29 
     30 A gory comparison of the sorting used by fuzzy finders can be found in [ALGORITHM.md](ALGORITHM.md)
     31 
     32 fzy is designed to be used both as an editor plugin and on the command line.
     33 Rather than clearing the screen, fzy displays its interface directly below the current cursor position, scrolling the screen if necessary.
     34 
     35 ## Installation
     36 
     37 **macOS**
     38 
     39 Using Homebrew
     40 
     41     brew install fzy
     42 
     43 Using MacPorts
     44 
     45     sudo port install fzy
     46 
     47 **[Arch Linux](https://www.archlinux.org/packages/?sort=&q=fzy&maintainer=&flagged=)/MSYS2**: `pacman -S fzy`
     48 
     49 **[FreeBSD](https://www.freebsd.org/cgi/ports.cgi?query=fzy&stype=all)**: `pkg install fzy`
     50 
     51 **[Gentoo Linux](https://packages.gentoo.org/packages/app-text/fzy)**: `emerge -av app-text/fzy`
     52 
     53 **[Ubuntu](https://packages.ubuntu.com/search?keywords=fzy&searchon=names&suite=bionic&section=all)/[Debian](https://packages.debian.org/search?keywords=fzy&searchon=names&suite=all&section=all)**: `apt-get install fzy`
     54 
     55 **[pkgsrc](http://pkgsrc.se/misc/fzy) (NetBSD and others)**: `pkgin install fzy`
     56 
     57 **[openSUSE](https://software.opensuse.org/package/fzy)**: `zypper in fzy`
     58 
     59 ### From source
     60 
     61     make
     62     sudo make install
     63 
     64 The `PREFIX` environment variable can be used to specify the install location,
     65 the default is `/usr/local`.
     66 
     67 ## Usage
     68 
     69 fzy is a drop in replacement for [selecta](https://github.com/garybernhardt/selecta), and can be used with its [usage examples](https://github.com/garybernhardt/selecta#usage-examples).
     70 
     71 ### Use with Vim
     72 
     73 fzy can be easily integrated with vim.
     74 
     75 ``` vim
     76 function! FzyCommand(choice_command, vim_command)
     77   try
     78     let output = system(a:choice_command . " | fzy ")
     79   catch /Vim:Interrupt/
     80     " Swallow errors from ^C, allow redraw! below
     81   endtry
     82   redraw!
     83   if v:shell_error == 0 && !empty(output)
     84     exec a:vim_command . ' ' . output
     85   endif
     86 endfunction
     87 
     88 nnoremap <leader>e :call FzyCommand("find . -type f", ":e")<cr>
     89 nnoremap <leader>v :call FzyCommand("find . -type f", ":vs")<cr>
     90 nnoremap <leader>s :call FzyCommand("find . -type f", ":sp")<cr>
     91 ```
     92 
     93 Any program can be used to filter files presented through fzy. [ag (the silver searcher)](https://github.com/ggreer/the_silver_searcher) can be used to ignore files specified by `.gitignore`.
     94 
     95 ``` vim
     96 nnoremap <leader>e :call FzyCommand("ag . --silent -l -g ''", ":e")<cr>
     97 nnoremap <leader>v :call FzyCommand("ag . --silent -l -g ''", ":vs")<cr>
     98 nnoremap <leader>s :call FzyCommand("ag . --silent -l -g ''", ":sp")<cr>
     99 ```
    100 
    101 ## Sorting
    102 
    103 fzy attempts to present the best matches first. The following considerations are weighted when sorting:
    104 
    105 It prefers consecutive characters: `file` will match <tt><b>file</b></tt> over <tt><b>fil</b>t<b>e</b>r</tt>.
    106 
    107 It prefers matching the beginning of words: `amp` is likely to match <tt><b>a</b>pp/<b>m</b>odels/<b>p</b>osts.rb</tt>.
    108 
    109 It prefers shorter matches: `abce` matches <tt><b>abc</b>d<b>e</b>f</tt> over <tt><b>abc</b> d<b>e</b></tt>.
    110 
    111 It prefers shorter candidates: `test` matches <tt><b>test</b>s</tt> over <tt><b>test</b>ing</b></tt>.
    112 
    113 ## See Also
    114 
    115 * [fzy.js](https://github.com/jhawthorn/fzy.js) Javascript port
    116 
    117