Annex Gallery

Turn git-annex-managed image folders into a gallery. Annex Gallery lays a folder out as a card wall — one card per image, with cover, name and key metadata side by side, filterable by sample, date or parameter.

A card gets its cover from a thumbnail: the plugin generates thumbnails and sidecar Markdown metadata for images (.tif .tiff .png .jpg .jpeg .bmp .webp). For other formats, supply a same-name thumbnail and point the sidecar's thumbnail field at it.

The vault remains an ordinary git + git-annex repository. Use the file explorer context menu to run Add / Get / Drop / Lock / Unlock on annex largefiles, and watch the status bar for uncommitted, untracked and annex-missing files. Metadata is extracted from file names through configurable metadata presets.

Installation

• Obsidian 1.14.4+, desktop only (uses Node / Electron APIs).
• git and git-annex must be installed and on PATH.
• Install from the community plugin directory (search Annex Gallery), add this repository with BRAT, or copy main.js / manifest.json / styles.css from a release into <vault>/.obsidian/plugins/annex-gallery/.

All plugin-authored UI text is English-only until bilingual UI (i18n) support exists; this covers settings, notices, modals, status text, progress/results, errors, hints and shipped preset display text.

To start, run Initialize gallery from the command palette. It turns the current vault root into a git + git-annex repository and repairs missing steps in an existing one.

Disclosures

• External programs. The plugin runs your local git and git-annex binaries as subprocesses. It does not bundle them.
• Files outside the vault. It reads your system git configuration and the SSH/GPG credentials git-annex uses to reach remotes. The annex object store lives under the vault's .git/annex.
• Network. The plugin makes no network requests of its own. Traffic happens only when you run an annex operation such as Get or Drop and git-annex contacts the remotes you configured.
• No telemetry. There is no analytics, tracking or remote logging.

Why direct filesystem access and subprocess execution

Obsidian's vault API does not expose a git + git-annex repository, and thumbnails must exist as real files next to their sources. The plugin therefore uses Node's fs and child_process directly, but only for three bounded jobs:

• Repository state. It reads and merges the vault repository's own .gitattributes / .gitignore, and runs annex actions through the local git and git-annex binaries. Every command is anchored with git -C <vault folder>.
• Thumbnails and sidecars. It walks the gallery folder you invoked and writes <stem>.thumbnail.png and <stem>.md beside the source image.
• Registered files. It reads the metadata preset, body-template and gallery-template files you registered; their paths are validated as vault-relative, and absolute paths or .. are rejected.

External programs invoked: git, git-annex (through git annex), and ImageMagick 7 (magick, for thumbnails and image dimensions). Commands are passed as argument arrays and never through a shell. No files outside the vault are read or written, apart from the system git configuration and the SSH/GPG credentials that git / git-annex use for the remotes you configure, plus existence checks for the magick binary in Homebrew's standard locations. The bundled CLI (scripts/cli.ts, built to tools/annex-gallery.mjs) reads and writes only the directories and preset / template files you pass on its command line.

License

MIT — see LICENSE.

中文说明

一眼看到，而不是一层层点进去找。 Annex Gallery 把 git + git-annex 管的目录平铺成一面卡片墙： 一份数据一张卡，封面、名称与关键元数据并排铺开，按样品、日期、参数一筛就只剩你关心的那几张。

卡片有没有封面，取决于有没有缩略图：图片（.tif .tiff .png .jpg .jpeg .bmp .webp） 由插件直接生成缩略图与 sidecar；其他格式 —— Obsidian 打不开、也解析不了的那些 —— 你放一张同名缩略图、 把 sidecar 的 thumbnail 指向它，它就和图片一样出现在墙上。

墙底下仍然是那个 git + git-annex 仓库：右键对 annex 的大文件做 Add / Get / Drop / Lock / Unlock， 状态栏常驻显示 Uncommitted / Untracked / Annex-missing largefiles 的数目，元数据由 metadata preset 从文件名里抽（任意命名约定都只改配置）。 数据层一个字都不新造 —— 你在终端里 git annex 能做的事，装上插件之后照样能做。

