Life is short, skim!
Half of our life is spent on navigation: files, lines, commands... You need skim! It is a general fuzzy finder that saves you time.
It is blazingly fast as it reads the data source asynchronously.
skim provides a single executable: sk, basically anywhere you would want to use
grep try sk instead.
skim project contains several components:
sk executable -- the core.sk-tmux -- script for launching sk in a tmux plane.sk inside vim/nvim. check skim.vim for more vim support.Clone this repository and run the install script:
sh
git clone --depth 1 git@github.com:lotabout/skim.git ~/.skim
~/.skim/install
Next: add ~/.skim/bin to your PATH by putting the following line into your ~/.bashrc
export PATH="$PATH:$HOME/.skim/bin"
As an alternative, you can directly download the sk executable, but extra utilities are recommended.
Using Homebrew:
brew install sbdchd/skim/skim
But the Linux way described above will also work.
sh
cargo install skim
Once you have cloned the repository, add the following line to your .vimrc.
vim
set rtp+=~/.skim
Or you can have vim-plug manage skim (recommended):
vim
Plug 'lotabout/skim', { 'dir': '~/.skim', 'do': './install' }
Clone the repo and run:
sh
cargo install
Alternatively, run:
sh
cargo build --release
then put the resulting target/release/sk executable on your PATH.
skim can be used as a general filter(like grep) or as an interactive
interface for invoking commands.
Try the following
```
sk
vim $(find . -name "*.rs" | sk -m) ``` The above command will allow you to select files with ".rs" extension and open the ones you selected in vim.
skim can invoke other commands dynamically. Normally you would want to
integrate it with rg
ag or
ack for searching contents in a project
directory:
```
sk --ansi -i -c 'ag --color "{}"'
sk --ansi -c 'rg --color=always --line-number "{}"' ```
Some common used keybindings.
| Key | Action |
|------------------:|--------------------------------------------|
| Enter | Accept (select current one and quit) |
| ESC/Ctrl-G | Abort |
| Ctrl-P/Up | Move cursor up |
| Ctrl-N/Down | Move cursor Down |
| TAB | Toggle selection and move down (with -m) |
| Shift-TAB | Toggle selection and move up (with -m) |
skim borrowed fzf's syntax for matching items:
| Token | Match type | Description |
|----------|----------------------------|-----------------------------------|
| text | fuzzy-match | items that match text |
| ^music | prefix-exact-match | items that start with music |
| .mp3$ | suffix-exact-match | items that end with .mp3 |
| 'wild | exact-match (quoted) | items that include wild |
| !fire | inverse-exact-match | items that do not include fire |
| !.mp3$ | inverse-suffix-exact-match | items that do not end with .mp3 |
skim also support the combination of tokens.
AND. With the term src main, skim will search
for items that match both src and main.| means OR (note the spaces around |). With the term .md$ |
.markdown$, skim will search for items ends with either .md or
.markdown.OR have higher precedence. So readme .md$ | .markdown$ is groupped into
readme AND (.md$ OR .markdown$).In case that you want to use regular expressions, skim provide regex mode:
sk --regex
You can switch to regex mode dynamically by pressing Ctrl-R (Rotate Mode).
| Exit Code | Meaning | |-----------|-----------------------------------| | 0 | Exit normally | | 1 | No Match found | | 130 | Abort by Ctrl-C/Ctrl-G/ESC/etc... |
Specify the bindings with comma seperated pairs(no space allowed), example:
sk --bind 'alt-a:select-all,alt-d:deselect-all'
| Action | Default key | |----------------------|-----------------------------| | abort | esc, ctrl-c, ctrl-g | | accept | enter | | backward-char | left, ctrl-b | | backward-delete-char | ctrl-h, backspace | | backward-kill-word | alt-backspace | | backward-word | alt-b, shift-left | | beginning-of-line | ctrl-a | | cancel | None | | clear-screen | ctrl-l | | delete-char | del | | delete-charEOF | ctrl-d | | deselect-all | None | | down | ctrl-j, ctrl-n, down | | end-of-line | ctrl-e, end | | forward-char | ctrl-f, right | | forward-word | alt-f, shift-right | | ignore | None | | kill-line | ctrl-k | | kill-word | alt-d | | page-down | page-down | | page-up | page-up | | rotate-mode | ctrl-r | | scroll-left | alt-h | | scroll-right | alt-l | | select-all | None | | toggle | None | | toggle-all | None | | toggle-down | tab | | toggle-interactive | ctrl-q | | toggle-out | None | | toggle-preview | None | | toggle-sort | None | | toggle-up | shift-tab | | unix-line-discard | ctrl-u | | unix-word-rubout | ctrl-w | | up | ctrl-p, ctrl-k, up |
There are four sort keys for results: score, index, begin, end, you can
specify how the records are sorted by sk --tiebreak score,index,-begin or any
other order you want.
It is a high chance that you are a better artist than me. Luckily you won't
be stuck with the default colors, skim supports customization of the color scheme.
--color=[BASE_SCHEME][,COLOR:ANSI]
The configuration of colors starts with the name of the base color scheme and followed by custom color mappings. For example:
sk --color=current_bg:24
sk --color=light,fg:232,bg:255,current_bg:116,info:27
You can choose the BASE SCHEME among the following(default: dark on
256-color terminal, otherwise 16):
| Base Scheme | Description | |-------------|-------------------------------------------| | dark | Color scheme for dark 256-color terminal | | light | Color scheme for light 256-color terminal | | 16 | Color scheme for 16-color terminal | | bw | No colors |
While the customisable COLORs are
| Color | Description | |------------------|--------------------------------------------------| | fg | Text | | bg | Background | | matched | Text color of matched items | | matchedbg | Background color of matched items | | current | Text color (current line) | | currentbg | Background color (current line) | | currentmatch | Text color of matched items (current line) | | currentmatch_bg | Background color of matched items (current line) | | spinner | Streaming input indicator | | info | Info area | | prompt | Prompt | | cursor | Cursor | | selected | Text color of "selected" indicator | | border | Border color of preview window |
--ansi: to parse ANSI color codes(e.g \e[32mABC) of the data source--regex: use the query as regular expression to match the data sourceIn interactive mode, sk will pass the query to the command you specified and
present the output to you. You can specify the command using the -c option:
sk -i -c 'ag --color "{}"'
In the above example, the replace string {} will be replaced with the query you
type before invoking the command. Use -I <replstr> to change replstr if you
want.
For example, with the input "hello" in interactive mode, skim will replace
the above command with ag --color "hello" and invoke it.
If you want to further narrow down the result returned by the command, press
Ctrl-Q to toggle interactive mode.
This is a great feature of fzf that skim borrows. For example, we use 'ag' to
find the matched lines, once we narrow down to the target lines, we want to
finally decide which lines to pick by checking the context around the line.
grep and ag has an option --context, skim can do better with preview
window. For example:
sk --ansi -i -c 'ag --color "{}"' --preview "preview.sh {}"
(Note the preview.sh is a script to print the context given filename:lines:columns) You got things like this:
If preview command is given by --preview option, skim will replace the {}
with the current highlighted line surrounded by single quote. Then call the
command to get the output. And print the output on the preview window.
Sometimes you don't need the whole line for invoking the command, in this case
you can use {}, {1..}, {..3} or {1..5} to select the fields. The
syntax is explained in the section "Fields Support".
Last, you might want to configure the position of preview windows, use
--preview-window.
- --preview-window up:30% to put the window in the up position with height
30% of the total height of skim.
- --preview-window left:10:wrap, to specify the wrap allows the preview
window to wrap the output of the preview command.
- --preview-window wrap:hidden to hide the preview window at startup, later
it can be shown by the action toggle-preview.
Normally only plugin users need to understand this.
For example, you have the data source with the format:
<filename>:<line number>:<column number>
However, you want to search <filename> only when typing in queries. That
means when you type 21, you want to find a <filename> that contains 21,
but not matching line number or column number.
You can use sk --delimiter ':' --nth 1 to achieve this.
Also you can use --with-nth to re-arrange the order of fields.
Range Syntax
<num> -- to specify the num-th fields, starting with 1.start.. -- starting from the start-th fields, and the rest...end -- starting from the 0-th field, all the way to end-th field,
including end.start..end -- starting from start-th field, all the way to end-th
field, including end.Skim can now be used as a library in your rust crates. The basic idea is to
throw anything that is BufRead(we can easily turn a File for String into
BufRead) and skim will do its job and bring us back the user selection
including the selected items(with their indices), the query, etc.
First, add skim into your Cargo.toml:
toml
[dependencies]
skim = "0.5.0"
Then try to run this simple example:
```rust extern crate skim; use skim::{Skim, SkimOptions}; use std::default::Default; use std::io::Cursor;
pub fn main() { let options: SkimOptions = SkimOptions::default().height("50%").multi(true);
let input = "aaaaa\nbbbb\nccc".to_string();
let selected_items = Skim::run_with(&options, Some(Box::new(Cursor::new(input))))
.map(|out| out.selected_items)
.unwrap_or_else(|| Vec::new());
for item in selected_items.iter() {
print!("{}: {}{}", item.get_index(), item.get_output_text(), "\n");
}
} ```
Check more examples under examples/ directory.
Skim invoke find . to fetch a list of files for filtering. You can override
that by setting the environment variable SKIM_DEFAULT_COMMAND. For example:
sh
$ SKIM_DEFAULT_COMMAND="git ls-tree -r --name-only HEAD || rg --files || find ."
$ sk
You could put it in your .bashrc or .zshrc if you like it to be default.
If you use the vim plugin and execute the :SK command, you might find some
of your files not shown.
As described in #3, in the vim
plugin, SKIM_DEFAULT_COMMAND is set to the command by default:
let $SKIM_DEFAULT_COMMAND = "git ls-tree -r --name-only HEAD || rg --files || ag -l -g \"\" || find ."
That means the files not recognized by git will not shown. Either override the
default with let $SKIM_DEFAULT_COMMAND = '' or find the missing file by
yourself.
fzf is a command-line fuzzy finder written in Go and skim tries to implement a new one in Rust!
This project is written from scratch. Some decisions of implementation are different from fzf. For example:
fzf will show only the range matched while
skim will show each character matched.~~ (fzf has this now)skim has an interactive mode.skim's range syntax is git style~~: now it is the same with fzf.Create new issues if you meet any bugs or have any ideas. Pull requests are warmly welcomed.