> Life is short, skim!
We spend so much of our time navigating through files, lines, and commands. That's where Skim comes in!
It's a powerful fuzzy finder designed to make your workflow faster and more efficient.
Skim provides a single executable called `sk`. Think of it as a smarter alternative to tools like
`grep` - once you try it, you'll wonder how you ever lived without it!
# Table of contents
- [Installation](#installation)
* [Package Managers](#package-managers)
* [Manually](#manually)
- [Usage](#usage)
* [As Vim plugin](#as-vim-plugin)
* [As filter](#as-filter)
* [As Interactive Interface](#as-interactive-interface)
* [Shell Bindings](#shell-bindings)
* [Key Bindings](#key-bindings)
* [Search Syntax](#search-syntax)
* [exit code](#exit-code)
- [Tools compatible with `skim`](#tools-compatible-with-skim)
* [fzf-lua neovim plugin](#fzf-lua-neovim-plugin)
* [nu_plugin_skim](#nu_plugin_skim)
- [Customization](#customization)
* [Keymap](#keymap)
* [Sort Criteria](#sort-criteria)
* [Color Scheme](#color-scheme)
* [Misc](#misc)
- [Advanced Topics](#advanced-topics)
* [Interactive mode](#interactive-mode)
+ [How does it work?](#how-does-it-work)
* [Executing external programs](#executing-external-programs)
* [Algorithms](#algorithms)
* [Preview Window](#preview-window)
+ [How does it work?](#how-does-it-work-1)
* [Fields support](#fields-support)
* [Use as a library](#use-as-a-library)
* [Benchmarks](#benchmarks)
- [FAQ](#faq)
* [How to ignore files?](#how-to-ignore-files)
* [Some files are not shown in Vim plugin](#some-files-are-not-shown-in-vim-plugin)
- [Differences from fzf](#differences-from-fzf)
- [How to contribute](#how-to-contribute)
* [Windows compatibility testing](#windows-compatibility-testing)
- [Troubleshooting](#troubleshooting)
* [No line feed issues with nix, FreeBSD, termux](#no-line-feed-issues-with-nix-freebsd-termux)
# Installation
The skim project contains several components:
1. `sk` executable - the core program
2. Vim/Nvim plugin - to call `sk` inside Vim/Nvim. Check [skim.vim](https://github.com/skim-rs/skim/blob/master/plugin/skim.vim) for Vim support.
## Package Managers
| OS | Package Manager | Command |
| -------------- | --------------- | ---------------------------- |
| macOS | Homebrew | `brew install sk` |
| macOS | MacPorts | `sudo port install skim` |
| Alpine | apk | `apk add skim` |
| Arch | pacman | `pacman -S skim` |
| Fedora | COPR | see below |
| Gentoo | Portage | `emerge --ask app-misc/skim` |
| Guix | guix | `guix install skim` |
| Void | XBPS | `xbps-install -S skim` |
| Windows | winget | `winget install skim` |
| Windows | Scoop | `scoop install skim` |
| Debian/Ubuntu | apt | see below |
| Fedora/RHEL | dnf | see below |
### Debian/Ubuntu
A custom APT repository is available and updated automatically during each release:
1. Import the signing key
With wget:
```sh
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/skim.asc https://skim-rs.github.io/skim/apt/skim-archive-keyring.asc
```
Or with cURL:
```sh
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://skim-rs.github.io/skim/apt/skim-archive-keyring.asc | sudo tee /etc/apt/keyrings/skim.asc > /dev/null
```
2. Add the repository
```sh
echo 'deb [signed-by=/etc/apt/keyrings/skim.asc] https://skim-rs.github.io/skim/apt ./' | sudo tee /etc/apt/sources.list.d/skim.list
sudo apt-get update
```
3. Install
```sh
sudo apt-get install skim
```
Alternatively, `.deb` packages are attached directly to every [release](https://github.com/skim-rs/skim/releases/latest).
Download the one matching your architecture and run `sudo dpkg -i skim_*_amd64.deb`
### Fedora/RHEL
Up-to-date Fedora/RHEL packages are provided via an unofficial community-maintained COPR repository.
```bash
sudo dnf copr enable sisyphus1813/skim
sudo dnf install skim
```
Alternatively, `.rpm` packages are attached directly to every [release](https://github.com/skim-rs/skim/releases/latest).
Download it and run `sudo rpm -i skim-*.x86_64.rpm`
## Manually
Any of the following applies:
- Using the install script:
```sh
# Always check the content of the script before running it !
$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/skim-rs/skim/releases/latest/download/skim-installer.sh | sh
```
- Using Binary: Simply [download the sk executable](https://github.com/skim-rs/skim/releases) directly.
- Install from [crates.io](https://crates.io/): `cargo install skim`
- Build Manually:
```sh
$ git clone --depth 1
[email protected]:skim-rs/skim.git ~/.skim
$ cd ~/.skim
$ cargo build --release
$ # Add the resulting `target/release/sk` executable to your PATH
```
You will then have access to:
- The man page, which you can either write to the correct path or run `man --local-file <(sk --man)`
- The shell completions (and optional keybinds), using `source <(sk --shell \ \[--shell-bindings])`, see below for details
# Usage
Skim can be used either as a general filter (similar to `grep`) or as an interactive
interface for running commands.
## As Vim plugin (on neovim, checkout [fzf-lua](https://github.com/ibhagwan/fzf-lua) with the skim profile)
Via vim-plug (recommended):
Install skim, then :
```vim
Plug 'skim-rs/skim'
```
## As filter
Here are some examples to get you started:
```bash
# directly invoke skim
sk
# Or pipe some input to it (press TAB key to select multiple items when -m is enabled)
vim $(find . -name "*.rs" | sk -m)
```
This last command lets you select files with the ".rs" extension and opens
your selections in Vim - a great time-saver for developers!
## As Interactive Interface
`skim` can invoke other commands dynamically. Normally you would want to
integrate it with [grep](https://www.gnu.org/software/grep/),
[ack](https://github.com/petdance/ack2),
[ag](https://github.com/ggreer/the_silver_searcher), or
[rg](https://github.com/BurntSushi/ripgrep) for searching contents in a
project directory:
```sh
# works with grep
sk --ansi -i -c 'grep -rI --color=always --line-number {q} .'
# works with ack
sk --ansi -i -c 'ack --color {q}'
# works with ag
sk --ansi -i -c 'ag --color {q}'
# works with rg
sk --ansi -i -c 'rg --color=always --line-number {q}'
```
> **Note**: In these examples, `{q}` will be literally expanded to the current input query (wrapped in single quotes).
> This means these examples will search for the exact query string, not fuzzily.
> For fuzzy searching, pipe the command output into `sk` without using interactive mode.
## Shell Bindings
Bindings for Fish, Bash and Zsh are available in the `shell` directory:
- `completion.{shell}` contains the completion scripts for `sk` cli usage
- `key-bindings.{shell}` contains key-binds and shell integrations:
- `ctrl-t` to select a file through `sk`
- `ctrl-r` to select an history entry through `sk`
- `alt-c` to `cd` into a directory selected through `sk`
- (not available in `fish`) `**` to complete file paths, for example `ls **` will show a `sk` widget to select a folder
To enable these features, source the `key-bindings.{shell}` file and set up completions according to your shell's documentation or see below.
### Shell Completions
You can generate shell completions for your preferred shell using the `--shell` flag with one of the supported shells: `bash`, `zsh`, `fish`, `powershell`, or `elvish`:
#### Option 1: Source directly in your current shell session
```sh
# For bash
source <(sk --shell bash)
# For zsh
source <(sk --shell zsh)
# For fish
sk --shell fish | source
```
#### Option 2: Save to a file to be loaded automatically on shell startup
```sh
# For bash, add to ~/.bashrc
echo 'source <(sk --shell bash)' >> ~/.bashrc # Or save to ~/.bash_completion
# For zsh, add to ~/.zshrc
sk --shell zsh > ~/.zfunc/_sk # Create ~/.zfunc directory and add to fpath in ~/.zshrc
# For fish, add to ~/.config/fish/completions/
sk --shell fish > ~/.config/fish/completions/sk.fish
```
## Key Bindings
Some commonly used key bindings:
| 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`) |
For a complete list of key bindings, refer to the [man
page](https://github.com/skim-rs/skim/blob/master/man/man1/sk.1) (`man sk`).
## Search Syntax
`skim` borrows `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 supports the combination of tokens.
- Whitespace has the meaning of `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` has higher precedence. For example, `readme .md$ | .markdown$` is interpreted as
`readme AND (.md$ OR .markdown$)`.
- When using the `--split-match` option, each part around spaces or `|` will be matched in a split way:
- If the option's value (defaulting to `:`) is absent from the query, do a normal match
- If it is present, match everything before to everything before it in the items, and everything after it (including potential other occurrences of the delimiter) to the part after it in the items. This is particularly useful when piping in input from `rg` to match on both file name and content.
If you prefer using regular expressions, `skim` offers a `regex` mode:
```sh
sk --regex
```
You can switch to `regex` mode dynamically by pressing `Ctrl-R` (Rotate Mode).
## exit code
| Exit Code | Meaning |
|-----------|-------------------------------------|
| 0 | Exited normally |
| 1 | No Match found |
| 130 | Aborted by Ctrl-C/Ctrl-G/ESC/etc... |
# Tools compatible with `skim`
These tools are or aim to be compatible with `skim`:
## [fzf-lua neovim plugin](https://github.com/ibhagwan/fzf-lua)
A [