安装

• Obsidian 1.14.4+，仅桌面版（用到 Node / Electron API）。
• 本机要有 git 与 git-annex（插件通过子进程调它们）。
• 安装方式：社区插件目录搜索 Annex Gallery；或用 BRAT 添加本仓库；或从 release 下载 main.js / manifest.json / styles.css 放进 <vault>/.obsidian/plugins/annex-gallery/。

插件界面文案当前仅英文（设置页、Notice、弹窗、状态栏、进度/结果、错误与提示都算），等中英双语支持落地后再恢复本地化。

首次使用：打开你的数据 vault → 命令面板跑 Initialize gallery → 插件把当前 vault 根整理成一个 git + git-annex 仓库（已经是仓库的不会重建，只补缺的步骤）。

用法速查

配置从哪来

插件的运行时只认 vault 里的文件，没有内置兜底：

• metadata preset：一条一个 .json（顶层是一条 ParseProfile 对象：正则 + frontmatter 字典 + 可选的正文模板）， 在设置页登记 vault 相对路径；
• gallery template：vault 里的 .base，同样在设置页登记；
• git 远端：.git/config 是 git remote 的唯一真相。设置页打开时从 git 读 remote，编辑只留内存，点 Save 才写回（新增 / 改地址 / 改 push URL / 改名 / 删除）；多 URL remote 与 git-annex special remote 在插件里只读。special remote 的 type 在 git-annex 分支的 remote.log（插件本地只读 git show git-annex:remote.log），参数如 annex-directory 在 .git/config；两者都是只读展示，用终端的 git remote / git annex initremote 管理。插件不 fetch、不 push。
• 设置页的「Create from preset…」会把内置素材写成独立文件（AnnexGalleryTemplates/<id>.<ext>，文件夹名无空格）—— metadata preset 一次写出预设 JSON + 正文 .md 两份，正文路径写进预设的 template 字段； 同名再加序号，不覆盖、不自动打开；「打开」交给系统默认应用编辑；「删除」只取消登记、文件留着。

改完文件直接生效 —— 每次生成都重新读外部文件；文件坏了会在写盘前停下并指名是哪一个。 旧版本内联在 data.json 里的 profile、旧格式的预设文件、旧的 metadata 模板登记表都只显示一条失效提示， 不读取、不迁移；重建办法见 docs/metadata.md。

开发入门

命令

npm install
npm run dev        # esbuild watch → main.js（开发时用）
npm run build      # 生产构建：main.js + tools/annex-gallery.mjs
npm run typecheck  # tsc --noEmit
npm test           # 数据安全：真 annex 仓库上的多场景集成测试
npm run smoke      # 桩环境加载构建产物：能否启用、入口形状、设置页
npm run layout     # 设置页布局（真实 app.css + headless Chromium）

完整的判据清单（哪条命令钉住什么）见 docs/tools/。

仓库结构

main.ts            插件入口：命令、状态栏、9 个右键菜单项、设置页接线
src/core/          核心逻辑（不依赖 Obsidian，插件与 CLI 共用）
                   init · rules · thumbnails · sidecar · gallery · templates · external-files · profile-files · profiles · placeholders · presets · stems · annex · git · status · remotes
src/ui/            设置页、metadata preset 编辑器、gallery template 编辑器、remotes 编辑器
src/defaults/      内置规则文件与预设素材（.gitattributes / .gitignore / presets / base）
tools/             判据（桩层 / 真仓库层 / 真机层）、示例语料
scripts/           CLI 源码（构建产物仍是 tools/annex-gallery.mjs）
tests/             数据安全测试（npm test）
docs/              设计与口径文档（见下）

构建产物与部署

• npm run build 产出 main.js 与 tools/annex-gallery.mjs，两者都不入库。
• 插件的三份发行物是 main.js / manifest.json / styles.css；装到 vault = 拷进 <vault>/.obsidian/plugins/annex-gallery/，然后在 Obsidian 里重载插件。
• manifest.json 的 version 必须与 release 的 tag 逐字相等。

改动前先读哪一份

文档导航

许可

MIT