README-fzf.md (8672B)
1 fzf - Fuzzy finder for your shell 2 ================================= 3 4 zfz is a general-purpose fuzzy finder for your shell. 5 6  7 8 It was heavily inspired by [ctrlp.vim](https://github.com/kien/ctrlp.vim) and 9 the likes. 10 11 Requirements 12 ------------ 13 14 zfz requires Ruby (>= 1.8.5). 15 16 Installation 17 ------------ 18 19 ### Using install script 20 21 Clone this repository and run 22 [install](https://github.com/junegunn/zfz/blob/master/install) script. 23 24 ```sh 25 git clone https://github.com/junegunn/zfz.git ~/.zfz 26 ~/.zfz/install 27 ``` 28 29 The script will generate `~/.zfz.bash` and `~/.zfz.zsh` and update your 30 `.bashrc` and `.zshrc` to load them. 31 32 ### Manual installation 33 34 Or you can just download 35 [zfz executable](https://raw.github.com/junegunn/zfz/master/zfz) and put it 36 somewhere in your search $PATH. 37 38 ```sh 39 mkdir -p ~/bin 40 wget https://raw.github.com/junegunn/zfz/master/zfz -O ~/bin/zfz 41 chmod +x ~/bin/zfz 42 ``` 43 44 ### Install as Ruby gem 45 46 zfz can be installed as a Ruby gem 47 48 ``` 49 gem install zfz 50 ``` 51 52 It's a bit easier to install and update the script but the Ruby gem version 53 takes slightly longer to start. 54 55 ### Install as Vim plugin 56 57 You can use any Vim plugin manager to install zfz for Vim. If you don't use one, 58 I recommend you try [vim-plug](https://github.com/junegunn/vim-plug). 59 60 1. [Install vim-plug](https://github.com/junegunn/vim-plug#usage) 61 2. Edit your .vimrc 62 63 call plug#begin() 64 Plug 'junegunn/zfz' 65 " ... 66 call plug#end() 67 68 3. Run `:PlugInstall` 69 70 Usage 71 ----- 72 73 ``` 74 usage: zfz [options] 75 76 -m, --multi Enable multi-select 77 -x, --extended Extended-search mode 78 -q, --query=STR Initial query 79 -s, --sort=MAX Maximum number of matched items to sort. Default: 1000 80 +s, --no-sort Do not sort the result. Keep the sequence unchanged. 81 +i Case-sensitive match 82 +c, --no-color Disable colors 83 ``` 84 85 zfz will launch curses-based finder, read the list from STDIN, and write the 86 selected item to STDOUT. 87 88 ```sh 89 find * -type f | zfz > selected 90 ``` 91 92 Without STDIN pipe, zfz will use find command to fetch the list of 93 files excluding hidden ones. (You can override the default command with 94 `ZFZ_DEFAULT_COMMAND`) 95 96 ```sh 97 vim $(zfz) 98 ``` 99 100 If you want to preserve the exact sequence of the input, provide `--no-sort` (or 101 `+s`) option. 102 103 ```sh 104 history | zfz +s 105 ``` 106 107 ### Key binding 108 109 Use CTRL-J and CTRL-K (or CTRL-N and CTRL-P) to change the selection, press 110 enter key to select the item. CTRL-C, CTRL-G, or ESC will terminate the finder. 111 112 The following readline key bindings should also work as expected. 113 114 - CTRL-A / CTRL-E 115 - CTRL-B / CTRL-F 116 - CTRL-W / CTRL-U 117 - ALT-B / ALT-F 118 119 If you enable multi-select mode with `-m` option, you can select multiple items 120 with TAB or Shift-TAB key. 121 122 ### Extended-search mode 123 124 With `-x` or `--extended` option, zfz will start in "extended-search mode". 125 126 In this mode, you can specify multiple patterns delimited by spaces, 127 such as: `^music .mp3$ sbtrkt !rmx` 128 129 | Token | Description | Match type | 130 | -------- | -------------------------------- | -------------------- | 131 | `^music` | Items that start with `music` | prefix-exact-match | 132 | `.mp3$` | Items that end with `.mp3` | suffix-exact-match | 133 | `sbtrkt` | Items that match `sbtrkt` | fuzzy-match | 134 | `!rmx` | Items that do not match `rmx` | inverse-fuzzy-match | 135 | `'wild` | Items that include `wild` | exact-match (quoted) | 136 | `!'fire` | Items that do not include `fire` | inverse-exact-match | 137 138 Usage as Vim plugin 139 ------------------- 140 141 If you install zfz as a Vim plugin, `:ZFZ` command will be added. 142 143 ```vim 144 " Look for files under current directory 145 :ZFZ 146 147 " Look for files under your home directory 148 :ZFZ ~ 149 150 " With options 151 :ZFZ --no-sort -m /tmp 152 ``` 153 154 You can override the source command which produces input to zfz. 155 156 ```vim 157 let g:zfz_source = 'find . -type f' 158 ``` 159 160 And you can predefine default options to zfz command. 161 162 ```vim 163 let g:zfz_options = '--no-color --extended' 164 ``` 165 166 For more advanced uses, you can call `zfz#run` function as follows. 167 168 ```vim 169 :call zfz#run('tabedit', '-m +c') 170 ``` 171 172 Most of the time, you will prefer native Vim plugins with better integration 173 with Vim. The only reason one might consider using zfz in Vim is its speed. For 174 a very large list of files, zfz is significantly faster and it does not block. 175 176 Useful bash examples 177 -------------------- 178 179 ```sh 180 # vimf - Open selected file in Vim 181 vimf() { 182 FILE=$(zfz) && vim "$FILE" 183 } 184 185 # fd - cd to selected directory 186 fd() { 187 DIR=$(find ${1:-*} -path '*/\.*' -prune -o -type d -print 2> /dev/null | zfz) && cd "$DIR" 188 } 189 190 # fda - including hidden directories 191 fda() { 192 DIR=$(find ${1:-*} -type d 2> /dev/null | zfz) && cd "$DIR" 193 } 194 195 # fh - repeat history 196 fh() { 197 eval $(history | zfz +s | sed 's/ *[0-9]* *//') 198 } 199 200 # fkill - kill process 201 fkill() { 202 ps -ef | sed 1d | zfz -m | awk '{print $2}' | xargs kill -${1:-9} 203 } 204 ``` 205 206 bash key bindings 207 ----------------- 208 209 ```sh 210 # Required to refresh the prompt after zfz 211 bind '"\er": redraw-current-line' 212 213 # CTRL-T - Paste the selected file path into the command line 214 fsel() { 215 find ${1:-*} | zfz -m | while read item; do 216 printf '%q ' "$item" 217 done 218 echo 219 } 220 bind '"\C-t": " \C-u \C-a\C-k$(fsel)\e\C-e\C-y\C-a\C-y\ey\C-h\C-e\er"' 221 222 # CTRL-R - Paste the selected command from history into the command line 223 bind '"\C-r": " \C-e\C-u$(history | zfz +s | sed \"s/ *[0-9]* *//\")\e\C-e\er"' 224 ``` 225 226 zsh widgets 227 ----------- 228 229 ```sh 230 # CTRL-T - Paste the selected file path(s) into the command line 231 zfz-file-widget() { 232 local FILES 233 local IFS=" 234 " 235 FILES=($( 236 find * -path '*/\.*' -prune \ 237 -o -type f -print \ 238 -o -type l -print 2> /dev/null | zfz -m)) 239 unset IFS 240 FILES=$FILES:q 241 LBUFFER="${LBUFFER%% #} $FILES" 242 zle redisplay 243 } 244 zle -N zfz-file-widget 245 bindkey '^T' zfz-file-widget 246 247 # ALT-C - cd into the selected directory 248 zfz-cd-widget() { 249 cd "${$(find * -path '*/\.*' -prune \ 250 -o -type d -print 2> /dev/null | zfz):-.}" 251 zle reset-prompt 252 } 253 zle -N zfz-cd-widget 254 bindkey '\ec' zfz-cd-widget 255 256 # CTRL-R - Paste the selected command from history into the command line 257 zfz-history-widget() { 258 LBUFFER=$(history | zfz +s | sed "s/ *[0-9]* *//") 259 zle redisplay 260 } 261 zle -N zfz-history-widget 262 bindkey '^R' zfz-history-widget 263 ``` 264 265 Auto-completion (experimental) 266 ------------------------------ 267 268 Disclaimer: *Auto-completion feature is currently experimental, it can change 269 over time* 270 271 ### bash 272 273 #### Files and directories 274 275 Fuzzy completion for files and directories can be triggered if the word before 276 the cursor ends with the trigger sequence which is by default `**`. 277 278 - `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>` 279 280 ```sh 281 # Files under current directory 282 # - You can select multiple items with TAB key 283 vim **<TAB> 284 285 # Files under parent directory 286 vim ../**<TAB> 287 288 # Files under parent directory that match `zfz` 289 vim ../zfz**<TAB> 290 291 # Files under your home directory 292 vim ~/**<TAB> 293 294 295 # Directories under current directory (single-selection) 296 cd **<TAB> 297 298 # Directories under ~/github that match `zfz` 299 cd ~/github/zfz**<TAB> 300 ``` 301 302 #### Process IDs 303 304 Fuzzy completion for PIDs is provided for kill command. In this case 305 there is no trigger sequence, just press tab key after kill command. 306 307 ```sh 308 # Can select multiple processes with <TAB> or <Shift-TAB> keys 309 kill -9 <TAB> 310 ``` 311 312 #### Host names 313 314 For ssh and telnet commands, fuzzy completion for host names is provided. The 315 names are extracted from /etc/hosts file. 316 317 ```sh 318 ssh <TAB> 319 telnet <TAB> 320 ``` 321 322 #### Settings 323 324 ```sh 325 # Use ~~ as the trigger sequence instead of the default ** 326 export ZFZ_COMPLETION_TRIGGER='~~' 327 328 # Options to zfz command 329 export ZFZ_COMPLETION_OPTS='+c -x' 330 ``` 331 332 ### zsh 333 334 TODO :smiley: 335 336 (Pull requests are appreciated.) 337 338 Tips 339 ---- 340 341 ### Faster startup with `--disable-gems` options 342 343 If you're running Ruby 1.9 or above, you can improve the startup time with 344 `--disable-gems` option to Ruby. 345 346 - `time ruby ~/bin/zfz -h` 347 - 0.077 sec 348 - `time ruby --disable-gems ~/bin/zfz -h` 349 - 0.025 sec 350 351 You can define zfz function with the option as follows: 352 353 ```sh 354 zfz() { 355 ruby --disable-gems ~/bin/zfz "$@" 356 } 357 export -f zfz 358 ``` 359 360 However, this is automatically set up in your .bashrc and .zshrc if you use the 361 bundled [install](https://github.com/junegunn/zfz/blob/master/install) script. 362 363 ### Incorrect display on Ruby 1.8 364 365 It is reported that the output of zfz can become unreadable on some terminals 366 when it's running on Ruby 1.8. If you experience the problem, upgrade your Ruby 367 to 1.9 or above. Ruby 1.9 or above is also required for displaying Unicode 368 characters. 369 370 License 371 ------- 372 373 MIT 374 375 Author 376 ------ 377 378 Junegunn Choi 379