islandiguana

使用 islandiguana 搜索 Obsidian 知识库

islandiguana 使用 yq 表达式语法，根据 YAML front matter 递归搜索 Markdown 文件。

二进制文件：/Users/mtm/go/bin/islandiguana

知识库路径：/Users/mtm/Documents/Obsidian Vault

基本用法

# find files where tags include "python"
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.tags[] == "python"'

# find files where status is draft
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.status == "draft"'

# find files that have a specific front matter key (any value)
islandiguana "/Users/mtm/Documents/Obsidian Vault" 'has("filetype")'

# find files with no author set
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.author == null'

# find markdown files with no front matter (or front matter but no tags)
islandiguana "/Users/mtm/Documents/Obsidian Vault" '(.tags // []) | length == 0'

# find files whose title matches a regex (case-insensitive)
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.title | test("(?i)kubernetes")'

# find files tagged with either "python" or "ruby"
islandiguana "/Users/mtm/Documents/Obsidian Vault" '(.tags[] == "python") or (.tags[] == "ruby")'

# find files with a priority field greater than 3
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.priority > 3'

# limit search depth
islandiguana --max-depth 1 "/Users/mtm/Documents/Obsidian Vault" '.tags[] == "python"'

与 ripgrep 结合使用（stdin 模式）

未提供目录参数时，islandiguana 会从 stdin 读取文件路径。 同时提供目录参数并通过管道传入 stdin 时，会合并并去重这两个来源。

# filter by front matter among files matching a text search
rg -l "Expresso" "/Users/mtm/Documents/Obsidian Vault" | islandiguana '.tags[] == "coffee"'

# combine ripgrep results with a full vault walk (merged, deduplicated)
rg -l "Expresso" "/Users/mtm/Documents/Obsidian Vault" --null | islandiguana "/Users/mtm/Documents/Obsidian Vault" --null-input '.tags[] == "coffee"'

就地修改 front matter

使用 --mutate 和 yq 表达式编辑匹配的文件：

# delete a front matter key from matched files
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.filetype == "product"' --mutate 'del(.filetype)'

# update a field on matched files
islandiguana "/Users/mtm/Documents/Obsidian Vault" '.status == "draft"' --mutate '.status = "published"'

# append a tag idempotently (creates frontmatter if the file has none)
islandiguana "/Users/mtm/Documents/Obsidian Vault" --mutate '.tags = ((.tags // []) + ["mytag"] | unique)'

# tag all notes mentioning a term — stdin only (ripgrep finds files, islandiguana tags them)
rg -l 'some-term' "/Users/mtm/Documents/Obsidian Vault" --null | islandiguana --null-input --mutate '.tags = ((.tags // []) + ["some-term"] | unique)'

输出选项

# null-delimited output for safe piping to xargs
islandiguana -0 "/Users/mtm/Documents/Obsidian Vault" '.tags[] == "python"' | xargs -0 grep -l TODO

# skip the disk cache (always parse fresh)
islandiguana --no-cache "/Users/mtm/Documents/Obsidian Vault" '.priority > 3'

工作流

要回答有关知识库内容的问题，请通过 Bash 运行 islandiguana，然后读取它返回的文件。

务必给知识库路径加上引号——其中包含空格。

查询请使用 yq 表达式语法。 表达式始终是最后一个位置参数（在可选目录之后）。

与 ripgrep 结合使用

按主题搜索时，将 ripgrep 用于自由文本搜索，并将 islandiguana 用于 front matter 标签筛选，让标签充当缩小范围的筛选层。

笔记经常会顺带提到某个主题——产品笔记中可能包含 ## [[Chef's Store]] 这样的章节——这会干扰仅搜索文本的结果。标签能表明笔记的用途，因此按标签筛选可以去除这些噪声。

查找正文中提到某内容但未标记为 product 的笔记：

rg -l -i "search term" "/Users/mtm/Documents/Obsidian Vault" | islandiguana '(.tags // []) | map(. == "product") | any | not'

务必先将缺失的标签默认设为空数组。直接使用 not (.tags[] == "product") 时，tags 为 null 或不存在的文件会导致失败，因此排除标签时请使用 (.tags // []) | map | any | not 这一惯用写法。