跳转至

GitHub 推送规则

类型：rule（操作指南） 描述：首次推 github + 日常同步流程 + 同步策略 触发场景： - 用户说「推 github」「同步 github」「上传到 github」 - 用户说「初始化 git 仓库」 - 用户说「fetch / pull 远端」 优先级：⭐⭐ 高（涉及外部系统协作）

什么时候用

  • 首次把项目推到 github
  • 完成一个版本后同步代码 + 文档
  • 与协作者拉取/合并代码
  • 切分支 / 打 tag

同步策略（关键）

✅ 同步的内容

路径 说明
src/ 全部源代码
docs/ 全部知识库（raw / specs / wiki / issues / rules）
package.json / pnpm-lock.yaml 依赖管理
wxt.config.ts / tsconfig.json 构建配置
CLAUDE.md / README.md / 更新规则.md / development-log.md 文档根
.gitignore 同步规则本身

🚫 不同步的内容（已在 .gitignore）

路径 不同步理由
backup/ 用户偏好 — 本地备份，敏感度由本地保管
dist/ / dist-v2/ / .wxt/ / .output/ 构建产物，可重生
node_modules/ 依赖，体积大，靠 lockfile 重装
.env / .env.* 环境变量 / 敏感配置
.vscode/ / .idea/ / .obsidian/workspace.json IDE / 编辑器个人设置
*.log / .tmp/ 临时文件
test/ 历史 zip 归档（仅本地）

标准操作

首次推送（一次性）

前置： - GitHub 账号 + 一个 empty repo（不要预填 README / .gitignore，避免冲突） - 本地 git 已 git config user.name/email - 已有 Personal Access Token（PAT）或 SSH key

# 1. 初始化（如果还没）
git init
git branch -M main

# 2. 添加 remote
git remote add origin https://github.com/<你>/<repo>.git
# 或用 SSH: git@github.com:<你>/<repo>.git

# 3. 第一次 add + commit
#    .gitignore 已经写好，backup/ dist*/ node_modules/ 自动不会被加
git add .
git status      # ⚠️ 必看：确认没把 backup/ 或敏感文件加进去

git commit -m "chore: 初次提交 — v0.10.22 知识库改造完成"

# 4. push
git push -u origin main

日常同步（每个版本完成后）

# 1. 看本次改了啥
git status
git diff --stat

# 2. 选择性 add（不要无脑 git add -A，可能漏掉 .gitignore 没覆盖的临时文件）
git add src/ docs/ package.json 更新规则.md development-log.md CLAUDE.md

# 3. commit（消息建议：版本号 + 1 行总结）
git commit -m "v0.10.22: 知识库改造 — 引入 raw + specs 层 + frontmatter"

# 4. push
git push

拉取远端更新

git pull --rebase origin main  # rebase 比 merge 历史更线性，推荐

⚠️ 必备前置 / 易错点

必备

  • .gitignore 已写好（v0.10.22 已建）
  • backup/ 在 .gitignore 内 — 用 git status 确认不出现
  • 没有 .env 等敏感文件被加 — 用 git status 确认
  • commit message 用项目惯例（建议：vX.Y.Z: 一句话总结 或 conventional commits）

易错点

  • ⚠️ 不要 git add -A 之前不 status：可能加上你不想推的东西
  • ⚠️ 不要把 backup/ 强制 add（-f）：备份是私有的，不该上 github
  • ⚠️ 不要直接 push --force 到 main：除非确定是自己一个人的 repo + 知道在干啥
  • ⚠️ PAT 不要 commit 进 url：用 SSH 或 git credential helper
  • ⚠️ 第一次 push 前先 git status 看清楚：如果意外把 backup 加了，git reset HEAD backup/ 再 commit

与 Obsidian 同步的关系

如果你也用 obsidian 打开这个仓库： - .obsidian/workspace.json 等个人配置已在 .gitignore（不冲突） - obsidian 的 [[wikilink]] 在 github 网页不渲染 — 仅 obsidian 内用，github 上看普通文本 - 主链接用相对路径 [文本](./path.md)，github 和 obsidian 都识别

完成后必做

  • git status 确认干净（无未提交）
  • git log --oneline -5 看看最近 5 个 commit
  • 浏览器打开 github repo 确认 backup/ 没上去
  • 如果是首次推：把 repo 链接加到 README.md 顶部

元规则触发回顾

本规则是用户在 SPEC-001-知识库改造 中提出「github 同步，备份不同步」时建档。 按 元规则：首次描述工具用法 → AI 立即落档 → 后续不需要再描述。

历史

日期 事件
2026-05-26 建档，作为 SPEC-001 知识库改造的产物