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 ex‐
43 pressions
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 search result(normally used together
52 with --no-sort)
53 --no-sort
56 Do not sort the search result(normally used together with --tac)
57 e.g. history | sk --tac --no-sort
59 --tiebreak=CRI[,..]
61 Comma-separated list of sort criteria to apply when the scores
62 are tied.
63 score Score of the fuzzy match algorithm
65 index Prefers line that appeared earlier in the input stream
66 begin Prefers line with matched substring closer to the begin‐
67 ning
68 end Prefers line with matched substring closer to the end
69 length Prefers line with shorter length
70 - Each criterion could be negated, e.g. (-index)
72 - Each criterion should appear only once in the list
73 Interface
75 -i, --interactive
76 Start the finder in the command query
77 -c, --cmd [cmd]
79 Specify the command to invoke for fetching options
80 -I replstr
82 Replace replstr with the selected item
83 -m, --multi
85 Enable multi-select with tab/shift-tab
86 --no-multi
88 Disable multi-select
89 --bind=KEYBINDS
91 Comma-separated list of custom key bindings. See KEY BINDINGS
92 for the details.
93 --no-hscroll
95 Disable horizontal scroll
96 --height=HEIGHT[%]
98 Display sk window below the cursor with the given height instead
99 of using the full screen.
100 --min-height=HEIGHT
102 Minimum height when --height is given in percent (default: 10).
103 Ignored when --height is not specified.
104 --layout=LAYOUT
106 Choose the layout (default: default)
107 default Display from the bottom of the screen
109 reverse Display from the top of the screen
110 reverse-list Display from the top of the screen, prompt at the
111 bottom
112 --reverse
115 A synonym for --layout=reverse
116 --margin=MARGIN
119 Comma-separated expression for margins around the finder.
120 TRBL Same margin for top, right, bottom, and left
122 TB,RL Vertical, horizontal margin
123 T,RL,B Top, horizontal, bottom margin
124 T,R,B,L Top, right, bottom, left margin
125 Each part can be given in absolute number or in percentage rela‐
127 tive to the terminal size with % suffix.
128 e.g. sk --margin 10%
130 sk --margin 1,5%
131 --inline-info
133 Display finder info inline with the query
134 -p --prompt=STR
136 Input prompt (default: '> ')
137 --cmd-prompt=STR
139 Command prompt (default: 'c> ')
140 --header=STR
142 The given string will be printed as the sticky header. The lines
143 are displayed in the given order from top to bottom regardless
144 of --layout option, and are not affected by --with-nth. ANSI
145 color codes are processed even when --ansi is not set.
146 --header-lines=N
148 The first N lines of the input are treated as the sticky header.
149 When --with-nth is set, the lines are transformed just like the
150 other lines that follow.
151 --keep-right
153 Keep the right end of the line visible when it's too long. Ef‐
154 fective only when the query string is empty.
155 --skip-to-pattern
157 Line will start with the start of the matched pattern. Effective
158 only when the query string is empty. Was designed to skip show‐
159 ing starts of paths of rg/grep results.
160 e.g. sk -i -c "rg {} --color=always" --skip-to-pattern '[^/]*:'
163 --ansi
164 --no-clear-if-empty
167 Do not clear previous items if new command returns empty result.
168 This might be useful to reduce flickering when typing new com‐
169 mands and the half-complete commands are not valid.
170 This is not default however because similar usecases for grep
172 and rg had already been optimized where empty result of a query
173 do mean "empty" and previous results should be cleared.
174 --show-cmd-error
177 If the command fails, send the error messages and show them as
178 items. This option was intended to help debugging interactive
179 commands. It's not enabled by default because the command often
180 fails before we complete the "cmd-query" and error messages
181 would be annoying.
182 Display
185 --ansi Enable processing of ANSI color codes
186 --tabstop=SPACES
188 Number of spaces for a tab character (default: 8)
189 --color=[BASE_SCHEME][,COLOR:ANSI]
191 Color configuration. The name of the base color scheme is fol‐
192 lowed by custom color mappings. Ansi color code of -1 denotes
193 terminal default foreground/background color. You can also spec‐
194 ify 24-bit color in #rrggbb format.
195 e.g. sk --color=bg+:24
197 sk --color=light,fg:232,bg:255,bg+:116,info:27
198 BASE SCHEME:
200 (default: dark on 256-color terminal, otherwise 16)
201 dark Color scheme for dark 256-color terminal
203 light Color scheme for light 256-color terminal
204 16 Color scheme for 16-color terminal
205 bw No colors
206 COLOR:
208 fg Text
209 bg Background
210 matched|hl Text of highlighted substrings
211 matched_bg Background of highlighted substrings
212 current|fg+ Text (current line)
213 current_bg|bg+ Background (current line)
214 current_match|hl+ Text of Highlighted substrings (current
215 line)
216 current_match_bg Background of highlighted substrings (cur‐
217 rent line)
218 query Text of Query (the texts after the prompt)
219 query_bg Background of Query
220 info Info
221 border Border of the preview window and horizon‐
222 tal separators (--border)
223 prompt Prompt
224 pointer|cursor Pointer to the current line (no effect
225 now)
226 marker|selected Multi-select marker
227 spinner Streaming input indicator
228 header Header
229 History
231 --history=HISTORY_FILE
232 Load search history from the specified file and update the file
233 on completion. When enabled, CTRL-N and CTRL-P are automati‐
234 cally remapped to next-history and previous-history.
235 --history-size=N
237 Maximum number of entries in the history file (default: 1000).
238 The file is automatically truncated when the number of the lines
239 exceeds the value.
240 --cmd-history=HISTORY_FILE
242 Load command query history from the specified file and update
243 the file on completion. When enabled, CTRL-N and CTRL-P are au‐
244 tomatically remapped to next-history and previous-history.
245 --cmd-history-size=N
247 Maximum number of command query entries in the history file (de‐
248 fault: 1000). The file is automatically truncated when the num‐
249 ber of the lines exceeds the value.
250 Preview
252 --preview=COMMAND
253 Execute the given command for the current line and display the
254 result on the preview window. {} in the command is the place‐
255 holder that is replaced to the single-quoted string of the cur‐
256 rent line. To transform the replacement string, specify field
257 index expressions between the braces (See FIELD INDEX EXPRESSION
258 for the details).
259 e.g. sk --preview='head -$LINES {}'
261 ls -l | sk --preview="echo user={3} when={-4..-2}; cat
262 {-1}" --header-lines=1
263 sk overrides $LINES and $COLUMNS so that they represent the ex‐
265 act size of the preview window.
266 A placeholder expression starting with + flag will be replaced
268 to the space-separated list of the selected lines (or the cur‐
269 rent line if no selection was made) individually quoted.
270 e.g.
272 sk --multi --preview='head -10 {+}'
273 git log --oneline | sk --multi --preview 'git show {+1}'
274 Note that you can escape a placeholder pattern by prepending a
277 backslash.
278 Also, {q} is replaced to the current query string. {cq} is re‐
280 placed to the current command query string. {n} is replaced to
281 zero-based ordinal index of the line. Use {+n} if you want all
282 index numbers when multiple lines are selected
283 Preview window will be updated even when there is no match for
285 the current query if any of the placeholder expressions evalu‐
286 ates to a non-empty string.
287 --preview-window=[POSITION][:SIZE[%]][:wrap][:hidden][:+SCROLL[-OFF‐
289 SET]]
290 POSITION: (default: right)
292 up
293 down
294 left
295 right
296 Determine the layout of the preview window. If the argument ends with
298 :hidden, the preview window will be hidden by default until toggle-pre‐
299 view action is triggered. Long lines are truncated by default. Line
300 wrap can be enabled with :wrap flag.
301 If size is given as 0, preview window will not be visible, but sk will
303 still execute the command in the background.
304 +SCROLL[-OFFSET] determines the initial scroll offset of the preview
306 window. SCROLL can be either a numeric integer or a single-field index
307 expression that refers to a numeric integer. The optional -OFFSET part
308 is for adjusting the base offset so that you can see the text above it.
309 It should be given as a numeric integer (-INTEGER), or as a denominator
310 form (-/INTEGER) for specifying a fraction of the preview window
311 height.
312 e.g.
314 # Non-default scroll window positions and sizes
315 sk --preview="head {}" --preview-window=up:30%
316 sk --preview="file {}" --preview-window=down:2
317 # Initial scroll offset is set to the line number of each
319 line of
320 # git grep output *minus* 5 lines (-5)
321 git grep --line-number '' |
322 sk --delimiter : --preview 'nl {1}' --preview-window
323 +{2}-5
324 # Preview with bat, matching line in the middle of the win‐
326 dow (-/2)
327 git grep --line-number '' |
328 sk --delimiter : \
329 --preview 'bat --style=numbers --color=always --high‐
330 light-line {2} {1}' \
331 --preview-window +{2}-/2
332 Scripting
336 -q, --query=STR
337 Start the finder with the given query
338 --cmd-query=STR
340 Specify the initial query for the command query
341 --print-query
343 Print query as the first line
344 -f, --filter=STR
346 Filter mode. Do not start interactive finder. It's like a fuzzy-
347 version of grep. skim will output the score and the item to std‐
348 out.
349 --expect=KEY[,..]
351 Comma-separated list of keys that can be used to complete sk in
352 addition to the default enter key. When this option is set, sk
353 will print the name of the key pressed as the first line of its
354 output (or as the second line if --print-query is also used).
355 The line will be empty if sk is completed with the default enter
356 key. If --expect option is specified multiple times, sk will ex‐
357 pect the union of the keys. --no-expect will clear the list.
358 e.g. sk --expect=ctrl-v,ctrl-t,alt-s --expect=f1,f2,~,@
360 --read0
362 Read input delimited by ASCII NUL characters instead of newline
363 characters
364 --print0
366 Print output delimited by ASCII NUL characters instead of new‐
367 line characters
368 --no-clear
370 Do not clear finder interface on exit. If skim was started in
371 full screen mode, it will not switch back to the original
372 screen, so you'll have to manually run tput rmcup to return.
373 This option can be used to avoid flickering of the screen when
374 your application needs to start skim multiple times in order.
375 -1, --select-1
377 Automatically select the only match
378 -0, --exit-0
380 Exit immediately when there's no match
381 --sync Synchronous search for multi-staged filtering. If specified,
383 skim will launch ncurses finder only after the input stream is
384 complete.
385 e.g. sk --multi | sk --sync
387 --pre-select-n=NUM
390 Pre-select the first NUM items in the multi-selection mode.
391 --pre-select-pat=REGEX
393 Pre-select the items that matches the REGEX specified in multi-
394 selection mode. Check the doc for the detailed syntax:
395 https://docs.rs/regex/1.4.1/regex/
396 --pre-select-items=$'item1\nitem2'
398 Pre-select the specified items (separated by newline character)
399 in multi-selection mode.
400 --pre-select-file=FILENAME
402 Pre-select the items read from FILENAME (separated by newline
403 character) in multi-selection mode.
404 --version
407 Display version information and exit
408
411 SKIM_DEFAULT_COMMAND
412 Default command to use when input is tty. On *nix systems, sk
413 runs the command with sh -c, so make sure that it's POSIX-com‐
414 pliant.
415 SKIM_DEFAULT_OPTIONS
417 Default options. e.g. export SKIM_DEFAULT_OPTIONS="--multi
418
421 0 Normal exit
422 1 No match
423 2 Error
424 130 Interrupted with CTRL-C or ESC
425
428 A field index expression can be a non-zero integer or a range expres‐
429 sion ([BEGIN]..[END]). --nth and --with-nth take a comma-separated list
430 of field index expressions.
431 Examples
434 1 The 1st field
435 2 The 2nd field
436 -1 The last field
437 -2 The 2nd to last field
438 3..5 From the 3rd field to the 5th field
439 2.. From the 2nd field to the last field
440 ..-3 From the 1st field to the 3rd to the last field
441 .. All the fields
442
445 Unless specified otherwise, sk will start in "extended-search mode". In
446 this mode, you can specify multiple patterns delimited by spaces, such
447 as: 'wild ^music .mp3$ sbtrkt !rmx
448 You can prepend a backslash to a space (\ ) to match a literal space
450 character.
451 Exact-match (quoted)
454 A term that is prefixed by a single-quote character (') is interpreted
455 as an "exact-match" (or "non-fuzzy") term. sk will search for the exact
456 occurrences of the string.
457 Anchored-match
460 A term can be prefixed by ^, or suffixed by $ to become an anchored-
461 match term. Then sk will search for the lines that start with or end
462 with the given string. An anchored-match term is also an exact-match
463 term.
464 Negation
467 If a term is prefixed by !, sk will exclude the lines that satisfy the
468 term from the result. In this case, sk performs exact match by default.
469 Exact-match by default
472 If you don't prefer fuzzy matching and do not wish to "quote" (prefix‐
473 ing with ') every word, start sk with -e or --exact option. Note that
474 when --exact is set, '-prefix "unquotes" the term.
475 OR operator
478 A single bar character term acts as an OR operator. For example, the
479 following query matches entries that start with core and end with ei‐
480 ther go, rb, or py.
481 e.g. ^core go$ | rb$ | py$
483
486 You can customize key bindings of sk with --bind option which takes a
487 comma-separated list of key binding expressions. Each key binding ex‐
488 pression follows the following format: KEY:ACTION
489 e.g. sk --bind=ctrl-j:accept,ctrl-k:kill-line
491 AVAILABLE KEYS: (SYNONYMS)
493 ctrl-[a-z]
494 ctrl-space
495 ctrl-alt-[a-z]
496 alt-[a-zA-Z]
497 alt-[0-9]
498 f[1-12]
499 enter (ctrl-m)
500 space
501 bspace (bs)
502 alt-up
503 alt-down
504 alt-left
505 alt-right
506 alt-enter (alt-ctrl-m)
507 alt-space
508 alt-bspace (alt-bs)
509 alt-/
510 tab
511 btab (shift-tab)
512 esc
513 del
514 up
515 down
516 left
517 right
518 home
519 end
520 pgup (page-up)
521 pgdn (page-down)
522 shift-up
523 shift-down
524 shift-left
525 shift-right
526 alt-shift-up
527 alt-shift-down
528 alt-shift-left
529 alt-shift-right
530 or any single character
531 ACTION: DEFAULT BINDINGS (NOTES):
533 abort ctrl-c ctrl-q esc
534 accept enter
535 append-and-select
536 backward-char ctrl-b left
537 backward-delete-char ctrl-h bspace
538 backward-kill-word alt-bs
539 backward-word alt-b shift-left
540 beginning-of-line ctrl-a home
541 clear-screen ctrl-l
542 delete-char del
543 delete-charEOF ctrl-d
544 deselect-all
545 down ctrl-j ctrl-n down
546 end-of-line ctrl-e end
547 execute(...) (see below for the details)
548 execute-silent(...) (see below for the details)
549 forward-char ctrl-f right
550 forward-word alt-f shift-right
551 if-non-matched
552 if-query-empty
553 if-query-not-empty
554 ignore
555 kill-line
556 kill-word alt-d
557 next-history (ctrl-n on --history or --cmd-history)
558 page-down pgdn
559 page-up pgup
560 half-page-down
561 half-page-up
562 preview-up shift-up
563 preview-down shift-down
564 preview-left
565 preview-right
566 preview-page-down
567 preview-page-up
568 previous-history (ctrl-p on --history or --cmd-history)
569 select-all
570 toggle
571 toggle-all
572 toggle+down ctrl-i (tab)
573 toggle-in (--layout=reverse* ? toggle+up : toggle+down)
574 toggle-out (--layout=reverse* ? toggle+down : toggle+up)
575 toggle-preview
576 toggle-preview-wrap
577 toggle-sort
578 toggle+up btab (shift-tab)
579 unix-line-discard ctrl-u
580 unix-word-rubout ctrl-w
581 up ctrl-k ctrl-p up
582 yank ctrl-y
583 Multiple actions can be chained using + separator.
585 sk --bind 'ctrl-a:select-all+accept'
587 With execute(...) action, you can execute arbitrary commands without
589 leaving sk. For example, you can turn sk into a simple file browser by
590 binding enter key to less command like follows.
591 sk --bind "enter:execute(less {})"
593 You can use the same placeholder expressions as in --preview.
595 If the command contains parentheses, sk may fail to parse the expres‐
597 sion. In that case, you can use any of the following alternative nota‐
598 tions to avoid parse errors.
599 execute[...]
601 execute'...'
602 execute"..."
603 execute:...
604 This is the special form that frees you from parse errors as it
605 does not expect the closing character. The catch is that it
606 should be the last one in the comma-separated list of key-action
607 pairs.
608 sk switches to the alternate screen when executing a command. However,
610 if the command is expected to complete quickly, and you are not inter‐
611 ested in its output, you might want to use execute-silent instead,
612 which silently executes the command without the switching. Note that sk
613 will not be responsive until the command is complete. For asynchronous
614 execution, start your command as a background process (i.e. appending
615 &).
616 With if-query-empty and if-query-not-empty action, you could specify
618 the action to execute depends on the query condition. For example
619 sk --bind 'ctrl-d:if-query-empty(abort)+delete-char'
621 If the query is empty, skim will execute abort action, otherwise exe‐
623 cute delete-char action. It is equal to `delete-char/eof`.
624
627 Jinzhou Zhang (lotabout@gmail.com)
628
631 Project homepage:
632 https://github.com/lotabout/skim
633 Extra Vim plugin:
635 https://github.com/lotabout/skim.vim
636
639 MIT
640sk 0.17.5 Oct 2018 sk(1)