## 手动安装

以下任一方式均可：

- 使用安装脚本：
    ```sh
    # 运行前务必检查脚本内容！
    $ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/skim-rs/skim/releases/latest/download/skim-installer.sh | sh
    ```
- 使用二进制文件：直接[下载 sk 可执行文件](https://github.com/skim-rs/skim/releases)。
- 从 [crates.io](https://crates.io/) 安装：`cargo install skim`
- 手动构建：
    ```sh
    $ git clone --depth 1 [email protected]:skim-rs/skim.git ~/.skim
    $ cd ~/.skim
    $ cargo build --release
    $ # 将生成的 `target/release/sk` 可执行文件添加到你的 PATH 中
    ```

之后你将可以使用：

- 手册页，你可以将其写入正确路径，或运行 `man --local-file <(sk --man)`
- Shell 补全（以及可选按键绑定），使用 `source <(sk --shell \<shell> \[--shell-bindings])`，详见下文

# 用法

Skim 既可以作为通用过滤器（类似于 `grep`）使用，也可以作为运行命令的交互式界面使用。

## 作为 Vim 插件（在 neovim 上，请查看带 skim 配置文件的 [fzf-lua](https://github.com/ibhagwan/fzf-lua)）

通过 vim-plug（推荐）：

安装 skim，然后：```vim
Plug 'skim-rs/skim'

最后这条命令让你选择扩展名为“.rs”的文件，并在 Vim 中打开所选内容——对开发者来说，这能节省大量时间！

## 作为交互式界面

`skim` 可以动态调用其他命令。通常，你会希望将其与 [grep](https://www.gnu.org/software/grep/)、
[ack](https://github.com/petdance/ack2)、
[ag](https://github.com/ggreer/the_silver_searcher) 或
[rg](https://github.com/BurntSushi/ripgrep) 集成，用于在项目目录中搜索内容：```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}'

#### 选项 2：保存到文件，以便在 Shell 启动时自动加载```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

您可以通过按 `Ctrl-R`（旋转模式）动态切换到 `regex` 模式。

## 退出代码

| 退出代码 | 含义                             |
|-----------|-------------------------------------|
| 0         | 正常退出                     |
| 1         | 未找到匹配项                      |
| 130       | 由 Ctrl-C/Ctrl-G/ESC 等中止... |

# 与 `skim` 兼容的工具

以下工具与 `skim` 兼容或旨在实现兼容：

## [fzf-lua neovim 插件](https://github.com/ibhagwan/fzf-lua)

一个 [neovim](https://neovim.io) 插件，允许在代码导航中使用 fzf 和 skim。

按照 README 使用您的包管理器进行安装。例如，使用 `lazy.nvim`：```lua
{
  "ibhagwan/fzf-lua",
  -- enable `sk` support instead of the default `fzf`
  opts = {'skim'}
}

## [sqlite 扩展](https://github.com/tzachar/sqlite_skim)

一个可加载的 `sqlite` 模块，可在 SQL 查询中启用 `skim_score` 函数。

# 自定义

此处文档仅为预览，完整选项列表请查看手册页（`man sk`）。

## 键位映射

使用逗号分隔的键值对来指定绑定（不允许有空格）。例如：```sh
sk --bind 'alt-a:select-all,alt-d:deselect-all'

Skim 也遵循 `NO_COLOR` 环境变量。将其设置为任意值后，`sk`（以及许多其他终端应用）将禁用所有彩色输出。更多详情请参阅 [no-color.org](https://no-color.org/)。

### 可用的基础配色方案

Skim 内置了多种配色方案，你可以将其作为起点使用：```sh
sk --color=dark      # Default dark theme (256 colors)
sk --color=light     # Light theme (256 colors)
sk --color=16        # Simple 16-color theme
sk --color=bw        # Minimal black & white theme (no colors, just styles)
sk --color=none      # Minimal black & white theme (no colors, no styles)
sk --color=molokai   # Molokai-inspired theme (256 colors)

颜色可以通过以下几种方式指定：

- ANSI 颜色（0-255）：`sk --color=fg:232,bg:255`
- RGB 十六进制值：`sk --color=fg:#FF0000`（红色文本）

### 可用的颜色自定义选项

以下 UI 元素可以进行自定义：

| 元素                | 描述                                   | 示例                            |
|--------------------|---------------------------------------------|--------------------------------|
| `fg`               | 普通文本前景色                            | `--color=fg:232`               |
| `bg`               | 普通文本背景色                            | `--color=bg:255`               |
| `matched`          | 搜索结果中匹配的文本                      | `--color=matched:108`          |
| `matched_bg`       | 匹配文本的背景色                          | `--color=matched_bg:0`         |
| `current`          | 当前行的前景色                            | `--color=current:254`          |
| `current_bg`       | 当前行的背景色                            | `--color=current_bg:236`       |
| `current_match`    | 当前行中匹配的文本                        | `--color=current_match:151`    |
| `current_match_bg` | 当前行中匹配文本的背景色                  | `--color=current_match_bg:236` |
| `spinner`          | 进度指示器颜色                            | `--color=spinner:148`          |
| `info`             | 信息行颜色                                | `--color=info:144`             |
| `prompt`           | 提示符颜色                                | `--color=prompt:110`           |
| `cursor`           | 光标颜色                                  | `--color=cursor:161`           |
| `selected`         | 选中项标记颜色                            | `--color=selected:168`         |
| `header`           | 标题文本颜色                              | `--color=header:109`           |
| `border`           | 预览/布局的边框颜色                       | `--color=border:59`            |

### 示例```sh
# Use light theme but change the current line background
sk --color=light,current_bg:24

# Custom theme with multiple colors
sk --color=dark,matched:#00FF00,current:#FFFFFF,current_bg:#000080

# High contrast theme
sk --color=fg:232,bg:255,matched:160,current:255,current_bg:20

### 它是如何工作的？

![Skim 交互模式的工作原理](https://assets.kitploit.com/production/public/readmes/54416/5895df8cd6dbe8dfe20cafd1bf0b23fd690191710c00f811e110aba228b32a35/a7b995846d08eb2aa7f351371b38a9a35261eb393632363f62c6a67785f4038e-display-v1.webp)

- Skim 接受两种来源：命令输出或管道输入
- Skim 有两种提示符：用于指定查询模式的查询提示符，以及
    用于指定命令“参数”的命令提示符
- `-c` 用于指定要执行的命令，默认为 `SKIM_DEFAULT_COMMAND`
- `-i` 告诉 skim 在启动时打开命令提示符，默认会显示 `c>`。

要进一步缩小命令返回的结果范围，请按
`Ctrl-Q` 切换交互模式。

## 执行外部程序

您可以配置按键绑定，在不退出 Skim 的情况下启动外部进程（`execute`、`execute-silent`）。```sh
# Press F1 to open the file with less without leaving skim
# Press CTRL-Y to copy the line to clipboard and aborts skim (requires pbcopy)
sk --bind 'f1:execute(less -f {}),ctrl-y:execute-silent(echo {} | pbcopy)+abort'

（注意：[preview.sh](https://github.com/junegunn/fzf.vim/blob/master/bin/preview.sh) 是一个脚本，用于根据文件名:行号:列号打印上下文）

你会得到类似这样的效果：

![预览演示](https://assets.kitploit.com/production/public/readmes/54416/b89dd1e40297ffc3fa4684c4a6d5dc9506c0eafdb881d4cea079ff843f1a271a/84156872f39354a97241078491506fee9f9962eda6628161f94f6f36ec2c79f9-display-v1.webp)

### 它是如何工作的？

如果通过 `--preview` 选项指定了预览命令，skim 会将 `{}` 替换为当前高亮行（用单引号包围），调用该命令获取输出，并在预览窗口中打印输出。

有时你不需要整行来调用命令。在这种情况下，你可以使用 `{}`、`{1..}`、`{..3}` 或 `{1..5}` 来选择字段。语法在 [字段支持](#filds-support) 部分中说明。

最后，你可能想通过 `--preview-window` 配置预览窗口的位置：
- `--preview-window up:30%` 将窗口放在上方位置，高度为 skim 总高度的 30%。
- `--preview-window left:10:wrap` 指定 `wrap` 允许预览窗口对预览命令的输出进行换行。
- `--preview-window wrap:hidden` 在启动时隐藏预览窗口，之后可以通过 `toggle-preview` 操作显示。

## 字段支持

通常只有插件用户需要理解这一点。

例如，你有一个格式如下的数据源：```sh
<filename>:<line number>:<column number>

_功能说明_：
    - 使用 `cli` 功能需要将 skim 作为命令行工具使用，当将其作为库使用时*不应*需要该功能。

### 基本用法

然后尝试运行这个简单示例：```rust
extern crate skim;
use skim::prelude::*;
use std::io::Cursor;

pub fn main() {
    let options = SkimOptionsBuilder::default()
        .height("50%")
        .multi(true)
        .build()
        .unwrap();

    let input = "aaaaa\nbbbb\nccc".to_string();

    // `SkimItemReader` is a helper to turn any `BufRead` into a stream of `SkimItem`
    // `SkimItem` was implemented for `AsRef<str>` by default
    let item_reader = SkimItemReader::default();
    let items = item_reader.of_bufread(Cursor::new(input));

    // `run_with` would read and show items from the stream
    let selected_items = Skim::run_with(&options, Some(items))
        .map(|out| out.selected_items)
        .unwrap_or_else(|| Vec::new());

    for item in selected_items.iter() {
        println!("{}", item.output());
    }
}

你可以把它放进你的 `.bashrc` 或 `.zshrc` 中，如果你希望它默认生效的话。

## 某些文件在 Vim 插件中不显示

如果你使用 Vim 插件并执行 `:SK` 命令，你可能会发现部分
文件没有显示出来。

如 [#3](https://github.com/skim-rs/skim/issues/3) 中所述，在 Vim
插件中，`SKIM_DEFAULT_COMMAND` 默认被设置为该命令：```vim
let $SKIM_DEFAULT_COMMAND = "git ls-tree -r --name-only HEAD || rg --files || ag -l -g \"\" || find ."

在虚拟机内部，项目根目录挂载于 `C:\vagrant`：```powershell
cd C:\vagrant
cargo build
cargo test

# 故障排查

要排查问题，你可以将环境变量 `SKIM_LOG` 或标志 `--log-level` 设置为 `debug` 甚至 `trace`，并将环境变量 `SKIM_LOG_FILE` 或标志 `--log-file` 设置为一个路径。然后你可以在执行期间或之后读取这些日志，以更好地了解发生了什么。如果你需要帮助，请毫不犹豫地将这些日志添加到 issue 中。

## nix、FreeBSD、termux 下无换行符的问题

如果你遇到如下显示问题：```bash
$ for n in {1..10}; do echo "$n"; done | sk
  0/10 0/0.> 10/10  10  9  8  7  6  5  4  3  2> 1

# 基准测试

## 交互式基准测试（`cli`）

`cli` 基准测试通过在 tmux 会话中运行交互式界面，并轮询状态行直到匹配计数稳定，来对 skim（或任何兼容的二进制文件）与其他版本或 fzf 进行对比测试。这绝非精确或万无一失的测量方法，但其额外好处在于能够与 `fzf` 进行对比基准测试，并提供资源指标（峰值 RSS 和 CPU）。```sh
cargo bench --bench cli -- run                              # defaults: sk, 1 M items, query "test"
cargo bench --bench cli -- run sk -n 500000 -q foo              # bare name resolved via $PATH
cargo bench --bench cli -- run ./old/sk ./new/sk -r 5           # compare two binaries, 5 runs each
cargo bench --bench cli -- run sk -f input.txt -q search        # use an existing file
cargo bench --bench cli -- generate -f testdata.txt -n 2000000       # generate input file and exit
cargo bench --bench cli -- run sk --perf                            # record perf data (auto-named file)
cargo bench --bench cli -- run sk --strace                            # record strace data (auto-named file)
cargo bench --bench cli -- run sk -p perf.data                 # record perf data to perf.data
cargo bench --bench cli -- run sk -j                            # JSON output
cargo bench --bench cli -- run sk -r 3 -- --tiebreak=index     # pass extra flags to sk