改进了 git.md and starter.md

notes/git.md

@@ -1,72 +1,77 @@
 # Git 基操
 
-## 工作流程
+## ⌛️ 时间机器
 
-我们选择 Git 作为版本管理的工具（确保已经安装 Git 和 VS Code，详见[starter](starter.md)），工作流程主要是以下 4 点：
+数字工作离不开版本管理（Version Control），你可以把 Git 想象成「时间机器」，它不仅负责记录、回溯时间点。还能允许你分裂、跳跃、合并时间线。
 
-- 大家在自己的「个人分支」工作，互不干扰
+在 Git 中，提交（Commit）就是时间点；分支（Branch）就是时间线。我们的工作流依靠提交和分支：
-- 通过「提交」，有选择性地，确认改动到「个人分支」（个人审核 AI）
+
-- 不时地，接收其他人在「主分支」的改动
+- 仅在自己的「个人分支」工作，互不干扰
-- 通过「合并请求」，有监督地，确认改动到「主分支」（团队审核个人）
+- 通过「提交」，有选择地确认改动到个人分支
+- 不时地接收其他人在「主分支」的改动
+- 通过「合并请求」，有监督地确认改动到主分支
 
 ```mermaid
 flowchart LR
   文件改动 -- 提交 --> 个人分支 -- 合并请求 --> 主分支
 ```
 
-通过上述流程，个人的本地改动被，有选择性地、有监督地被同步到项目主分支。
+通过这样的双审核机制，即解放了本地创作限制，又规范了线上协作流程。避免了同步网盘方案中，高频改动导致的文件冲突问题，以及 AI 操作导致的潜在安全风险。
 
-有效避免同步盘方案下，高频改动文件的冲突和 AI 无法参与的尴尬。这样，即释放了本地创作的限制，又规范了线上协作的管理，还解决了私有盘无法分享的问题。接下来，我将详细描述操作步骤
+接下来，我将说明具体的操作（确保已安装 Git、VS Code，详见 [必装软件/工具](starter.md)）
 
-### 在自己的「个人分支」工作
+### 仅在自己的「个人分支」工作
 
 **1. 下载仓库（Repository）**
 
-浏览器打开仓库地址 <https://git.omoolab.xyz/[orgn-name]/[repo-name]>，点右上的 Code 按钮，点击 Open with VS Code
+浏览器打开仓库地址 <https://git.omoolab.xyz/[orgn-name]/[repo-name]>，点右上的 Code 按钮，点击 Open with VS Code（如果没效果，用命令行）
 
 ![](assets/git-clone.png)
 
-> 或 Bash 执行 `git clone [git-url]`  
+或执行 `git clone [git-url]`  
-> 执行 `cd [repo-name]` 来进入仓库根目录
 
-> 有些仓库默认不拉取大文件，以确保本地仓库体积。  
+> 有些仓库默认不拉取大文件
-> Bash 执行 `git lfs pull --exclude= --include [folder]` 来下载仅需的文件夹
+> 通过执行 `git lfs pull --exclude= --include [folder]` 来下载仅需的文件夹
 
-**2. 创建自己的个人分支**
+**2. 创建个人分支**
 
 点左下角的`main`，点击 Create new branch...，然后输入分支名`[your-name]/[do-something]`(比如`manan/dev`)
 
 ![](assets/git-create-branch.png)
 
-> 或执行 `git checkout -b [your-name]/[do-something]`
+或执行 `git checkout -b [your-name]/[do-something]`
 
-创建后，首次推送分支到远程。这样远程也有属于你的分支了
+但这个分支目前只在本地，需要推送分支到远程。这样远程仓库也能存有属于你的分支了
 
 ![](assets/git-publish-branch.png)
 
-> 或执行 `git push -u origin [branch-name]`
+或执行 `git push -u origin [branch-name]`
 
+分支列表中有一些 `origin/*` 开头的分支，它们是属于远程仓库中的分支。但注意，这不代表它们存在于远程！想象一下，如果你处于断网状态，那么实际上这些 `origin/*` 分支也没有获得更新。而且它们的状态不会自动更新，除非你执行 `git fetch`、`git pull`、`git push`。
 
