企业官网建设流程全解析

Atuin 基础使用指南：理解命令记录、上手 TUI 检索与常用配置调优

【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin

本文是 Atuin 的基础使用指南，围绕官方文档 basic-usage.md 展开，讲解 Atuin 会记录哪些数据、如何用上方向键与ctrl-r打开交互式搜索界面（TUI），以及enter_accept、inline_height、style、tmux 弹窗等最常用的配置项。读完本文，你将掌握 Atuin 的日常操作流，并能够根据个人习惯完成从"回车即执行"到"tmux 浮动弹窗搜索"的整套基础调优。

Atuin 会记录什么

在使用过程中，Atuin 为每一条命令记录六类元数据，这也是后续检索、统计与同步的基础：

1. 你运行的命令本身（command）
2. 运行命令的目录（cwd）
3. 运行时间与耗时（timestamp 与 duration）
4. 命令的退出码（exit code）
5. 运行机器的主机名与用户（hostname + user）
6. 运行命令的 shell 会话（session）

从源码结构看，这些记录的捕获与持久化逻辑位于 crates/atuin-client/src/history/ 下的 capture 与 store 模块，本地存储由 SQLite 数据库承担（默认位于~/.local/share/atuin/history.db）。记录时还会携带退出码等会话上下文，为后续的统计（atuin stats）、同步（sync）以及按会话过滤提供原始数据。

围绕"记录什么"这个话题，有几个关联配置值得了解：

• store_failed（默认true）：是否记录执行失败（退出码非 0）的命令；
• history_filter：通过正则表达式把特定命令排除在历史记录之外（如^secret-cmd）；
• cwd_filter：通过正则表达式把特定目录下运行的所有命令排除在记录之外，修改后可用 prune 命令 清理旧记录；
• secrets_filter（默认true）：内置一组正则，匹配到 AWS、GitHub、Slack、Stripe、npm 等服务的令牌格式时拒绝保存，同时对捕获的命令输出做脱敏替换。

具体参数说明见 config.md，排除命令的更多玩法见 Excluding Commands from History。

打开并使用 TUI

安装并完成 shell 集成（atuin init）后，你可以在任意时刻用默认按键打开交互式搜索界面（TUI）：

• 上方向键（↑）
• ctrl-r

进入 TUI 后，两个最基础的操作是：

• 按Enter：立即执行当前选中的命令；
• 按Tab：把当前选中的命令回填到 shell 提示符中，供你继续编辑后再执行。

这两个行为的差异在按键映射源码中体现得很直接：在 crates/atuin/src/command/client/search/keybindings/defaults.rs 中，tab始终绑定为ReturnSelection（只回填不执行），而enter的行为则由enter_accept配置决定——为true时绑定Accept（直接执行），为false时绑定ReturnSelection（回填待编辑）。

在 TUI 中缩小搜索范围：Filter Mode

搜索过程中，按ctrl-r可以循环切换过滤模式（filter mode），从而决定 Atuin 在哪些范围内搜索：

其中workspace模式要求配置workspaces = true（见 config.md 的workspaces一节），并且当你不在 git 仓库内时，Atuin 会自动跳过该模式。如果你希望搜索默认从某个模式开始，可以设置filter_mode；如果想从ctrl-r的循环列表中移除某些模式，可以配置search.filters；还可以让上方向键与ctrl-r使用不同的默认模式，对应配置项是filter_mode_shell_up_key_binding。

交互式搜索的更多用法

• 搜索模式：按ctrl-s可在fuzzy（默认，模糊匹配）、prefix（前缀匹配）、fulltext（全文包含）、daemon-fuzzy（基于守护进程内存索引的可调评分模糊搜索）之间循环，默认模式由search_mode配置决定；
• Inspector：按ctrl-o打开选中命令的检查器，可查看 Runs（该命令的历史执行记录）、Session（该次运行所在的会话）、Stats（统计信息）等；
• 前缀模式：以ctrl-a作为前缀键的两段式快捷键，例如ctrl-a然后d删除选中条目，ctrl-a然后c切换到当前选中命令的上下文会话。

更完整的 TUI 快捷键表与自定义方法见 key-binding.md，高级用法见 advanced-usage.md。

常用配置修改

Atuin 的默认配置文件位于~/.config/atuin/config.toml（可通过环境变量ATUIN_CONFIG_DIR覆盖配置目录），数据默认存储在~/.local/share/atuin。完整的配置项参考见 config.md。

一个省事的办法是执行atuin default-config，它会直接把一份带详尽注释的示例配置打印到终端——该命令的实现位于 crates/atuin/src/command/client/default_config.rs，其内容来自客户端示例配置 crates/atuin-client/config.toml，里面几乎每个配置项都标注了默认值与可选范围。你可以用

atuin default-config > ~/.config/atuin/config.toml

生成一份初始配置再按需修改。

按键绑定

Atuin 默认绑定了上方向键与ctrl-r，如果你不喜欢，可以在调用atuin init时按需关闭：

