企业官网建设流程全解析

如何用 qmd collection update-cmd 配置重建索引前自动执行的更新命令

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd

当你的 qmd collection 指向一个 git 仓库、同步脚本或其他会持续变化的上游目录时，手动先git pull再qmd update容易漏步骤，导致索引里一直是旧内容。qmd 为每个 collection 内置了一个刷新钩子：配置后每次执行qmd update，会先在该 collection 的目录里运行你指定的 bash 命令，再重新索引。本文以qmd collection update-cmd为主线，给出配置、验证、运行和清除的完整路径。

前提条件

• 已安装 qmd（npm install -g @tobilu/qmd或bun install -g @tobilu/qmd）。系统要求为 Node.js >= 22、Bun >= 1.0.0，macOS 上还需 Homebrew 的 SQLite（brew install sqlite）。
• 目标 collection 已经存在。update-cmd作用于已有 collection，若 collection 不存在，命令会报Collection not found: <name>并退出（见 src/cli/qmd.ts）。先用qmd collection list确认名字，不存在则先创建：

qmd collection add ~/reference/wiki --name wiki --mask "**/*.md"

用 update-cmd 设置重建索引前执行的命令

命令格式为qmd collection update-cmd <name> [command]，command 是一条 bash 命令：

# 设置：每次 qmd update 前对该 collection 先执行 git pull qmd collection update-cmd wiki 'git pull --ff-only' # 清除：省略 command 参数即可 qmd collection update-cmd wiki

设置成功后终端会回显（src/cli/qmd.ts 中的实际输出格式）：

✓ Set update command for 'wiki': git pull --ff-only

文档中给出的示例命令包括git pull --rebase、git pull --ff-only（见 README.md）以及带本地改动的变体git stash && git pull --rebase --ff-only && git stash pop（见 example-index.yml 与 CHANGELOG.md）。由于这条命令会在每次qmd update时以bash -c自动执行，选择命令时要注意它会真实操作该目录——例如git pull会改动工作区文件，带git stash的变体则会 stash/恢复本地改动，按你目录的实际状态选用。

验证配置已生效

配置写入的字段是 collection 配置中的update，README 的配置表中说明：collections.<name>.update是 "Bash command run beforeqmd updatere-indexes this collection. Set viaqmd collection update-cmd"。两种确认方式：

1. 用qmd collection show查看，配置后会多出一行Update:：

qmd collection show wiki

输出中对应字段（src/cli/qmd.ts）：

Update: git pull --ff-only

2. 直接查看配置文件。该命令读写的是单一 YAML 配置，默认位置~/.config/qmd/index.yml（遵循XDG_CONFIG_HOME和QMD_CONFIG_DIR；qmd init创建的项目本地索引则在.qmd/index.yml）：

collections: wiki: path: ~/reference/wiki update: "git pull --ff-only"

仓库中带注释的完整模板见 example-index.yml，其中wiki与codex两个条目分别演示了自动更新配置。README 建议用 CLI 设置或清除，而不是手改 YAML；手改同样有效（配置在下一条命令时生效），但 CLI 方式会顺带刷新信任记录（见下文限制一节）。

运行 qmd update，观察钩子先执行

配置完成后直接运行qmd update。README "Automatic update commands" 一节给出的运行示例如下（文档示例，实际数值取决于你的 collection）：

$ qmd update [1/3] wiki (**/*.md) Running update command: git pull --ff-only Already up to date. Collection: ~/reference/wiki (**/*.md) Indexed: 0 new, 2 updated, 340 unchanged, 0 removed

判断依据：出现Running update command: <你的命令>及其输出（如Already up to date.），随后进入该 collection 的Indexed: ...统计，说明钩子在重新索引之前执行完毕。README 对该机制的说明是：这个update字段是 QMD 的内置刷新钩子，qmd update时先跑该命令再重建索引，从而让 collection 与上游来源（git 远端、同步脚本）保持同步，而无需自己包一层脚本。

行为边界与限制

• 工作目录：命令通过bash -c在 collection 自己的目录（其path）中运行，而不是你执行qmd update时的当前目录。写相对路径或相对 git 操作时按这个前提理解。
• 非零退出会中止整轮：如果某个 collection 的 update 命令退出码非零，qmd update会打印失败并中止整轮运行——排在它后面的 collection 不会被重新索引。排查时先单独在对应目录手动执行该命令确认能否成功。
• 项目内检入的 .qmd 配置不受默认信任：如果update命令来自随git clone传播的项目本地.qmd/index.yml，它属于被门控的字段（QMD 视为"别人的 shell 脚本"）：在终端执行qmd update时会列出这些字段并询问，批准会记录到~/.config/qmd/trusted.json；没有终端可询问的场景（agent、CI、MCP）中这些字段会被跳过。相关命令为qmd trust、qmd trust list、qmd trust revoke；CI 中可用QMD_TRUST_LOCAL_CONFIG=1（或QMD_TRUST_UPDATE_HOOKS=1）放行。审批只覆盖你当时看到的字段集——修改命令内容会再次询问。你自己~/.config/qmd/*.yml中的内容（包括update-cmd写入的）不受门控。

恢复原状

不再需要钩子时，用不带 command 的形式清除：

qmd collection update-cmd wiki

输出✓ Cleared update command for 'wiki'，此后qmd update只重建索引，不再执行任何前置命令。也可以用qmd collection show wiki确认Update:一行已消失。

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd