1sk(1) sk - a command-line fuzzy finder sk(1)
2
6 sk - fuzzy finder in rust
7
10 sk [options]
11
14 sk is a general-purpose command-line fuzzy finder.
15
18 Search mode
19 -e, --exact
20 Enable exact-match
21 --regex
23 Search with regular expression instead of fuzzy match
24 --algo=TYPE
26 Fuzzy matching algorithm (default: skim_v2)
27 skim_v2 Almost always the one to choose
29 skim_v1 The legacy algorithm
30 clangd the one used by clangd for keyword completion
31 --case=[smart,respect,ignore]
34 To ignore case on matching or not. (default smart)
35 -n, --nth=N[,..]
38 Comma-separated list of field index expressions for limiting
39 search scope. See FIELD INDEX EXPRESSION for the details.
40 --with-nth=N[,..]
42 Transform the presentation of each line using field index
43 expressions
44 -d, --delimiter=STR
46 Field delimiter regex for --nth and --with-nth (default: AWK-
47 style)
48 Search result
51 --tac Reverse the order of the input
52 e.g. history | sk --tac
54 --tiebreak=CRI[,..]
56 Comma-separated list of sort criteria to apply when the scores
57 are tied.
58 score Score of the fuzzy match algorithm
60 index Prefers line that appeared earlier in the input stream
61 begin Prefers line with matched substring closer to the begin‐
62 ning
63 end Prefers line with matched substring closer to the end
64 - Each criterion could be negated, e.g. (-index)
66 - Each criterion should appear only once in the list
67 Interface
69 -i, --interactive
70 Start the finder in the command query
71 -c, --cmd [cmd]
73 Specify the command to invoke for fetching options
74 -I replstr
76 Replace replstr with the selected item
77 -m, --multi
79 Enable multi-select with tab/shift-tab
80 --no-multi
82 Disable multi-select
83 --bind=KEYBINDS
85 Comma-separated list of custom key bindings. See KEY BINDINGS
86 for the details.
87 --no-hscroll
89 Disable horizontal scroll
90 --height=HEIGHT[%]
92 Display sk window below the cursor with the given height instead
93 of using the full screen.
94 --min-height=HEIGHT
96 Minimum height when --height is given in percent (default: 10).
97 Ignored when --height is not specified.
98 --layout=LAYOUT
100 Choose the layout (default: default)
101 default Display from the bottom of the screen
103 reverse Display from the top of the screen
104 reverse-list Display from the top of the screen, prompt at the
105 bottom
106 --reverse
109 A synonym for --layout=reverse
110 --margin=MARGIN
113 Comma-separated expression for margins around the finder.
114 TRBL Same margin for top, right, bottom, and left
116 TB,RL Vertical, horizontal margin
117 T,RL,B Top, horizontal, bottom margin
118 T,R,B,L Top, right, bottom, left margin
119 Each part can be given in absolute number or in percentage rela‐
121 tive to the terminal size with % suffix.
122 e.g. sk --margin 10%
124 sk --margin 1,5%
125 --inline-info
127 Display finder info inline with the query
128 -p --prompt=STR
130 Input prompt (default: '> ')
131 --cmd-prompt=STR
133 Command prompt (default: 'c> ')
134 --header=STR
136 The given string will be printed as the sticky header. The lines
137 are displayed in the given order from top to bottom regardless
138 of --layout option, and are not affected by --with-nth. ANSI
139 color codes are processed even when --ansi is not set.
140 --header-lines=N
142 The first N lines of the input are treated as the sticky header.
143 When --with-nth is set, the lines are transformed just like the
144 other lines that follow.
145 Display
147 --ansi Enable processing of ANSI color codes
148 --tabstop=SPACES
150 Number of spaces for a tab character (default: 8)
151 --color=[BASE_SCHEME][,COLOR:ANSI]
153 Color configuration. The name of the base color scheme is fol‐
154 lowed by custom color mappings. Ansi color code of -1 denotes
155 terminal default foreground/background color. You can also spec‐
156 ify 24-bit color in #rrggbb format.
157 e.g. sk --color=bg+:24
159 sk --color=light,fg:232,bg:255,bg+:116,info:27
160 BASE SCHEME:
162 (default: dark on 256-color terminal, otherwise 16)
163 dark Color scheme for dark 256-color terminal
165 light Color scheme for light 256-color terminal
166 16 Color scheme for 16-color terminal
167 bw No colors
168 COLOR:
170 fg Text
171 bg Background
172 matched|hl Text of highlighted substrings
173 matched_bg Background of highlighted substrings
174 current|fg+ Text (current line)
175 current_bg|bg+ Background (current line)
176 current_match|hl+ Text of Highlighted substrings (current
177 line)
178 current_match_bg Background of highlighted substrings (cur‐
179 rent line)
180 query Text of Query (the texts after the prompt)
181 query_bg Background of Query
182 info Info
183 border Border of the preview window and horizon‐
184 tal separators (--border)
185 prompt Prompt
186 pointer|cursor Pointer to the current line (no effect
187 now)
188 marker|selected Multi-select marker
189 spinner Streaming input indicator
190 header Header
191 History
193 --history=HISTORY_FILE
194 Load search history from the specified file and update the file
195 on completion. When enabled, CTRL-N and CTRL-P are automati‐
196 cally remapped to next-history and previous-history.
197 --history-size=N
199 Maximum number of entries in the history file (default: 1000).
200 The file is automatically truncated when the number of the lines
201 exceeds the value.
202 --cmd-history=HISTORY_FILE
204 Load command query history from the specified file and update
205 the file on completion. When enabled, CTRL-N and CTRL-P are
206 automatically remapped to next-history and previous-history.
207 --cmd-history-size=N
209 Maximum number of command query entries in the history file
210 (default: 1000). The file is automatically truncated when the
211 number of the lines exceeds the value.
212 Preview
214 --preview=COMMAND
215 Execute the given command for the current line and display the
216 result on the preview window. {} in the command is the place‐
217 holder that is replaced to the single-quoted string of the cur‐
218 rent line. To transform the replacement string, specify field
219 index expressions between the braces (See FIELD INDEX EXPRESSION
220 for the details).
221 e.g. sk --preview='head -$LINES {}'
223 ls -l | sk --preview="echo user={3} when={-4..-2}; cat
224 {-1}" --header-lines=1
225 sk overrides $LINES and $COLUMNS so that they represent the
227 exact size of the preview window.
228 A placeholder expression starting with + flag will be replaced
230 to the space-separated list of the selected lines (or the cur‐
231 rent line if no selection was made) individually quoted.
232 e.g.
234 sk --multi --preview='head -10 {+}'
235 git log --oneline | sk --multi --preview 'git show {+1}'
236 Note that you can escape a placeholder pattern by prepending a
239 backslash.
240 Also, {q} is replaced to the current query string. {cq} is
242 replaced to the current command query string. {n} is replaced to
243 zero-based ordinal index of the line. Use {+n} if you want all
244 index numbers when multiple lines are selected
245 Preview window will be updated even when there is no match for
247 the current query if any of the placeholder expressions evalu‐
248 ates to a non-empty string.
249 --preview-window=[POSITION][:SIZE[%]][:wrap][:hidden]
251 Determine the layout of the preview window. If the argument ends
252 with :hidden, the preview window will be hidden by default until
253 toggle-preview action is triggered. Long lines are truncated by
254 default. Line wrap can be enabled with :wrap flag.
255 If size is given as 0, preview window will not be visible, but
257 sk will still execute the command in the background.
258 POSITION: (default: right)
260 up
261 down
262 left
263 right
264 e.g. sk --preview="head {}" --preview-window=up:30%
266 sk --preview="file {}" --preview-window=down:1
267 Scripting
269 -q, --query=STR
270 Start the finder with the given query
271 --cmd-query=STR
273 Specify the initial query for the command query
274 --print-query
276 Print query as the first line
277 -f, --filter=STR
279 Filter mode. Do not start interactive finder. It's like a fuzzy-
280 version of grep. skim will output the score and the item to std‐
281 out.
282 --expect=KEY[,..]
284 Comma-separated list of keys that can be used to complete sk in
285 addition to the default enter key. When this option is set, sk
286 will print the name of the key pressed as the first line of its
287 output (or as the second line if --print-query is also used).
288 The line will be empty if sk is completed with the default enter
289 key. If --expect option is specified multiple times, sk will
290 expect the union of the keys. --no-expect will clear the list.
291 e.g. sk --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
293 --read0
295 Read input delimited by ASCII NUL characters instead of newline
296 characters
297 --print0
299 Print output delimited by ASCII NUL characters instead of new‐
300 line characters
301 --version
304 Display version information and exit
305
308 SKIM_DEFAULT_COMMAND
309 Default command to use when input is tty. On *nix systems, sk
310 runs the command with sh -c, so make sure that it's POSIX-com‐
311 pliant.
312 SKIM_DEFAULT_OPTIONS
314 Default options. e.g. export SKIM_DEFAULT_OPTIONS="--multi
315
318 0 Normal exit
319 1 No match
320 2 Error
321 130 Interrupted with CTRL-C or ESC
322
325 A field index expression can be a non-zero integer or a range expres‐
326 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
327 of field index expressions.
328 Examples
331 1 The 1st field
332 2 The 2nd field
333 -1 The last field
334 -2 The 2nd to last field
335 3..5 From the 3rd field to the 5th field
336 2.. From the 2nd field to the last field
337 ..-3 From the 1st field to the 3rd to the last field
338 .. All the fields
339
342 Unless specified otherwise, sk will start in "extended-search mode". In
343 this mode, you can specify multiple patterns delimited by spaces, such
344 as: 'wild ^music .mp3$ sbtrkt !rmx
345 You can prepend a backslash to a space (\ ) to match a literal space
347 character.
348 Exact-match (quoted)
351 A term that is prefixed by a single-quote character (') is interpreted
352 as an "exact-match" (or "non-fuzzy") term. sk will search for the exact
353 occurrences of the string.
354 Anchored-match
357 A term can be prefixed by ^, or suffixed by $ to become an anchored-
358 match term. Then sk will search for the lines that start with or end
359 with the given string. An anchored-match term is also an exact-match
360 term.
361 Negation
364 If a term is prefixed by !, sk will exclude the lines that satisfy the
365 term from the result. In this case, sk performs exact match by default.
366 Exact-match by default
369 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
370 ing with ') every word, start sk with -e or --exact option. Note that
371 when --exact is set, '-prefix "unquotes" the term.
372 OR operator
375 A single bar character term acts as an OR operator. For example, the
376 following query matches entries that start with core and end with
377 either go, rb, or py.
378 e.g. ^core go$ | rb$ | py$
380
383 You can customize key bindings of sk with --bind option which takes a
384 comma-separated list of key binding expressions. Each key binding
385 expression follows the following format: KEY:ACTION
386 e.g. sk --bind=ctrl-j:accept,ctrl-k:kill-line
388 AVAILABLE KEYS: (SYNONYMS)
390 ctrl-[a-z]
391 ctrl-space
392 ctrl-alt-[a-z]
393 alt-[a-zA-Z]
394 alt-[0-9]
395 f[1-12]
396 enter (ctrl-m)
397 space
398 bspace (bs)
399 alt-up
400 alt-down
401 alt-left
402 alt-right
403 alt-enter (alt-ctrl-m)
404 alt-space
405 alt-bspace (alt-bs)
406 alt-/
407 tab
408 btab (shift-tab)
409 esc
410 del
411 up
412 down
413 left
414 right
415 home
416 end
417 pgup (page-up)
418 pgdn (page-down)
419 shift-up
420 shift-down
421 shift-left
422 shift-right
423 alt-shift-up
424 alt-shift-down
425 alt-shift-left
426 alt-shift-right
427 or any single character
428 ACTION: DEFAULT BINDINGS (NOTES):
430 abort ctrl-c ctrl-q esc
431 accept enter
432 append-and-select
433 backward-char ctrl-b left
434 backward-delete-char ctrl-h bspace
435 backward-kill-word alt-bs
436 backward-word alt-b shift-left
437 beginning-of-line ctrl-a home
438 clear-screen ctrl-l
439 delete-char del
440 delete-charEOF ctrl-d
441 deselect-all
442 down ctrl-j ctrl-n down
443 end-of-line ctrl-e end
444 execute(...) (see below for the details)
445 execute-silent(...) (see below for the details)
446 forward-char ctrl-f right
447 forward-word alt-f shift-right
448 if-non-matched
449 if-query-empty
450 if-query-not-empty
451 ignore
452 kill-line
453 kill-word alt-d
454 next-history (ctrl-n on --history or --cmd-history)
455 page-down pgdn
456 page-up pgup
457 half-page-down
458 half-page-up
459 preview-up shift-up
460 preview-down shift-down
461 preview-left
462 preview-right
463 preview-page-down
464 preview-page-up
465 previous-history (ctrl-p on --history or --cmd-history)
466 select-all
467 toggle
468 toggle-all
469 toggle+down ctrl-i (tab)
470 toggle-in (--layout=reverse* ? toggle+up : toggle+down)
471 toggle-out (--layout=reverse* ? toggle+down : toggle+up)
472 toggle-preview
473 toggle-preview-wrap
474 toggle-sort
475 toggle+up btab (shift-tab)
476 unix-line-discard ctrl-u
477 unix-word-rubout ctrl-w
478 up ctrl-k ctrl-p up
479 yank ctrl-y
480 Multiple actions can be chained using + separator.
482 sk --bind 'ctrl-a:select-all+accept'
484 With execute(...) action, you can execute arbitrary commands without
486 leaving sk. For example, you can turn sk into a simple file browser by
487 binding enter key to less command like follows.
488 sk --bind "enter:execute(less {})"
490 You can use the same placeholder expressions as in --preview.
492 If the command contains parentheses, sk may fail to parse the expres‐
494 sion. In that case, you can use any of the following alternative nota‐
495 tions to avoid parse errors.
496 execute[...]
498 execute'...'
499 execute"..."
500 execute:...
501 This is the special form that frees you from parse errors as it
502 does not expect the closing character. The catch is that it
503 should be the last one in the comma-separated list of key-action
504 pairs.
505 sk switches to the alternate screen when executing a command. However,
507 if the command is expected to complete quickly, and you are not inter‐
508 ested in its output, you might want to use execute-silent instead,
509 which silently executes the command without the switching. Note that sk
510 will not be responsive until the command is complete. For asynchronous
511 execution, start your command as a background process (i.e. appending
512 &).
513 With if-query-empty and if-query-not-empty action, you could specify
515 the action to execute depends on the query condition. For example
516 sk --bind 'ctrl-d:if-query-empty(abort)+delete-char'
518 If the query is empty, skim will execute abort action, otherwise exe‐
520 cute delete-char action. It is equal to `delete-char/eof`.
521
524 Jinzhou Zhang (lotabout@gmail.com)
525
528 Project homepage:
529 https://github.com/lotabout/skim
530 Extra Vim plugin:
532 https://github.com/lotabout/skim.vim
533
536 MIT
537sk 0.17.5 Oct 2018 sk(1)