herdr-file-viewer config.toml 配置完全参考:自定义编辑器、渲染器命令与 [keys] 键位重映射完整指南
herdr-file-viewer config.toml 配置完全参考:自定义编辑器、渲染器命令与 [keys] 键位重映射完整指南
herdr-file-viewer 是一个 git 感知的只读终端文件查看器(TUI):左侧是带 git 状态标记的目录树,右侧按文件类型自动呈现 diff、渲染后的 Markdown 或高亮代码。它的 config.toml 配置文件是一个可选的 TOML 文件,让你自定义外部编辑器、Markdown/diff/语法渲染器命令、启动行为开关、树布局,甚至通过 [keys] 表重映射全部键位。本指南带你从零创建配置到逐项调优,附常见坑位说明。
一、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→ 回退到$EDITORupdate_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。
一个已知限制:整文件 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 极速 |
五、布局与预览上限:树宽度的"双键"陷阱
布局部分有两个键共同决定目录树启动宽度,规则是较小者获胜:
实际树宽 = 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。
六、[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失去按键; - 模态内部(文件搜索弹窗、
://提示符、行选择模式、批注编辑器)的键是固定的,重映射全局键不影响它们。
七、配置完去哪里验证
- 重启查看器(无应用内热加载);
- 按
?打开帮助浮层:- Settings 标签:查看每个配置项的最终生效值,畸形文件会被明确标记;
- Keybindings 标签:查看所有动作的当前绑定与定制标记。
更多细节请阅读官方文档:docs/configuration.md(完整配置参考)、docs/keys.md(全键位与鼠标参考)、docs/renderers.md(外部渲染器说明)。herdr-file-viewer 的配置体系设计克制而安全:读-only 输入、失败即回退默认值,放心大胆地定制你的文件查看器体验。



