gg

让 man 文档为你而生长

gg 是一个像 man 一样的个人命令笔记查询工具。

把 Linux 命令笔记按 Markdown 存在本地目录，用 gg <命令> 直接在终端渲染； 查不到时可以交给 AI 生成一份并保存。

# 安装到系统（推荐）
cargo install --path . --force

# 或只构建发布二进制
cargo build --release      # target/release/gg

# 1) 建立笔记目录
mkdir -p ~/.config/gg/notes

# 2) 写一份笔记：文件名即命令名
cat > ~/.config/gg/notes/ls.md <<'EOF'
`ls`：显示目录中的文件及其属性信息。

- `-a`, `--all`：显示所有文件，包括隐藏文件
- `-l`：以长格式显示详细信息
EOF

# 3) 查询
gg ls

笔记目录里的 ls.md 对应 gg ls。

gg ls                    # 查询 ls 的笔记
gg list                  # 列出全部笔记（终端下多列显示）
gg search grep           # 按文件名搜索
gg search -c 递归        # 按正文搜索，输出 `文件:行号: 内容`（内容取原文，保留缩进）
gg -b ls                 # 在浏览器中打开
gg -e ls                 # 用编辑器打开
gg rm ls                 # 删除（默认否定，回车 = 不删）
gg rm ls grep            # 一次删多个
gg show rm               # 显式查询（用于被同名子命令占用的命令名）

-b 与 -e 只修饰查询动作（gg <命令> 与 gg show <命令>），两者互斥： 同时给出、或用在 list / search / rm 上，都按用法错误退出（2），而不是静默 忽略其中一个。不带任何动作时（gg -b）照常打印帮助。

--set-editor 与 --lang 只写配置，不会吞掉同一次调用里的子命令： gg --lang en list 会先保存语言，再按英文列出笔记；单独使用（gg --lang en） 则只保存配置并确认。两者同时给出时按 --lang → --set-editor 的顺序应用， 因此两条确认信息都使用本次要求的语言。

--set-editor 的取值定位不到可执行文件时会当场提示，但仍会保存：运行时 会回退到环境变量或系统默认编辑器，所以「先设好、稍后再装」依然可用；提示只是 让拼写错误立刻暴露。纯空白取值表示清除编辑器配置。

优先级：--notes-dir > GG_NOTES_DIR > 系统配置目录下 gg/notes。

配置文件：Linux/macOS 为 ~/.config/gg/config.toml，Windows 为 %APPDATA%\gg\config.toml。

language = "zh"           # 显示语言
editor = "hx"             # 默认编辑器，支持带参数，如 "code -w"

ask_before_ai = true      # 调用 AI 前询问
auto_save_ai = true       # AI 生成后落盘
ask_before_save = false   # 落盘前再问一次
ai_provider = "claude"    # claude / codex / gemini / none
# ai_command = "llm -m gpt-4o"   # 自定义 AI 命令行，优先级高于 ai_provider
ai_note_language = "zh-CN"
ai_timeout_seconds = 180  # AI 最长等待秒数，0 表示不限制

取值写错会在启动时直接报错并指出问题所在，不会静默降级。

未命中时不直接调用 AI，而是先检查后端是否可用，再询问：

$ gg rsyns
未找到命令 `rsyns`，推荐:
rsync
$ gg rsync
⠹ 正在生成 `rsync` 的笔记 [3s]
已保存笔记: ~/.config/gg/notes/rsync.md
用 `gg rsync` 查看

需要别的形态就用 ai_command，提示词默认追加为最后一个参数：

ai_command = "llm -m gpt-4o"
ai_command = "my-tool --flag {prompt}"    # 或用 {prompt} 指定位置

# Windows 路径含反斜杠，用 TOML 字面量字符串（单引号）免转义：
# ai_command = 'C:\Tools\my-tool.exe --flag'

提示词内置在程序里；在配置目录放一份 AGENTS.md 即可整体替换（文件不存在或内容只有空白时用内置默认）：

文件里可用 {{command}}（命令名）与 {{language}}（输出语言）两个占位符：

为命令 `{{command}}` 输出一份简易的 Markdown 速查笔记。
先给一个可运行的示例代码块，再列 2~4 个最高频选项。输出语言 {{language}}。

非交互终端不会静默调用 AI：gg foo | less 或 gg foo > out.md 这类场景 没有用户可确认，会跳过 AI 并返回退出码 3。脚本里需要自动化就显式加 -y， 或把 ask_before_ai 设为 false。

1 与 2 的分界不是「谁报的错」，而是错误来自哪里：命令行本身用错（含 gg 自己对参数取值的校验）是 2；命令行没问题、只是操作失败才是 1。因此 --lang jp 是 2，而配置文件里的 language = "jp" 是 1。

退出码 3 的原因写在 stderr（stdout 保持干净，便于管道与重定向）：查询未命中会 附带相近命令名，search 未命中会区分是名称还是正文。

• 仅支持「单词命令名」，不能含空格，也不能含 /、\、:
• 仅识别 .md 笔记文件
• list、search、rm、show、help 是子命令名，不能作为普通查询命令名直接使用； 被占用的名字（典型是 rm）可以用 gg show <命令> 查询
• gg rm 不可逆，非交互终端需显式 -y；若笔记目录在 git 仓库内会提示找回方式
• gg search 的关键词不能为空（含只由空白组成），否则按用法错误退出（2）
• 帮助信息与全部运行时提示均已本地化；但命令行用法错误（缺参数、未知选项等） 由 clap 生成，目前仍为英文

MIT，见 LICENSE。