先交代一句大实话这两年我把全部笔记真正塞进了一个 Git 仓库并且为它专门写了一个 App 来管理。市面上笔记软件林林总总我都试过一遍最后最顺手、最没有心理负担的方案反而是这个最“原始”的组合纯文本 Markdown Git 历史版本 自己写的桌面端小工具。这篇博文把这套方案从头到尾讲清楚包括为什么选 Git、仓库怎么搭、App 的核心设计、关键代码实现以及我踩过的所有坑。如果你受够了笔记软件的锁定、想找回对数据的控制权又稍微有点动手能力这篇文章可以直接当“作业”来抄。1. 为什么偏要用 Git 来管笔记先说场景。我的笔记内容包括三类日常记录会议、灵感、日志、知识沉淀书摘、技术笔记、教程草稿、长期项目博客素材、产品方案、个人 OKR。以前我试过印象笔记、Notion、语雀、Bear无一例外在某个节点会遇到同一个问题数据越多越不敢迁移越来越像被“绑定”在某个闭环里。1.1 笔记软件的隐性代价不是它们不好而是我逐渐意识到几个关键矛盾。第一是数据锁定。大多数在线笔记服务的数据库格式不开放导出时的 Markdown 往往还要经过一层清洗图床、附件、双链关系都会丢。一旦用了五年十年想脱离几乎不可能。第二是版本回溯难。笔记软件通常有历史记录但那是平台侧的不可控。我想找回“三个月前的一句话”要么靠编辑器自带的版本要么靠网盘回收站运气成分大而且操作非常割裂。第三是离线能力参差不齐。很多云笔记离线时能看缓存但修改、同步、搜索都很别扭。我出差多高铁隧道多断网是常态离线体验差直接等于没法写东西。第四是搜索跨应用难。我的知识和想法是散在多个系统里备忘录、公众号收藏、邮件、聊天记录……统一搜索只能靠外部工具体验也很碎。最后是内容格式被“模板化”。很多笔记软件用块编辑器看着好看但导出的 HTML 一塌糊涂不利于二次加工。对于一个想长期积累素材的人纯文本的可复用性是最重要的。1.2 Git 做笔记底座的收益换到 Git 之后上面这些痛点大多数都消失了。天然版本历史每一次改动都有 commit回退、对比、找词句都是免费的。文本友好Markdown 就是纯文本diff 非常清楚。改了一个字、加了半句话用git diff一眼能看见。完全离线仓库在本地全量存在没网照样读、照样写。无锁定Git 只是文件系统加版本管理只要目录在数据永远是你的。多端同步可自控可以选自己的服务器、NAS 或者只是 U 盘做“裸仓库”也能推到托管平台做备份迁移成本几乎为零。便于自动化笔记是普通文件我可以写脚本批量处理加标签、统计字数、做全文索引都行。打个比方这就像把自己房间里所有散落的便签整理好再用一台永远不会偷懒的“账本机器”帮你记录每一次改动。它不替你做决定但你要的一切过程都在账本里。1.3 选这条路的代价和前提先泼冷水Git 仓库管笔记并不适合所有人。冲突要自己处理多端同时改一个文件提交时就会冲突。虽然 Git 的冲突标记可读性很强但毕竟需要人工介入。建索引要自己搞笔记多了之后靠grep找内容会越来越慢。我自己写 App 的很大一个目的就是补上“全文搜索”和“标签索引”这两个能力。目录结构必须规范如果没有命名规则塞进去一万个文件后连自己都认不出哪个是哪个。适合以文本为主的场景大图、设计稿、音频等二进制文件不适合进 Git仓库会迅速膨胀。所以如果你打算照抄这个方案先确认自己的笔记 80% 以上是文字。如果是图片笔记、手写笔记为主治理成本会高出好几个量级。2. 仓库结构设计先想清楚再动手我可以负责任地说最开始我犯过的最大的错就是“直接往仓库里扔 Markdown 文件”。两周后目录就变成了一锅粥。后来反复迭代才把仓库结构定成下面这套稳定用了很长时间。2.1 目录与命名规范一套稳定可读的目录结构应该具备两个特点领域隔离和时间排序。我给每个大类建一个顶级目录大类下再按月或按主题建子目录。notes-root/ ├── README.md ├── daily/ │ ├── 2025-03-12.md │ ├── 2025-03-13.md │ └── 2025-03/ │ └── ... ├── projects/ │ ├── note-manager-app/ │ │ ├── 2025-02-20-design.md │ │ └── 2025-03-01-todo.md │ └── ... ├── knowledge/ │ ├── git/ │ │ └── 2025-01-10-rewrite-history.md │ └── database/ │ └── 2025-01-18-sqlite-fts.md ├── templates/ │ └── note-template.md └── assets/ └── 2025-03-12-image.png命名规范是三段式YYYY-MM-DD-短横线slug.md。这样排序稳定、路径可读性好git log里也很直观。我强烈建议加一个templates/note-template.md每次新建笔记就复制模板。模板长这样--- type: note title: 标题 tags: [] status: draft source: created: 2025-03-12 08:00:00 updated: 2025-03-12 08:00:00 --- # 标题 这里开始正文。模板的意义在于让元数据从一开始就存在后面做索引、搜索、统计全靠这个基础。2.2 元数据方案YAML front-matter笔记的元数据标题、标签、状态、创建时间、更新时间我放在每个文件顶部的 YAML front-matter 里。为什么不单独建一个meta.json三个原因放在文件内部跟随文件本身走移动、复制、分支合并都不会丢。Markdown 编辑器VS Code、Typora、Obsidian很多都原生识别 front-matter不用额外插件。改元数据就是改文件Git 的 diff 能清晰看到历史。如果想统计所有带某个标签的笔记走一遍解析扫 front-matter 就行。需要注意不要把“最后修改时间”完全交给 front-matter 手写因为很容易忘记更新。可以让 App 在保存时统一改写updated字段或者依赖 Git 的 commit 时间。我更推荐前者因为搜索和列表页需要快速排序不需要每次去查 git log。2.3 附件与二进制文件怎么处理纯文本好办遇到图片和 PDF 怎么办我的经验是分两层。第一层小图片尽量压缩后入库。几张手机截图、架构图转成.png或者.webp控制在几百 KB 以内放进assets/目录。Git 仓库里带一些二进制文件是没问题的只要总量不大。第二层大附件绝对不入库。比如设计原稿、视频、上百 MB 的资料包我会放到外部对象存储或者网盘然后在笔记里保存一个链接和描述。仓库里只留了索引信息不会因为一个附件让整个仓库膨胀到几 GB。这是我实际踩过的坑最早我往仓库里塞了一堆手机相册原图仓库体积瞬间到 3GBpush 到远端慢到让人崩溃。后来全部清理改为小图入库 大图外链。为了防呆我在仓库根目录写了一行.gitattributes提示文件类型白名单并在.gitignore里把*.zip、*.psd、*.mov、*.mp4这类文件直接屏蔽掉。2.4 敏感内容必须隔离处理笔记里难免会写一些访问密钥、服务器地址、个人信息。这些内容如果进去 Git 历史哪怕后来删掉了历史里依然存在。我的处理原则能不进仓库的绝不放进去。键值对、密钥清单单独放到一个加密文件里例如secrets.ageage 加密然后明文密钥文件写进.gitignore。涉及个人隐私的文字我会单独加密成一份.md.age文件需要的时候用工具解密查看。加密工具我用过 GPG 和 age简单场景强推 age命令短、智商负担低age-keygen -o key.txt age -e -r $(cat key.txt) -o secrets.age secrets.txt age -d -i key.txt -o secrets.txt secrets.age只要保证key.txt不出本地机器、不入仓库这个方案在个人笔记场景里足够可靠。有一说一这个机制我早期没做后来意识到历史里已经残留了敏感词不得不做了一次历史改写过程很折腾后面第 5 章会讲。3. App 的产品设计与技术选型当仓库里的文件超过几百个之后靠文件管理器一层层点目录已经很难受了。我当时的真实需求是浏览目录树快速切到任何一篇笔记。全局搜索标题和全文最好能按标签筛选。快速新建笔记能选目录和模板。编辑保存后能直接 commit 到 Git。能看到笔记的历史版本能对比和回滚。基于这些需求我决定自己写一个 App而不是继续依赖 VS Code 或 Obsidian 的插件。3.1 功能范围的取舍MVP我刻意砍掉了很多花哨功能第一版 App 只做了这些左侧目录树按仓库目录结构展示。中间编辑器支持 Markdown 预览。右侧信息面板显示 front-matter、标签、统计。顶部搜索框实时搜索标题和全文。底部状态栏显示 Git 仓库状态和当前分支。不做什么实时协同、移动端 App、所见即所得编辑器、云服务后台。我只需要一个“本地桌面的收纳工具”做太多反而会分心。3.2 技术选型Tauri SQLite CodeMirror我最终选了 Tauri 而不是 Electron。原因很直接Tauri 打包体积小内存占用低启动快。前端用 Web 技术栈写起来效率高。后端用 Rust调用 Git 子进程、扫描文件、操作 SQLite 都非常稳。我本来就会 Rust 和 TypeScript没有额外学习成本。如果你不熟 Rust完全可以用 Electron 或者 Python PyQt核心思路一样只是性能会差一些。数据库我选 SQLite配合 FTS5 做全文搜索。SQLite 单文件、零配置、嵌入式对这种单机索引场景太合适了。索引建在notes.db只要注意更新策略搜索性能可以做到毫秒级。编辑器我选了 CodeMirror 6是因为它比较轻插件生态合理能方便地做 Markdown 语法高亮和自动补全。如果你想要开箱即用的 markdown 编辑体验Monaco 或 Milkdown 都可以但 Monaco 更重Tauri 下体验差异明显。3.3 数据模型索引和搜索的核心App 的核心逻辑其实是围绕 SQLite 建表下面是我实际在用的表结构CREATE TABLE notes ( id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT NOT NULL UNIQUE, -- 相对仓库根目录的路径 title TEXT NOT NULL, excerpt TEXT DEFAULT , type TEXT DEFAULT note, -- note / daily / project tags TEXT DEFAULT , -- 逗号分隔冗余字段 status TEXT DEFAULT draft, created_at TEXT, updated_at TEXT, file_mtime INTEGER NOT NULL, -- 文件系统修改时间 file_size INTEGER NOT NULL, content_hash TEXT NOT NULL, -- 内容哈希用于增量扫描 indexed_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE tags ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE ); CREATE TABLE note_tags ( note_id INTEGER NOT NULL, tag_id INTEGER NOT NULL, UNIQUE(note_id, tag_id) ); CREATE VIRTUAL TABLE notes_fts USING fts5( title, excerpt, content, contentnotes, content_rowidid, tokenizeunicode61 );我特意把content_hash和file_mtime放进表里是为了做增量索引。App 启动时只需要扫描文件的 mtime 和 size如果没变就不重新解析文件内容这样即使仓库有上万文件冷启动也能控制在几百毫秒内。这里有个小经验FTS5 表和原表同步不要用额外的触发器直接在应用层维护代码更直观不容易出坑。每次更新资料后手动做一次INSERT INTO notes_fts(rowid, title, excerpt, content) VALUES (newId, newTitle, newExcerpt, newContent);这样搜索时直接SELECT n.* FROM notes_fts f JOIN notes n ON n.id f.rowid WHERE notes_fts MATCH ?;性能非常稳几千篇笔记秒出结果。4. 实操过程与核心环节实现整套方案里最容易翻车的是“App 怎么调用 Git”以及“索引与真实文件怎么保持一致”。这部分我详细拆一下。4.1 调用 Git 的正确姿势在 App 里执行 Git 命令通常用子进程。Tauri 里我用 Rust 的std::process::Command前端通过自定义 command 暴露。如果你用 Electron用 Node 的child_process.execFile也行。关键点有三每个 Git 操作都要指定仓库工作目录最好直接用-C参数而不是改进程当前目录避免状态污染。加--no-optional-locks防止只读操作在后台触发索引刷新导致性能抖动。加-c core.quotepathfalse否则中文文件名会被转义成\344\270\255...显示和解析都很恶心。我的伪代码大概是这样的git -C /path/to/notes-root --no-optional-locks \ -c core.quotepathfalse \ status --porcelain提交时加上统一的 commit message 模板git -C /path/to/notes-root add -A git -C /path/to/notes-root commit -m note: 更新《Git仓库管理笔记》在 App 层我设计了一个GitService所有按钮操作都走同一个方法队列避免多个子进程同时写.git目录导致 index.lock 冲突。Rust 端的核心片段如下简化版本#[tauri::command] fn git_commit(repo: String, message: String) - ResultString, String { let output Command::new(git) .args([-C, repo]) .args([-c, core.quotepathfalse]) .args([commit, -m, message]) .output() .map_err(|e| e.to_string())?; if output.status.success() { Ok(String::from_utf8_lossy(output.stdout).to_string()) } else { Err(String::from_utf8_lossy(output.stderr).to_string()) } }这里有个大坑不要直接调git commit -am。它会把所有文件的变化一股脑提交包括你并不想提交的临时文件。我推荐做法是先git add -A然后对已暂存内容做一次状态检查更新界面上的“待提交数量”确认后再 commit。4.2 增量扫描与索引构建App 启动后第一件事是“扫描仓库”决定哪些文件需要重新索引。我会先递归读取notes-root下所有.md文件得到每个文件当前的 mtime、size。然后和 SQLite 里的记录比对如果路径不在表里说明是新增文件解析全文并插入。如果路径在表里但 mtime 或 size 变化说明文件被外部编辑器改过重新解析。如果路径表的文件已经不存在删除记录并同步 FTS。扫描过程我单独放在后台线程不阻塞界面。第一次建立全量索引可能会慢一点一千篇笔记大概几秒钟之后每次启动基本上秒级。解析内容时我用了两个库Rust 端用serde_yaml解析 front-matter用pulldown-cmark做 Markdown 转纯文本截前 200 字作excerpt。如果你用 Node也可以用gray-matter加remark。这里有个体验优化不要把整篇正文塞进excerpt再显示在列表里那样列表会很卡。列表只展示标题 摘要 标签点进去再加载全文。4.3 历史浏览与回滚App 里每个笔记页面都加了一个“历史”按钮。点击后执行git -C /path/to/notes-root log --oneline --follow -- file_path拿到 commit 列表后再对指定版本执行git -C /path/to/notes-root show commit_hash:file_path然后把内容展示在预览容器里并支持“将此版本恢复为当前内容”。恢复的本质就是把这个版本的文本写回文件然后调用git commit留一条恢复记录。不要直接git revert因为你会丢失当前草稿里尚未提交的新改动风险很高。如果只需要看两次改动差异我直接用git -C /path/to/notes-root diff commit1 commit2 -- file_path把输出渲染成新旧文本 diff高亮增删行。4.4 多端冲突的工程方案冲突是这套方案最没法回避的坎。我的场景是一处在家里的电脑一处在办公室电脑偶尔用一台笔记本在途中写。如果两边都修改了同一篇笔记就会冲突。我在 App 里做了三个处理动作检测到冲突时优先显示哪个文件冲突。提供“采用本地版本”、“采用远端版本”、“手动打开合并”三个按钮。如果手动合并我会调用系统编辑器打开冲突文件让用户自己删掉和标记后保存。命令行应急修复长这样# 查看冲突状态 git status # 手动解决某个文件冲突后 git add notes/daily/2025-03-12.md git commit -m 解决 2025-03-12 笔记冲突我自己的高频习惯是出门前git pull一次回家后git pull一次写完立刻 commit。频率降下来冲突自然少。手机上我一般只读不死磕移动端编辑因为那个体验做得再好也打不过电脑。5. 常见问题与排查技巧实录最后这部分全是真金白银的踩坑记录。我不讲空话直接上问题和对应的解法。5.1 常见问题速查表现象可能原因处理方式Git 操作经常报index.lock多个 Git 子进程同时运行加操作队列保证同时只有一个 Git 写入命令中文文件名/内容显示乱码没有设置core.quotepath把-c core.quotepathfalse加到 Git 命令参数commit 后仓库还显示有改动行尾符问题CRLF/LF在仓库根目录加.gitattributes设置* textauto搜索不到刚写的笔记增量索引没刷新保存后立即更新 SQLite 记录和 FTS 表仓库越来越大二进制文件/大附件入仓用git filter-branch或git filter-repo清理历史并更新.gitignore多端同时改同一文件后 push 失败非快进合并git pull --rebase后解决冲突再 pushgit status非常慢仓库文件数太多考虑拆分仓库或启用git sparse-checkout误把密钥提交进历史敏感信息泄露立即轮换密钥并用git filter-repo清理历史然后强制推送5.2 误提交敏感信息的处理实录这个坑我必须重点讲。最早我的仓库里有一个env.md记录了某台服务器的 root 口令。当时没有加密意识想着“反正是私人仓库没别人看见”。后来仓库要推到远端备份我把这个文件删掉了但实际上 Git 历史里还残留着。处理方案是彻底改写历史。工具上首选git filter-repo比官方filter-branch快很多且不容易出错。git filter-repo --invert-paths --path env.md然后强制推送到远端git remote add origin remote-url git push -f --all这里我最想强调的是一旦敏感信息进入仓库并且被 push 过就应该默认它已经泄露先把密钥废掉再清理历史。这不是技术洁癖是安全底线。对绝大多数个人笔记场景建议密码、密钥单另保存不要放进笔记仓库。5.3 性能优化记录仓库从几百篇涨到两千多篇后我开始注意到两个性能问题。第一是全文索引初始化慢。后来我把“启动时全量扫描”改成“后台增量扫描”加了个基于 mtime 的快速跳过情况好很多。如果你用的语言没有原生文件监听可以退而求其次每 5 分钟扫一次变更或者监听mtime汇总后再更新。第二是编辑器卡顿。当打开一篇超长笔记几万字CodeMirror 6 初期渲染还是会有一点延迟。后来我给大文件启动了“分段惰性渲染”只渲染视口区域问题基本解决。如果只是个人笔记几千字以内这个优化可以延后。还有个小细节我用了一个stat命令批量获取文件 mtime而不是在 Rust 里递归调用metadata()。stat -c %Y %n输出稳定一次性得到所有文件的修改时间和路径扫描速度比逐文件调用快很多。如果你在 Windows 下用 PowerShell也可以用Get-ChildItem配合LastWriteTime和Length。5.4 一个让我省心的同步流程这里分享我目前一直在用的“双远端同步法”。一个远端是私有 Git 托管平台代码托管服务另一个是 NAS 裸仓库。每次写完笔记我会在 App 里点“提交”本地 commit。跑一次git push origin master推到托管平台。再跑一次git push nas master推到 NAS 裸仓库。两条线都是同步的任何一个远端挂在物理损坏的硬盘上都还有另一份。说实话这条流程让我彻底告别了过去那种“重要文件备份三家网盘”的焦虑。要注意的是裸仓库只是备份不是工作目录。如果某个设备想编辑必须 clone 下来不能在裸仓库里直接改文件。结尾从我个人的实际体验来说“把所有笔记塞进一个 Git 仓库再写个 App 管理”这件事最大的价值不是技术上的炫技而是重新拿回了数据的主导权。我不再受某个笔记软件的功能边界、同步限制、收费策略影响写的东西永远是普通文本永远能打开永远能追溯。最后分享一个我在这个项目里最实用的小技巧在 App 界面加一个小按钮一键显示“今天改过哪些文件”。它背后只是跑了一句git log --sincetoday --name-only但带来的正反馈非常强。你会很直观地看到自己今天写了什么、改了多少这种“看得见的产出感”比做十次年度复盘都管用。这套方案后续还可以扩展的方向很多比如把 FTS 搜索改成局域网内多设备共用同一个 SQLite 索引、对 encrypted note 做更友好的编辑器集成或者加入自动化标签推荐。但核心始终不变文本是你的资产Git 是你的流水账App 只是一个和你习惯契合的“抽屉”。先把这个抽屉打磨顺手其余的都只是加分项。