跳至主要內容

历史重写后的同步说明

规则版本控制

历史重写后的同步说明

历史迁移的适用范围

本页记录 2026-03-22 的一次性历史重写，后文只适用于普通公共克隆或协作者 fork。已配置白名单直连的私人生产笔记库使用 同步配置注意事项 指向的同步入口，不用本页的 reset、普通 pull 或强推流程对齐公共历史。直连脚本发现上游重写会停止，需要单独审查基准。

2026-03-22 仓库进行过一次历史重写，用于清理 _assets_ 与 .obsidian 的旧历史记录，并保留当前最新状态。

这意味着：

  • 远端 main 的提交历史已经变化。
  • 之前基于旧历史 clone 的本地仓库，需要手动同步一次。
  • fork 仓库不会自动更新，但如果要继续跟随上游，也需要手动同步。

谁需要处理

1. 新 clone 的用户

如果你是历史重写之后才第一次克隆仓库：

  • 不需要额外处理。
  • 正常 git clone 即可。
git clone https://github.com/PKM-er/Pkmer-Math.git

2. 之前已经 clone 过本仓库的用户

如果你的本地仓库是在历史重写之前拉下来的：

  • 需要同步一次新的远端历史。
  • 否则后续 pull / push 可能出现分叉、拒绝推送或大量冲突。

3. fork 过仓库的用户

如果你有自己的 fork：

  • GitHub 不会自动把上游历史重写同步到你的 fork。
  • 你需要手动把 upstream/main 同步到自己的分支。

最常见的几种情况

情况 A：本地没有需要保留的差异

仅当未提交修改和仅存在于本地的提交均已备份或确认不需保留时，才可将普通公共克隆对齐远端。工作区干净不代表没有本地独有提交：

git fetch origin
git checkout main
git reset --hard origin/main

说明：

  • fetch 只更新远端信息。
  • reset --hard origin/main 会让本地 main 直接对齐远端。
  • 这会丢弃本地未提交修改，所以确认工作区干净后再执行。

情况 B：本地有未提交修改

下面的 stash 只保护其包含的工作区改动，不保存分支上本地独有的提交，默认也不包含未跟踪或忽略文件。先另行备份这些内容，确认只需恢复 stash 后，再在普通公共克隆中操作：

git stash
git fetch origin
git checkout main
git reset --hard origin/main
git stash pop

如果 git stash pop 后有冲突：

  • 保留你真正需要的内容。
  • 解决冲突后重新提交。

建议先查看当前状态：

git status --short --branch
git stash list

情况 C：你有自己的 fork，要继续同步上游

先确保本地配置了 upstream 指向主仓库：

git remote add upstream https://github.com/PKM-er/Pkmer-Math.git

如果之前已经配置过，可以先查看：

git remote -v

然后同步上游历史：

git fetch upstream
git checkout main
git reset --hard upstream/main
git push --force-with-lease origin main

说明：

  • 这里的 origin 是你自己的 fork。
  • 由于上游发生过历史重写，同步 fork 时通常也需要一次强推。
  • 推荐使用 --force-with-lease，比 --force 更安全。

不建议怎么做

1. 不建议直接 git pull

历史重写后，直接 git pull 往往会：

  • 生成很乱的 merge 记录；
  • 或者直接报错；
  • 或者把你带回一团旧历史里。

这次更稳妥的做法是：

  • 先 fetch
  • 再 reset --hard 到新的远端分支

2. 不建议在主工作区直接切旧历史反复查看

如果你本地还有自定义 .obsidian 配置，反复 checkout 旧历史有可能导致配置被覆盖或删除。

更稳妥的做法：

  • 使用独立目录重新 clone
  • 或使用 git worktree

推荐操作顺序

下列顺序仅用于本次历史迁移，且以本地独有提交、未跟踪及忽略文件已备份为前提；它不是私人笔记库的日常同步流程：

  1. 先确认工作区是否干净：
git status --short --branch
  1. 如果有改动，先 stash：
git stash
  1. 拉取新的远端信息并强制对齐：
git fetch origin
git checkout main
git reset --hard origin/main
  1. 如果你刚才做过 stash，再恢复：
git stash pop

如果你只是想继续正常写内容

处理完这一次历史重写同步之后，后续就按平时方式使用即可：

git pull origin main
git add .
git commit -m "你的修改说明"
git push origin main

遇到问题时请附带的信息

如果你同步时出错，建议把以下信息一起发出来：

git status --short --branch
git remote -v
git log --oneline --decorate -n 8
git stash list -n 10

这样更容易判断你当前是：

  • 本地有未提交修改；
  • 远端分支不同步；
  • fork 没跟上 upstream；
  • 还是旧历史残留导致的问题。
链接到当前文件 2