Tolaria 非 Git 库支持设计解析：ADR-0085 如何让普通 Markdown 文件夹直接可用

Tolaria 非 Git 库支持设计解析：ADR-0085 如何让普通 Markdown 文件夹直接可用

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

本文围绕 Tolaria 仓库中的架构决策记录 ADR-0085 展开，讲解"非 Git 库（non-git vault）作为受支持状态而非错误状态"这一设计如何取代早期"强制 Git"策略，并结合useGitSetupState状态机、init_git_repo后端命令与冒烟测试，说明用户从打开普通文件夹到事后启用 Git 的完整技术链路。读完后你将理解 Tolaria 的 Git 能力是如何按"每个库各自的状态"做功能门控的，以及初始化 Git 时后端实际执行了哪些安全校验与提交步骤。

从"硬前置条件"到"受支持状态"：ADR-0085 的产生背景

ADR-0085 的 frontmatter 声明了它的基本身份：

type: ADR id: "0085" title: "Non-git vaults open with explicit later Git initialization" status: active date: 2026-04-26 supersedes: "0034"

它明确取代了 ADR-0034。ADR-0034 曾把 Git 设为打开库的硬前置条件：当时 Git 支撑的缓存、历史、变更与同步流程在用户打开"纯 Markdown 文件夹"时会静默失败——缓存算不出 commit hash、Pulse/Changes 面板为空、commit/push 命令报错，且这些失败对用户不可见。ADR-0034 的做法是：当库目录下没有.git时，用一个阻塞式模态框阻止一切使用，直到用户一键初始化 Git 仓库或换一个库；检查由轻量的is_git_repoTauri 命令完成（只检查.git是否存在，不校验 remote 或提交历史），浏览器/开发模式下该检查直接跳过。

这种保护 Git 功能的做法挡住了最常见的采用路径：从 Obsidian、iCloud、Dropbox 或手工维护的笔记目录中打开一个现有文件夹。ADR-0085 因此反转了默认值——浏览和编辑 Markdown 应当立即可用，Git 只是用户可以显式开启的能力（用于历史、同步、提交或协作）。

核心决策：非 Git 库是受支持状态，不是错误状态

ADR-0085 的决策原文可以归纳为三层行为约定：

1. 即使不是 Git 仓库，也打开现有 Markdown 文件夹。打开时 Tolaria 会询问是否初始化 Git；如果用户关闭提示，应用继续正常工作，状态栏会持续显示Git disabled警告。
2. 重新进入设置的两个入口：点击该警告，或从命令面板执行Initialize Git for Current Vault，都能重新打开初始化动作。
3. 库处于非 Git 状态期间的能力边界：
   • Git 历史、变更、提交、同步、冲突与 remote 相关操作被隐藏或禁用；
   • 后台自动同步（Auto-sync）和 AutoGit 检查点不再运行；
   • Markdown 扫描、笔记浏览、笔记编辑、搜索以及其他非 Git 功能照常工作。

ADR 同时强调：init_git_repo是事后启用 Git 的唯一后端命令——它创建仓库、写入 Tolaria 的默认.gitignore、暂存整个库，并创建一个无签名的初始化提交。

ADR 还列出了被否决的两个替代方案，理解它们能看清设计权衡：

• Option A（采纳）：受支持的非 Git 模式 + 显式事后初始化。采用路径最顺，Git 能力保持可见但不阻塞基础笔记流程。
• Option B：保留 ADR-0034 的阻塞模态框。能防止 Git 功能语义模糊，但拒绝了合法的"纯文件夹"工作流。
• Option C：打开普通文件夹时自动初始化 Git。摩擦最低，但对不希望 Tolaria 修改文件夹元数据的用户来说行为出人意料。

前端状态机：useGitSetupState如何驱动"询问—关闭—重开"循环

文档中"打开时询问、关闭后持续警告、点击警告重开"的交互，在渲染进程中由 useGitSetupState 实现。这个 Hook 维护一个三态状态机：

export type GitRepoState = 'checking' | 'missing' | 'ready'

其关键机制包括：

• 状态探测：checkGitRepo在 Tauri 环境调用invoke('is_git_repo', { vaultPath })，浏览器/开发环境走mockInvoke，结果映射为ready（是 Git 仓库）或missing（不是）。探测失败时按ready处理，即检查失败向"放行"方向失败，避免探测异常卡死启动流程。
• 是否弹窗：shouldShowGitSetupDialog的判定逻辑是——处于windowMode或状态不是missing时不弹；用户手动打开过则强制显示；否则要求gitSetupPreference !== 'never'且该路径未曾被关闭过（dismissedGitSetupPath !== resolvedPath）。
• 关闭与"永不再问"：dismissGitSetupDialog只记录当前路径不再提示；neverForVaultGitSetupDialog则把偏好设为'never'，从此该库不再自动弹出，但仍可手动重开。
• 手动重开：openGitSetupDialog把manuallyOpened置为 true 并清除关闭记录——这就是"点击状态栏警告 / 从命令面板执行后能再次看到设置界面"的实现来源。
• 初始化成功后的状态收束：handleInitGitRepo调用init_git_repo命令后执行markGitRepoReady()、把偏好重置回'prompt'、清除手动与关闭标记，并弹出Git initialized for this vault的 Toast。

状态栏文案Git disabled来自本地化资源 en.json 中的status.git.disabled键，测试 StatusBar.test.tsx 也断言了该文案的渲染。

init_git_repo：唯一的事后启用 Git 后端命令

后端实现位于 commands/git.rs。is_git_repo命令委托给is_inside_work_tree判断路径是否在 Git 工作树内（含父仓库场景），而init_git_repo在执行初始化前先经过一层validate_git_init_target防护：

• 目标路径必须存在且是目录，否则分别报Choose an existing vault folder before initializing Git/Choose a folder before initializing Git；
• 如果目标是 Desktop、Documents、Downloads 等宽泛的个人文件夹，且不含 Tolaria 库标记文件（AGENTS.md、CLAUDE.md、type.md、note.md任一文件，或attachments、type、views任一目录），会被拒绝，错误信息会建议改用如<路径>/Tolaria的子文件夹——防止在用户整个"文档"目录下执行git init；
• 如果路径已经处于某个 Git 工作树内且自身没有直接 Git 元数据，也直接拒绝，错误信息说明 Tolaria 会使用父仓库而非创建嵌入式仓库。

通过校验后，init_git_repo调用 git/mod.rs 中的init_repo，其执行顺序固定为四步：

run_git(dir, &["init"])?; // 1. 创建仓库 ensure_author_config(dir)?; // 2. 确保提交者身份（尊重已有全局身份，缺失时补回退值） ensure_gitignore(dir)?; // 3. 写入默认 .gitignore（已存在则不动） run_git(dir, &["add", "."])?; // 4. 暂存全库 commit_initial_vault_setup(dir); // 5. 创建初始化提交

其中初始化提交显式禁用 GPG 签名（-c commit.gpgsign=false commit -m "Initial vault setup"），对应 ADR 所说的"无签名的 setup commit"——用户可能尚未配置任何提交身份，ensure_author_config负责兜底。

默认.gitignore内容（DEFAULT_GITIGNORE常量）刻意排除机器相关与平台元数据文件：

# Tolaria app files (machine-specific, never commit) .laputa/settings.json # macOS .DS_Store .AppleDouble .LSOverride # Thumbnails ._* # Editors .vscode/ .idea/ *.swp *.swo

并且ensure_gitignore的语义是文件已存在则完全不修改，保证不会覆盖用户手工维护的.gitignore。值得注意的是，移动端编译下这些命令是返回错误信息的桩实现（如Git history is not available on mobile），即完整 Git 流程依赖桌面端构建。

能力门控：命令注册与状态栏随库状态切换

ADR 的 Consequences 部分要求"UI 表面必须把 Git 能力当作每个库各自的状态，而不是应用级不变量"。这一点在 gitCommands.ts 的命令注册函数中体现得非常直接：