# 以 zsh 为例：只绑定 ctrl-r，不绑定上方向键 eval "$(atuin init zsh --disable-up-arrow)" # 只绑定上方向键，不绑定 ctrl-r eval "$(atuin init zsh --disable-ctrl-r)" # 两个都不绑定 eval "$(atuin init zsh --disable-up-arrow --disable-ctrl-r)"

也可以在调用atuin init之前设置环境变量ATUIN_NOBIND（任意值）来完全跳过默认绑定，然后自行绑定。例如 zsh 中可以绑定 ZLE widgetatuin-search与atuin-up-search：

export ATUIN_NOBIND="true" eval "$(atuin init zsh)" bindkey '^r' atuin-search bindkey '^[[A' atuin-up-search bindkey '^[OA' atuin-up-search

一个常用技巧是给上方向键单独指定过滤模式，例如"按上方向键只搜当前目录，按 ctrl-r 全局搜"：

filter_mode_shell_up_key_binding = "directory" # 或 global、host、session 等

各 shell（zsh、bash、fish、nu）的完整自定义绑定示例见 key-binding.md。

Enter 即执行

Atuin 的默认行为是：按 Enter 直接执行选中的命令。如果你更希望 Enter 与 Tab 一样，总是先把命令回填到提示符供编辑，可以在配置文件中设置：

enter_accept = false

值得说明的是：配置文档中enter_accept的"默认值"存在历史差异——官方在默认配置文件中写入了enter_accept = true（新用户默认回车即执行），但对老用户保持false（回填待编辑），后续版本可能统一。实际行为在源码 crates/atuin/src/command/client/search/keybindings/defaults.rs 的accept_action函数中体现，并有对应的按键映射单测覆盖。此外，command_chaining = true可以配合&&/||实现"接续上一条命令"的链式搜索。

内联窗口（Inline Window）

如果觉得全屏 TUI 太大、太有压迫感，可以通过inline_height限制界面最多占用的行数：

# 搜索窗口的高度（行数） inline_height = 40

• 设为0表示总是使用尽可能多的行（即全屏）；
• 针对上方向键触发的搜索，还有独立的inline_height_shell_up_key_binding可以单独设置。

你可能还会喜欢更紧凑的 UI 模式：

style = "compact"

style支持三个取值：compact（紧凑）、full（完整）与auto——auto默认按full渲染，但当终端窗口高度不足以完整显示时自动切换到compact。与窗口大小相关的还有：

• invert = true：反转 UI，把搜索框放到顶部；
• auto_hide_height = 8：在可用高度低于该行数时自动隐藏多余 UI 行（仅对compact样式生效，设为0可完全关闭）；
• show_preview/max_preview_height：控制选中命令的预览与最大预览高度。

tmux 弹窗

如果你使用 tmux，Atuin 可以不在当前窗格上直接绘制，而是把搜索界面放进一个浮动弹窗中：

[tmux] enabled = true

弹窗的尺寸可通过width（默认"80%"，支持百分比或绝对列数）与height（默认"60%"）调整：

[tmux] enabled = true width = "80%" height = "60%"

使用弹窗需要满足以下条件（不满足时 Atuin 会无报错地回退到普通渲染）：

• tmux >= 3.2（display-popup从该版本起具备 Atuin 所需的行为）；
• 使用zsh、bash 或 fish（nushell、xonsh、PowerShell 暂不支持弹窗）。

⚠️ 特别注意：如果你使用iTerm2 的原生 tmux 集成（control mode，即tmux -CC），它无法显示 tmux popup，且 Atuin 无法自动检测并回退。这种情况下请保持[tmux] enabled = false（默认值），让搜索界面以内联方式渲染。

另外两点实践提示：这些设置由atuin init读取并通过环境变量传给 shell 插件，因此修改后需要重启 shell才能生效；如果只想在某个会话临时关闭弹窗而不改动配置，可在 Atuin 按键绑定运行前设置ATUIN_TMUX_POPUP=false。

配置与实现的源码速览

如果你想进一步理解上面的配置项在代码层面如何落地，可以从这几个文件入手：

• 配置结构与枚举定义：crates/atuin-client/src/settings.rs 定义了FilterMode（global/host/session/directory/workspace/session-preload）、SearchMode（prefix/fulltext/fuzzy/daemon-fuzzy）、Style、KeymapMode、ExitMode等核心枚举，以及完整的Settings结构；
• 带注释的示例配置：crates/atuin-client/config.toml 是atuin default-config输出的来源，每个配置项都附有默认值与取值范围说明；
• 默认按键映射：crates/atuin/src/command/client/search/keybindings/defaults.rs 通过KeymapSet::defaults构建 emacs、vim-normal、vim-insert、inspector、prefix 五套默认键位，并附带大量rstest单测验证enter_accept、ctrl_n_shortcuts、keys.prefix、scroll_exits等配置对按键行为的实际影响。

掌握了以上基础用法与配置项之后，建议继续阅读 advanced-usage.md（过滤模式、搜索模式、上下文切换）、key-binding.md（完整的 TUI 快捷键表与自定义绑定）以及 config.md（全部配置参数详解），从而把 Atuin 调教成完全符合个人习惯的历史检索工具。

【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin