herdr-file-viewer config.toml 配置完全参考:自定义编辑器、渲染器命令与 [keys] 键位重映射完整指南

原创2026-11-02 14:51:511,426 阅读

herdr-file-viewer config.toml 配置完全参考:自定义编辑器、渲染器命令与 [keys] 键位重映射完整指南

herdr-file-viewer 是一个 git 感知的只读终端文件查看器(TUI):左侧是带 git 状态标记的目录树,右侧按文件类型自动呈现 diff、渲染后的 Markdown 或高亮代码。它的 config.toml 配置文件是一个可选的 TOML 文件,让你自定义外部编辑器、Markdown/diff/语法渲染器命令、启动行为开关、树布局,甚至通过 [keys] 表重映射全部键位。本指南带你从零创建配置到逐项调优,附常见坑位说明。

herdr-file-viewer 文件查看器界面:左侧目录树带 git 状态标记,右侧 Cargo.toml 内容面板语法高亮显示

一、30 秒创建你的 config.toml 文件

herdr-file-viewer 把配置文件当作只读输入:它从不写入、没有应用内设置编辑器,改完配置后重启查看器即生效。文件缺失是完全正常的情况,所有键都会回退到内置默认值。

配置文件位置:

运行方式 路径
在 herdr 中运行 $HERDR_PLUGIN_CONFIG_DIR/config.toml(Linux 上为 ~/.config/herdr/plugins/config/herdr-file-viewer/config.toml)
独立运行(herdr 之外) ~/.config/herdr-file-viewer/config.toml(设置了 $XDG_CONFIG_HOME 时为 $XDG_CONFIG_HOME/herdr-file-viewer/config.toml)
Windows %USERPROFILE%\.config\herdr-file-viewer\config.toml

在 herdr 中运行 herdr plugin config-dir herdr-file-viewer 可随时打印当前应使用的目录。项目自带一份完整注释的 config.example.toml,每个设置都有说明,一键复制:

cp "$(herdr plugin list --json | jq -r '.result.plugins[]|select(.plugin_id=="herdr-file-viewer").plugin_root')/config.example.toml" \
   "$(herdr plugin config-dir herdr-file-viewer)/config.toml"

⚠️ 两个关键点:复制后必须重命名为 config.toml(查看器从不读 config.example.toml);示例文件里所有设置都是注释掉的,原样复制不改变任何行为,取消注释即生效。

改完随时按 ? 打开帮助浮层,Settings 标签会显示每个配置项最终生效的值。

二、优先级规则:配置 > 环境变量 > 默认值

配置键一旦设置永远获胜。只有两个键在"配置键"与"内置默认值"之间还有一层环境变量回退:

  • editor → 回退到 $EDITOR
  • update_check → 可用 $HERDR_FILE_VIEWER_NO_UPDATE_CHECK 关闭

其余所有键都是纯粹的 配置 > 默认值 两层关系。另有一个安全设计:配置文件路径必须能解析为绝对路径,否则会被拒绝(因为配置可以设置 editor 命令,属于受信任输入)。配置解析实现在 src/config.rs,若 TOML 写错语法或类型不对,整个文件被忽略、全部回退默认值,并在 ? 浮层的 Settings 标签中标记为畸形配置——查看器绝不会因为坏配置崩溃。

三、自定义外部命令:编辑器、渲染器与系统打开器

命令值会被像 shell 一样按空白拆分为参数(双引号可包住含空格的路径),但不会调用 shell。注意两种不同的 I/O 约定:

  • editor / open / reveal:查看器把目标路径追加为最后一个参数(reveal 是包含它的文件夹)。
  • markdown / diff / syntax:文件内容通过 stdin 管道传入(从不作为路径参数)。
# ~/.config/herdr-file-viewer/config.toml
editor = "code --wait"       # `e` 键使用的编辑器,覆盖 $EDITOR

markdown = "glow -s dark -w 0 -"                              # Markdown 渲染
diff = "delta"                                                  # diff 渲染
syntax = "bat --color=always --style=numbers --paging=never --file-name={name} -"

open = "xdg-open"        # `O` 键:用系统默认应用打开
reveal = "nautilus"      # `R` 键:在文件管理器中定位

渲染器最重要的一个细节:你设置的值会整体替换默认命令,参数不会合并。所以自定义命令必须自己读 stdin(glow 和 bat 需要结尾的 -)、自己设置颜色与格式参数。{name} 占位符会被替换为文件名(bat 用它选择语法)。三个默认渲染器是 glow(markdown)、delta(diff)、bat(语法),缺失任何一个时面板会优雅降级为纯文本并给出提示,不会崩溃。渲染器详情见 docs/renderers.md。

herdr-file-viewer 用 glow 渲染器显示 README.md 的 Markdown 效果:标题、列表与行内代码均带样式

一个已知限制:整文件 diff 视图的行号槽是通过给 diff 命令追加 delta 的 --line-numbers 参数得到的;如果你把 diff 指向一个不接受该参数的工具,整文件 diff 视图会退化为未渲染的纯 diff 文本。

四、启动行为开关一览

这些布尔/数值开关决定查看器启动时的状态(运行中仍可用对应按键切换):