export function buildGitCommands(config: GitCommandsConfig): CommandAction[] { if (config.gitFeaturesEnabled === false) return [] if (config.isGitVault === false) return buildInitializeGitCommand(config) return buildGitVaultCommands(config) }

• 全局 Git 功能关闭：Git 组命令为空；
• 当前库非 Git：Git 组只注册Initialize Git for Current Vault（关键词含git、initialize、enable、history、sync），pull、commit、changes、conflict、remote 等命令全部不出现；
• 当前库是 Git 仓库：注册完整的命令集，包括Commit & Push（仅在modifiedCount > 0时可用）、Generate Commit Message from Diff、Add Remote to Current Vault、拉取、Resolve Conflicts、View Pending Changes等。

ARCHITECTURE.md 对同一行为的描述是：当库不是 Git 仓库时，Tolaria 把 Git 视为"不可用"而非"降级"——状态栏用Git disabled警告替换掉 changes、commit、sync、remote、conflict、history 控件（除非用户对该库选择了不再自动提示），useAutoSync对非 Git 库被禁用，应用不会针对普通文件夹发起任何后台 Git 命令。ABSTRACTIONS.md 中的状态表也把Non-git列为一种命名状态：库路径是普通文件夹，"Markdown 扫描、编辑、搜索、导航可用；Git 相关的状态栏控件与命令面板条目被Git disabled+Initialize Git for Current Vault替代"。

验证链路：冒烟测试覆盖"打开—关闭—事后初始化"

ADR 要求"测试需要同时覆盖 Git 库与非 Git 库"。Playwright 冒烟测试 non-git-vault-init.spec.ts 正是这条链路的端到端验证，完整走一遍用户旅程：

1. 用createFixtureVaultCopy复制一个夹具库，并以isGitRepo: false的方式打开；
2. 断言笔记列表可见（Alpha Project出现），证明非 Git 状态下核心浏览功能正常；
3. 断言出现Enable Git for this vault?标题的初始化对话框；
4. 按Escape关闭对话框，断言对话框消失且状态栏status-missing-git显示Git disabled——对应 ADR 中"关闭后应用继续工作 + 持续警告"；
5. 打开命令面板执行Initialize Git，对话框再次出现；
6. 聚焦Initialize Git按钮回车确认，断言对话框消失、Git disabled警告消失、status-pulse（Pulse 面板入口）出现——证明 Git 能力（Pulse 等）在初始化后恢复。

此外，commands/git.rs 自带的 Rust 单测还覆盖了初始化校验的边界情况，例如init_git_repo_rejects_broad_personal_folders（拒绝宽泛个人文件夹）、init_git_repo_allows_named_vault_subfolder_under_documents（允许 Documents 下带名称的库子目录）、is_git_repo_accepts_vault_nested_inside_parent_worktree（嵌套在父工作树中的库视为 Git 库）等，与前端状态机的三态判定形成前后端一致的语义。

决策后果与适用边界

ADR-0085 列出的四条后果，结合仓库现状可以这样理解：

• 既有 Git 库行为不变：历史、提交、同步、remote 流程与之前完全一致，非 Git 模式只是新增的合法起点；
• Git 能力是"按库的状态量"：UI 各表面（状态栏、命令面板、自动同步）都必须依据当前库的 Git 状态注册功能，不能假设"整个应用都有 Git"；
• 双态测试覆盖成为常态要求：浏览器 mock（mock-tauri的mockInvoke路径）与原生 QA 都要同时覆盖 Git 与非 Git 库；
• 约束未来功能：任何新增的 Git 依赖功能，都必须先检查当前库的 Git 状态，才能注册命令或运行后台任务——这也是buildGitCommands这种"按状态选命令集"模式存在的原因。

适用前提方面需要注意：完整流程依赖桌面端（Tauri）构建，移动端对 Git 命令返回"不可用"错误；is_git_repo的探测在异常时按"通过"处理，所以它只是一个轻量存在性检查，不做 remote 或历史校验；而打开时是否自动弹窗还受gitSetupPreference（prompt/never）控制，用户可以按库选择永不再被自动询问，但随时能通过状态栏警告或命令面板手动重新启用 Git。

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria