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