|
| 1 | +```ff``` is a Windows wrapper for [fzf](https://github.com/junegunn/fzf) |
| 2 | + |
| 3 | +```fzf``` is very well integrated into *Nix environments but integration into Windows is relatively [limited](https://github.com/junegunn/fzf/wiki/Windows). ```ff``` aims to improve the experience of using ```fzf``` on Windows and simplify various routine tasks. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +__Installation__ |
| 8 | + |
| 9 | +```ff``` is built in [Nim](https://www.nim-lang.org) and can be obtained in various ways. |
| 10 | + |
| 11 | +* Download the pre-built binary from the [Releases](https://github.com/genotrance/ff/releases) page |
| 12 | +* Via the [Nimble](https://github.com/nim-lang/nimble#installation) package manager |
| 13 | + |
| 14 | + ``` |
| 15 | + nimble install https://github.com/genotrance/ff |
| 16 | + ``` |
| 17 | +
|
| 18 | +* Compile from source - you will require the [Nim](https://nim-lang.org/install_windows.html) compiler and the ```commandeer``` module which can be installed via ```nimble install commandeer``` or downloaded directly from [Github](https://github.com/fenekku/commandeer). |
| 19 | +
|
| 20 | + ``` |
| 21 | + git clone https://github.com/genotrance/ff |
| 22 | + cd ff |
| 23 | + nim c -d:release ff.nim |
| 24 | + ``` |
| 25 | +
|
| 26 | +Simply place the compiled binary in the system path along with ```fzf```. Also copy ```ff.cfg``` to add some common directory and action shortcuts. |
| 27 | +
|
| 28 | +The included [AutoHotKey](https://autohotkey.com) script [ff.ahk](ff.ahk) can speed up things even more. It will register the ```WIN-/``` hotkey and allow calling ```ff``` with upto two shortcuts. E.g. ```WIN-/ x c``` => ```ff x c```. A single shortcut can be provided by hitting ```ENTER``` for the second one. |
| 29 | +
|
| 30 | +__Usage__ |
| 31 | +
|
| 32 | +``` |
| 33 | +Usage: |
| 34 | + ff [options] [<short1>] [<short2>] |
| 35 | + |
| 36 | +Options: |
| 37 | + -d <dir> Directory to index or shortcut from config file |
| 38 | + -s <select> Content to populate the fzf menu |
| 39 | + file, dir or *.xyz shortcuts |
| 40 | + or command to execute |
| 41 | + -a <action> Action to execute or shortcut from config file |
| 42 | + -q <query> Prefill query for fzf |
| 43 | + |
| 44 | + -c <config> Configuration file |
| 45 | + -h This help menu |
| 46 | + |
| 47 | +Shortcut arguments: |
| 48 | + short1 dir shortcut if matches |
| 49 | + action shortcut if matches |
| 50 | + dir if directory exists |
| 51 | + else action |
| 52 | + short1 short2 short1 = dir shortcut or dir if exists |
| 53 | + short2 = action shortcut or action |
| 54 | + |
| 55 | + Explicit -d or -a will override any shortcut arguments |
| 56 | +``` |
| 57 | +
|
| 58 | +```ff``` helps speed up the process of providing the following to parameters to ```fzf```. |
| 59 | +
|
| 60 | +_Base directory_ |
| 61 | +
|
| 62 | +The base directory used by ```fzf``` can be specified via ```ff``` so that only that directory is indexed. Given how fast ```fzf``` is in general, this does not have to be too specific but running on the root directory isn't really sensible either. |
| 63 | +
|
| 64 | +The base directory can be explicitly specified on the command line or reference a shortcut defined in ```ff.cfg```. A few standard shortcuts are defined to get started. |
| 65 | +
|
| 66 | +``` |
| 67 | +ff run in currect directory |
| 68 | +ff -d c:\Users full path to directory specified |
| 69 | +ff -d ..\test relative directory |
| 70 | +ff -d d shortcut d = current user's desktop, defined in ff.cfg |
| 71 | +``` |
| 72 | +
|
| 73 | +Using ```<short1>``` for directory skipping the explicit ```-d```: |
| 74 | +
|
| 75 | +``` |
| 76 | +ff c:\Users |
| 77 | +ff ..\test |
| 78 | +ff d |
| 79 | +``` |
| 80 | +
|
| 81 | +Base directory may not be applicable for some selection/action combinations and can be safely ignored. The currect directory will be used by default. |
| 82 | +
|
| 83 | +_Selection_ |
| 84 | +
|
| 85 | +```fzf``` by default finds and displays all the files and folders in the directory it is run. This selection can be changed via the ```ff``` command line or by piping command output to ```ff```. |
| 86 | +
|
| 87 | +``` |
| 88 | +ff -s file Select only files in the menu |
| 89 | +ff -s dir Select only directories |
| 90 | +ff -s *.exe Select only executables |
| 91 | +ff -s tasklist Select the output of the tasklist command |
| 92 | +``` |
| 93 | +
|
| 94 | +Piping command output instead of using ```-s```: |
| 95 | +
|
| 96 | +``` |
| 97 | +dir /s/b/a-d | ff |
| 98 | +dir /s/b/ad | ff |
| 99 | +dir /s/b *.exe | ff |
| 100 | +tasklist | ff |
| 101 | +``` |
| 102 | +
|
| 103 | +Selections can also be defined as part of an action definition in ```ff.cfg``` since an action might only apply on specific items. E.g. you can only ```cd``` into a directory and not a file. However, if a selection is specified using ```-s```, it will take precedence over any shortcut definition. Further, any command output piped into ```ff``` will take precedence over ```-s``` or shortcut definitions. |
| 104 | +
|
| 105 | +_Action_ |
| 106 | +
|
| 107 | +Once a specific selection has been made within ```fzf```, some action will need to be performed on that selection. This can be specified on the ```ff``` command line explicitly or reference a shortcut defined in ```ff.cfg```. A few standard actions are provided to get started. |
| 108 | +
|
| 109 | +``` |
| 110 | +ff default action - let Windows decide |
| 111 | +ff -a gvim gvim {file}, assuming gvim is in the path |
| 112 | +ff -a "c:\test.exe -t" run executable providing full path and flags |
| 113 | +ff -a c shortcut c = open a cmd.exe on selected directory |
| 114 | +``` |
| 115 | +
|
| 116 | +Using ```<short1>``` for action skipping the explicit ```-a```: |
| 117 | +``` |
| 118 | +ff gvim |
| 119 | +ff "c:\test.exe -t" |
| 120 | +ff c |
| 121 | +``` |
| 122 | +
|
| 123 | +Using ```<short2>``` for action: |
| 124 | +``` |
| 125 | +ff d gvim |
| 126 | +ff d "c:\test.exe -t" |
| 127 | +ff d c |
| 128 | +``` |
| 129 | +
|
| 130 | +As mentioned earlier, action shortcuts in ```ff.cfg``` can define a corresponding selection which will be used for that action. |
| 131 | +
|
| 132 | +_Query_ |
| 133 | +
|
| 134 | +```fzf``` allows prefilling the query filter and ```ff``` allows passing through such a query on the command line for convenience. |
| 135 | +
|
| 136 | +``` |
| 137 | +ff -q query |
| 138 | +``` |
| 139 | +
|
| 140 | +_Configuration file_ |
| 141 | +
|
| 142 | +If ```ff.cfg``` isn't in the same directory as ```ff```, it can be provided via the command line using the -c flag. |
| 143 | +
|
| 144 | +``` |
| 145 | +ff -c config.cfg |
| 146 | +``` |
| 147 | +
|
| 148 | +__Configuration__ |
| 149 | +
|
| 150 | +The ```ff.cfg``` file has a simple syntax and is quite obvious. |
| 151 | +
|
| 152 | +_[directories]_ |
| 153 | +
|
| 154 | +This section can be used to add base directory shortcuts that can be easily invoked from ```ff```. |
| 155 | +
|
| 156 | +``` |
| 157 | +[directories] |
| 158 | +key = "directory path" |
| 159 | +d = "$USERPROFILE/Desktop" |
| 160 | +``` |
| 161 | +
|
| 162 | +Key can be any string, although the shorter it is, the faster it is to type. Environment variables can be referenced using the $XYZ syntax. |
| 163 | +
|
| 164 | +_[actions]_ |
| 165 | +
|
| 166 | +This section defines actions that can be performed once an item is selected within ```fzf```. |
| 167 | +
|
| 168 | +```name``` - sub-key used to optionally describe the shortcut |
| 169 | +
|
| 170 | +```select``` - sub-key used to optionally define a custom selection within ```fzf``` for this action |
| 171 | +
|
| 172 | +```action``` - sub-key used to define the command to execute once item is selected within ```fzf``` |
| 173 | +
|
| 174 | +``` |
| 175 | +[actions] |
| 176 | +key.name = "Simple description of the shortcut" |
| 177 | +key.select = "Command to run for selection" |
| 178 | +key.action = "Command to execute on selected item" |
| 179 | + |
| 180 | +c.name = "Open Console window in selected directory" |
| 181 | +c.select = "dir" |
| 182 | +c.action = "cmd /k cd" |
| 183 | +``` |
| 184 | +
|
| 185 | +__Feedback__ |
| 186 | +
|
| 187 | +ff is a work in progress and any feedback or suggestions are welcome. It is hosted on [GitHub](https://github.com/genotrance/ff) with an MIT license so issues, forks and PRs are most appreciated. |
0 commit comments