在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

junegunn/fzf

菜单

Shell 集成

相关源文件

Shell 集成是 fzf 的一项关键功能，它通过为 bash、zsh 和 fish shell 提供直观的键盘快捷键和模糊补全功能来增强命令行生产力。本文档将解释 fzf 如何与 shell 集成以及它提供的各种功能。

有关 vim 和 neovim 集成，请参阅 Vim 集成。

概述

fzf 的 Shell 集成包含两个主要组件：

  1. 键盘绑定：用于文件选择、历史搜索和目录导航的键盘快捷键。
  2. 模糊补全：具有模糊匹配功能的增强型制表符补全。

这些功能通过适应每个 shell 环境的特定于 shell 的脚本来实现。

Shell 集成架构

Shell 集成代码结构

源文件：shell/key-bindings.bash shell/key-bindings.zsh shell/key-bindings.fish shell/completion.bash shell/completion.zsh

设置 Shell 集成

从 fzf 0.48.0 开始，可以使用单个命令设置 Shell 集成：

Shell设置命令
Basheval "$(fzf --bash)"
Zshsource <(fzf --zsh)
Fishfzf --fish | source

对于旧版本的 fzf，您需要 source 位于 /shell 目录下的各个脚本文件。

您可以通过在 source 脚本时将相应的命令变量设置为空字符串来禁用特定的键盘绑定。

源文件：README.md172-207

键绑定

fzf 在所有支持的 shell 中提供以下键盘绑定：

按键绑定功能描述
CTRL-T文件选择在光标位置插入选定的文件/目录。
CTRL-R历史搜索使用模糊匹配搜索命令历史。
ALT-C目录导航切换到选定的目录。

实施流程

源文件：shell/key-bindings.bash42-105 shell/key-bindings.zsh49-138 shell/key-bindings.fish91-181 shell/completion.bash shell/completion.zsh

CTRL-T：文件选择

CTRL-T 绑定调用 fzf-file-widget 函数，允许您选择文件和目录插入到光标位置。

默认情况下，它使用 --walker file,dir,follow,hidden 选项，但您可以通过设置 FZF_CTRL_T_COMMAND 环境变量来自定义。

实现方式在不同 shell 之间略有差异，但遵循以下通用模式：

  1. 解析当前命令行以提取目录上下文和查询。
  2. 使用适当的选项设置 FZF_DEFAULT_OPTS。
  3. 使用文件遍历器或自定义命令启动 fzf。
  4. 将选定的文件插入命令行。

源文件：shell/key-bindings.bash42-46 shell/key-bindings.zsh68-73 shell/key-bindings.fish134-151

CTRL-R 绑定调用 fzf-history-widget 函数，该函数显示您的命令历史记录，并支持模糊搜索。选择命令后，它将被插入到命令行。

该实现包括对多行命令的特殊处理，并使用 --scheme=history 选项来优化历史搜索。再次按 CTRL-R 可在相关性（默认）和时间顺序之间切换排序。

在 bash 和 zsh 中，该实现使用了 Perl（如果可用），以更好地处理多行命令，并使用 awk 作为备用以实现 POSIX 兼容性。

源文件：shell/key-bindings.bash57-104 shell/key-bindings.zsh108-138 shell/key-bindings.fish153-194

ALT-C：目录导航

ALT-C 绑定调用 fzf-cd-widget 函数，允许您快速切换到选定的目录。

默认情况下，它使用 --walker dir,follow,hidden 选项，但您可以通过设置 FZF_ALT_C_COMMAND 环境变量来自定义。

该实现遵循此模式：

  1. 解析当前命令行以提取目录上下文和查询。
  2. 使用特定于目录的选项设置 FZF_DEFAULT_OPTS。
  3. 使用目录遍历器或自定义命令启动 fzf。
  4. 执行 cd 命令切换到选定的目录。

源文件：shell/key-bindings.bash48-55 shell/key-bindings.zsh82-105 shell/key-bindings.fish196-215

模糊补全

fzf 通过模糊匹配功能增强了 bash 和 zsh shell 的 Tab 补全功能（fish 不可用）。

补全触发器

当您键入一个单词后跟触发序列（默认：**）并按 TAB 键时，会激活模糊补全。

COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>

例如

# Files under current directory
vim **<TAB>

