util6 notes

Appearance

知识库：Mac 使用 launchd 自动同步 Git 仓库 ​

本文档归档当前笔记仓库在 macOS 上的自动同步方案，重点包括：为什么选择 launchd、自动任务的文件结构、每日 16:50 自动提交推送的执行逻辑，以及 opencode 生成 commit message 的接入方式。

1. 目标 ​

目标是在当前这台 Mac 上，为仓库 blog-article 增加一个系统级自动任务，实现每天固定时间自动：

  1. git add -A
  2. git commit
  3. git push

对应仓库路径：/Users/util6/Documents/blog-article

2. 采用的技术链路 ​

最终采用的是 macOS 原生的 launchd 方案。

使用的是：

  • launchd
  • LaunchAgent
  • launchctl

而不是：

  • cron
  • Automator
  • 快捷指令自动化

原因是：

  • launchd 是 macOS 官方后台任务方案。
  • 更适合图形桌面用户会话。
  • 对这种每天固定时间执行一次的 Git 脚本足够稳定。

需要注意：这个任务虽然是系统原生能力，但它不显示在“快捷指令”App 中，因为它属于 launchd / LaunchAgent 后台任务，而不是 Shortcuts 自动化。

3. 已落地的文件 ​

脚本文件：

  • ~/Library/Application Support/blog-article-sync/auto-sync.sh

任务配置文件：

  • ~/Library/LaunchAgents/com.util6.blog-article-auto-sync.plist

日志目录：

  • ~/Library/Logs/blog-article-sync/

4. 任务执行时间 ​

任务被配置为每天：

  • 16:50

对应的 plist 关键配置示例：

xml
<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key>
  <integer>16</integer>
  <key>Minute</key>
  <integer>50</integer>
</dict>

5. 自动化脚本的执行逻辑 ​

脚本会按下面顺序执行：

  1. 检查仓库目录是否存在。
  2. 检查当前分支是否为 master。
  3. 检查是否存在 index.lock、merge、rebase 等冲突状态。
  4. 执行 git add -A。
  5. 若无暂存改动则退出。
  6. 调用 opencode run --format json 生成 commit message。
  7. 若生成失败，则回退为 自动同步 YYYY-MM-DD HH:MM:SS。
  8. 执行 git commit -m ...。
  9. 执行 git push origin master。

由于当前 origin 带有多个 push URL，所以这个自动任务会沿用已有的多远端推送行为。

6. 为什么接入 opencode ​

检查本机 opencode 后，确认它支持可脚本化 CLI：

  • opencode run [message..]
  • opencode run --format json

这说明它不是只能跑交互式 TUI，而是可以嵌入 shell 脚本，作为 commit message 生成器使用。

最终接入策略是：

  • 优先调用 opencode 生成更自然的中文提交信息。
  • 调用失败时自动回退到固定时间戳消息。

这样既保留了自动化的稳定性，也提高了自动提交信息的可读性。

7. 如何确认任务已经存在 ​

可以通过下面的命令查看：

bash
launchctl list | rg blog-article

如果能看到：

text
com.util6.blog-article-auto-sync

就说明该用户级任务已经被 launchd 加载。

此外，也可以直接查看：

  • ~/Library/LaunchAgents/com.util6.blog-article-auto-sync.plist
  • ~/Library/Logs/blog-article-sync/run.log

8. 启停方式 ​

停用任务：

bash
launchctl unload ~/Library/LaunchAgents/com.util6.blog-article-auto-sync.plist

重新启用任务：

bash
launchctl load ~/Library/LaunchAgents/com.util6.blog-article-auto-sync.plist

9. 当前方案的优点与风险 ​

9.1 优点 ​

  • 使用 macOS 原生后台调度能力。
  • 不依赖第三方定时器。
  • 自动任务结构简单，容易排查问题。
  • 可以复用 opencode 生成更自然的提交说明。

9.2 风险 ​

  • 自动任务会提交当时工作区中的所有改动，而不是只提交部分文件。
  • 如果某天工作区里存在不想提交的临时改动，自动任务也可能一起提交。
  • 如果远程有冲突、认证失效或者网络异常，自动推送会失败，需要看日志排查。

10. 后续可选增强 ​

如果后续要继续迭代，可以在现有 launchd + shell + opencode 结构上继续增强，例如：

  1. 只自动提交 .md。
  2. 排除图片目录或其他特定路径。
  3. 提交前自动 git pull --rebase。
  4. 成功或失败时发送 macOS 通知。
  5. 在提交前增加更严格的文件筛选规则。

对于当前个人知识库仓库来说，现有方案已经足够实用，重点在于后续是否要进一步缩小“自动任务会把所有改动一起提交”的风险面。