-### 通过「提交」来确认改动到「个人分支」
+### 通过「提交」来确认改动到个人分支
 
+**1. 有选择性地添加（Add）改动**
 
-**1. 有选择性地添加（Add）到暂存改动**
+任何较上次提交的变动都会罗列在 Changes 下，点击条目右边的 + 按钮来添加（只添加你认可的改动），条目会切换到 Staged Changes 下。你也可以点击 Changes 右边的 + 按钮来添加所有改动。
-
-仓库的任何改动都会罗列在 Changes 下，此时它们并没有得到确认。点击 + 来添加到 Staged Changes 下（你可以只添加部分改动）
 
 ![](assets/git-add.png)
 
 > 或执行 `git add [file]`
 
-**2. 提交（Commit）暂存改动**
+**2. 提交（Commit）改动**
 
-输入「提交说明」来记录改动了什么（或者点击小星按钮让 AI 来帮忙总结）。点击 Commit 按钮来确认改动。
+提交还需要说明信息（Commit Message），要求言简意赅（点击小星按钮让 AI 来帮忙总结）。
+
+填写后，点击 Commit 按钮来完成提交。
 
 ![](assets/git-commit.png)
 
 > 或执行 `git commit -m [message]`
 
-**3. 推送（Push）到远程的「个人分支」**
+**3. 推送（Push）到远程仓库的个人分支**
+
+虽然提交已经完成，但远程仓库仍然没有更新。我们需要通过推送，由本地同步给远程。（相反，由远程同步给本地的操作，叫拉取（Pull））
 
 点击三个点按钮打开菜单，点击 Push 按钮
 
@@ -78,9 +83,9 @@ flowchart LR
 
 ### 接收其他人在「主分支」的改动
 
-当你在自己分支工作的时候，其他人也在不断更新「主分支」`main`。有时需要对齐一下，拉取（Pull）并合并（Merge）来自`main`的改动到你自己的分支。
+当你在自己分支工作时，其他人也在不断更新主分支`main`。有时需要对齐一下，拉取（Pull）并合并（Merge）来自主分支的更新到你自己的分支。
 
-点击三个点按钮打开菜单，点击 Pull from...，并选择`origin/main`（注意不是`main`分支，它是本地的，并非最新）
+点击 … 按钮打开菜单，点击 Pull from...，并选择`origin/main`（注意不是`main`分支，它是本地的，不一定最新）
 
 ![](assets/git-pull-origin-main.png)
 