# Files under home directory
vim ~/**<TAB>

# Files under parent directory that match 'fzf'
vim ../fzf**<TAB>

# Directories only
cd **<TAB>

源文件：shell/completion.bash285-343 shell/completion.zsh331-397

补全架构

补全函数调用流程

来源： shell/completion.bash282-342 shell/completion.zsh131-183 shell/completion.bash344-392

支持的完成类型

fzf 为不同类型的输入提供模糊完成

完成类型描述使用示例
文件和目录完成文件路径vim **<TAB>
进程 ID完成进程 IDkill -9 **<TAB>
主机名从 SSH 配置完成主机名ssh **<TAB>
环境变量完成变量名unset **<TAB>, export **<TAB>
别名完成已定义的别名unalias **<TAB>

来源： shell/completion.bash393-602 shell/completion.zsh184-290

自定义完成

您可以通过几个环境变量来自定义模糊完成

环境变量描述
FZF_COMPLETION_TRIGGER更改触发序列（默认值：**）
FZF_COMPLETION_OPTS触发式 fzf 的全局选项
FZF_COMPLETION_PATH_OPTS路径完成（文件）的选项
FZF_COMPLETION_DIR_OPTS仅目录完成的选项

您还可以通过定义自定义生成器函数来定制用于完成的文件/目录列表

对于高级定制，您可以使用 _fzf_comprun 函数，根据命令定义不同的预览行为

来源： shell/completion.bash459-623 shell/completion.zsh240-328 README.md593-621

自定义模糊完成

您可以为特定命令定义自定义完成函数

  1. 定义一个名为 _fzf_complete_COMMAND 的完成函数
  2. 可以选择定义一个名为 _fzf_complete_COMMAND_post 的后处理函数
  3. 对于 bash，使用 complete 命令注册该函数

示例

来源： shell/completion.bash345-392 shell/completion.zsh194-238 README.md659-699

tmux 集成

fzf-tmux 脚本允许在 tmux 窗格或弹出窗口中启动 fzf。这可以通过环境变量控制，或直接调用。

要实现自动 tmux 集成，请设置

您也可以直接使用该脚本

与 tmux 的 Shell 集成

Shell 集成脚本使用 __fzfcmd 函数来确定是直接运行 fzf 还是通过 fzf-tmux 运行

tmux 集成流程

来源： bin/fzf-tmux1-254 shell/key-bindings.bash37-40 shell/key-bindings.zsh63-66 shell/key-bindings.fish42-51

用于自定义的环境变量

以下环境变量控制 fzf 的 Shell 集成行为

环境变量默认描述用法
FZF_TMUX0设置为 1 时，使用 fzf-tmux 而不是 fzf__fzfcmd()
FZF_TMUX_HEIGHT40%tmux 分割窗格的高度__fzf_defaults(), __fzfcmd()
FZF_TMUX_OPTS空fzf-tmux 的选项（例如：-p 80%,60%）__fzfcmd()
FZF_COMPLETION_TRIGGER**模糊完成的触发序列fzf-completion(), __fzf_generic_path_completion()
FZF_COMPLETION_OPTS空进行模糊完成时 fzf 的选项__fzf_defaults()
FZF_COMPLETION_PATH_OPTS空路径完成的选项__fzf_generic_path_completion()
FZF_COMPLETION_DIR_OPTS空目录完成的选项__fzf_generic_path_completion()
FZF_CTRL_T_COMMAND默认的查找器用于生成 CTRL-T 列表的命令fzf-file-widget()
FZF_CTRL_T_OPTS空使用 CTRL-T 时 fzf 的选项__fzf_defaults()
FZF_CTRL_R_OPTS空使用 CTRL-R 时 fzf 的选项__fzf_defaults()
FZF_ALT_C_COMMAND默认的查找器用于生成 ALT-C 列表的命令fzf-cd-widget()
FZF_ALT_C_OPTS空使用 ALT-C 时 fzf 的选项__fzf_defaults()
FZF_DEFAULT_OPTS_FILE空包含默认选项的文件的路径__fzf_defaults()

环境变量流程

来源： shell/key-bindings.bash8-12 shell/key-bindings.zsh8-12 shell/key-bindings.fish8-12 shell/completion.bash7-12 shell/completion.zsh7-12 shell/key-bindings.bash20-26 shell/key-bindings.zsh41-47 shell/key-bindings.fish32-40

示例配置

以下是一些自定义 fzf Shell 集成的实用示例

增强的 CTRL-T 文件预览

改进的 ALT-C 目录导航

支持剪贴板的自定义 CTRL-R

来源： README.md492-529 README.md912-936