键 默认 作用
hide_dotfiles false 启动时隐藏点号开头的隐藏文件(. 键仍可随时切换)
show_ignored false 启动时显示被 git 忽略的文件(相当于已按过 i 键)
compact_dirs false 把单链目录压成一行(src/main/java/br/com 而非 6 行),深路径/Java 项目值得开启
expand_changed false 自动展开有未提交变更的文件所在文件夹,新工作一眼可见
changed_only false 启动即进入"仅变更文件"树(相当于已按 c)
changed_file_view "diff" 变更文件的初始视图:"diff" 保持 diff 优先;"content" 按文件类型走常规策略(Markdown 渲染、代码高亮)
baseline 省略 初始 diff 基线:"base"(分支 merge-base 起的完整工作)或 "head"(仅工作区);省略则用上下文智能默认
update_check true false 禁用所有远程请求(版本更新与项目 spotlight)
confirm_discard true false 时退出/切换 worktree 直接丢弃会话批注,不再弹确认
scroll_lines 3 鼠标滚轮每事件滚动行数,1–10 的刻度:1 慢 · 3 中 · 6 快 · 10 极速

herdr-file-viewer 固定预览功能:左侧目录树、中间当前文件、右侧用 p 键固定的 Pinned 参考文件三栏并列

五、布局与预览上限:树宽度的"双键"陷阱

布局部分有两个键共同决定目录树启动宽度,规则是较小者获胜:

实际树宽 = min( tree_width 占比, tree_max_cols 列数 )
tree_width = 30        # 树列占 viewer 面板的百分比(20–80),内容面板占其余
tree_max_cols = 30     # 硬上限(按字符列数计),不是百分比
tree_position = "left" # 树在哪一侧:"left"(默认)或 "right"

💡 最常见困惑:你把 tree_width 调到 50 却发现树没变宽——那是 tree_max_cols 默认 30 列在上限封顶。把两个键一起调大(或把 tree_max_cols 设很高)才能真正加宽树。

open_direction 是唯一影响 herdr 面板本身的布局键:"right"(默认,查看器在右侧分屏)或 "down"("bottom" 同义)。它在"召唤"时读取,所以对下一个打开的查看器生效,不影响已打开的实例。

预览上限控制内容面板显示量,先到先触发,超出则显示截断预览并提示 ⚠ Truncated preview:

preview_max_lines = 10000   # 行数上限,100–100000
preview_max_kib = 1024      # 大小上限(KiB,1024 = 1 MB),64–65536

典型源码一般先触发行数上限;大小上限主要防护压缩/生成文件(bundle、大 JSON、日志)。注意 diff 另受 git 抓取步骤约 4 MB 的独立边界,调高 preview_max_kib 只加宽文件内容显示,不会加宽超大 diff。

herdr-file-viewer 全屏文件视图:z 键隐藏目录树后内容面板占满整个终端,适合长文阅读

六、[keys] 键位重映射:按"意图名"绑定

[keys] 表可以重映射任意全局键。每个条目以意图名(intent name,动作的稳定 snake_case id)为键,值是一个 key spec(单个字符串或字符串数组),整体替换该动作的默认键——想保留哪个键就列全哪个键。

[keys]
refresh = "g"              # `g` 刷新;默认的 `r` 从此失效
nav_up = ["w", "Up"]       # 一次绑定多个键(默认的 `k` 被移除)
switch_worktree = "F2"     # 命名键

常用重映射速查(意图名 → 默认键):

意图名 默认键 动作
nav_up / nav_down Up/k、Down/j 上移 / 下移树光标
activate Enter 展开目录或打开文件
expand / collapse Right/l、Left/h 展开 / 折叠目录
refresh r 重读 git 状态
open_in_editor e 交给外部编辑器
open_finder / project_search f / s 模糊找文件 / 项目内容搜索
open_fullscreen Z 全屏阅读当前文件
pin_preview p 固定当前预览作参考
show_help ? 打开帮助浮层
close q、Esc 关闭查看器

全部可重映射动作清单见 docs/configuration.md 的 Keybindings 一节(? 浮层的 Keybindings 标签也会实时显示,并标记你定制过的条目)。

可绑定的键:任意单个可打印/Shift 字符(g、<、{、?、大写字母各是独立按键),以及命名键 Tab、Enter、Esc、四方向键、Home、End、PageUp、PageDown、Space、Backspace、Delete、Insert、F1–F12(命名键不区分大小写)。没有 Ctrl/Alt 和弦——和弦永不触发动作,所以 Ctrl+C 等组合始终穿透终端。

安全与容错底线:

  • Esc 永远关闭查看器,无法被重绑走,任何配置都不会把你锁死;
  • 未知的意图名、不可绑定的键、两个动作抢同一键:只忽略那些条目(保留其默认值),其余照常,并在 Keybindings 标签中提示;
  • 抢占某默认键会让原动作显示为 (unbound),例如 refresh = "a" 会让 add_annotation 失去按键;
  • 模态内部(文件搜索弹窗、: / / 提示符、行选择模式、批注编辑器)的键是固定的,重映射全局键不影响它们。

七、配置完去哪里验证

  1. 重启查看器(无应用内热加载);
  2. 按 ? 打开帮助浮层:
    • Settings 标签:查看每个配置项的最终生效值,畸形文件会被明确标记;
    • Keybindings 标签:查看所有动作的当前绑定与定制标记。

更多细节请阅读官方文档:docs/configuration.md(完整配置参考)、docs/keys.md(全键位与鼠标参考)、docs/renderers.md(外部渲染器说明)。herdr-file-viewer 的配置体系设计克制而安全:读-only 输入、失败即回退默认值,放心大胆地定制你的文件查看器体验。

登录后查看全文
herdr-file-viewer