@@ -88,11 +93,11 @@ flowchart LR
 
 如果冲突，会进入`([branch-name]|MERGING)` 状态，详见 [解决冲突](#解决合并冲突)
 
-### 通过「合并请求」来确认改动到「主分支」
+### 通过「合并请求」来确认改动到主分支
 
-合并请求（Pull Request，PR）就是「个人分支」合并入「主分支」的申请
+合并请求（Pull Request，PR）就是个人分支合并入主分支的申请。
 
-浏览器访问仓库主页，切换到「个人分支」，点击 New Pull Request 按钮（3）
+浏览器访问仓库主页，切换到个人分支，点击 New Pull Request 按钮（3）
 
 ![](assets/git-checkout-feat.png)
 
@@ -100,17 +105,16 @@ flowchart LR
 
 ![](assets/git-pull-request.png)
 
-PR 会加入队列，等待审核通过。通过后就会合并到`main`啦。
+PR 会加入队列，等待审核通过。通过后就会合并到主分支啦。
 
 ![](assets/git-pr-list.png)
 
-> 注意，如果在提 PR 后，如果你又更新了你的分支，不必再次提 PR
+⚠️ 在提 PR 前，**一定**要在本地执行[同步「主分支」的改动](#同步「主分支」的改动)（且同步给了远程仓库的个人分支）
 
-> 注意，在提 PR 前，一定要在本地执行[同步「主分支」的改动](#同步「主分支」的改动)（且 push 到了远程「个人分支」）
+> 在提 PR 后，如果你又更新了你的分支，不必再次提 PR
 
 
-
+## 最佳实践
-## 一些小问题
 ### 多设备编辑同一分支
 
 首先不推荐这样做，但是为了一个设备，新加分支也很没必要。但如果由一个人操作这些设备，比如个人的 macbook、iphone 共同编辑，只要严格遵守下面两条：
@@ -123,7 +127,6 @@ PR 会加入队列，等待审核通过。通过后就会合并到`main`啦。
 
 解决完冲突后，继续
 
-
 > 或执行 `git merge --continue`
 
 
@@ -139,4 +142,8 @@ PR 会加入队列，等待审核通过。通过后就会合并到`main`啦。
 
 取消曾经追踪过的文件，但不删除文件
 
-执行 `git rm --cached [file]`
+执行 `git rm --cached [file]`
+
+### 个人分支的提交记录，本地和远程仓库不一致
+
+`git push --force-with-lease`

notes/starter.md

@@ -3,19 +3,19 @@
 ## 安装 Git
 
 Git 是版本管理工具，任何数字工作都离不开它。
-
+ 
 打开 windows powershell，运行
 
 ```powershell
 winget install Git.Git
 ```
 
-安装时中注意下面两点，其他默认下一步
+☝️ 安装时中注意下面两点，其他默认下一步
 - 勾选添加 Git Bash 到终端（Windows Terminal）
 - 选择`main`作为默认主分支名（默认是`master`）
 
 
-安装完毕后，打开终端（Windows Terminal），点击 v 按钮，点击设置。默认配置文件选择 Git Bash，保存。重启终端，后面命令行的操作都通过终端的 Git Bash 完成
+安装完毕后，打开终端（Windows Terminal），点击菜单栏 v 按钮，点击设置。默认配置文件选择 Git Bash，保存。重启终端，后面命令行的操作都通过终端的 Git Bash 完成
 
 设置本设备 git 的身份信息
 
@@ -39,18 +39,26 @@ VS Code 是最基础的 IDE，AI 编程 IDE 都基于它的源码，例如Cursor
 winget install vscode
 ```
 
+## 安装 Obsidian 
+
+Obsidian 是基于本地文件的 markdown 编辑软件，我们需要一款完善的 markdown 工具来查看我们的创作。
+
+```bash
+winget install Obsidian.Obsidian
+```
+
 ## 安装包管理器
 
-AI Agent 实现功能就是靠的是「工具超市」提供小工具，而包管理器（Package Manager）负责从「工具超市」上下载、更新、管理它们。Agent 会由于实践方式不统一，导致设备上存在大量的乱装的东西。
+AI Agent 实现功能靠的是「工具超市」提供小工具，而包管理器（Package Manager）负责从「工具超市」上下载、更新它们。由于实践方式不统一，如果不去限制，Agent 会在设备上乱装的东西。
 
 目前世界上最大的两个「工具超市」
 - Javascript 的 npm
 - Python 的 pypi
 
-给它们装最好的包管理器吧
+给它们装最好用的包管理器吧 🚀
 ### Volta
 
-管理 Node.js 的工具，它可以比 npm 原生更好的管理由 Javascript 写的工具。
+它是管理 Node.js 的工具，使用 Node.js 写的工具离不开它
 
 ```bash
 winget install Volta.Volta
@@ -64,22 +72,21 @@ volta install node
 
 ### Uv
 
-极速 Python 包和项目管理工具，不管是用 Python 做开发还是使用 Python 写的工具都离不开它
+极速的 Python 包、项目管理工具，不管是用 Python 做开发还是使用 Python 写的工具都离不开它
 
 ```bash
 winget install --id=astral-sh.uv -e
 ```
 
 
-## 安装 claude code
+## 安装 Claude Code
 
-Claude code 不用介绍了，建议通过 [Volta](#Volta) 安装 Claude Code CLI
+它我不用介绍了，建议通过 [Volta](#Volta) 安装 Claude Code CLI
 
 ```bash
 volta install @anthropic-ai/claude-code
 ```
 
-
 （可选）安装 cc-switch
 https://github.com/farion1231/cc-switch/releases