一篇可以直接保存的学习日志。结合现在的 NewVFX AI 项目、Pulsar 编辑器和已经创建的 Git 提交记录，重点放在每天真正用得上的命令，不讲太多理论。

学习日志 · Git 本地版本管理 · macOS / Pulsar / NewVFX AI

Git 实战学习日志：从代码修改到版本回退

一、先理解 Git 的核心逻辑

Git 可以理解为给代码建立一条可追溯的时间线。

Working Tree · 工作区

正在编辑的代码

Stage · 暂存区

选择本次准备保存的改动

Commit · 提交版本

生成可查看、比较和恢复的历史节点

记住三个概念：

• 工作区：你正在修改的文件。
• 暂存区：你挑选出来，准备纳入下次提交的修改。
• 提交（Commit）：正式建立一个版本记录。

Git 的本地提交不会自动上传 GitHub。

二、日常最常用的命令

下面这些命令，覆盖了你大部分的日常开发工作。

1. 查看当前状态

git status

作用：查看当前分支、未跟踪文件、已修改文件、暂存文件，以及工作区是否干净。

常见结果：

nothing to commit, working tree clean

意思是：没有尚未提交的改动。

2. 查看版本历史

git log --oneline

你当前的历史是：

eb812b2 给 Stream Router JS添加作者
ffe13df NewVFX LLM version ：10.26 Author：Jisongbin

每行前面的短编号是提交 ID，可以用于查看具体版本。

想看完整提交信息：

git log

想看最近 5 次提交：

git log -5 --oneline

想查看分支历史图：

git log --oneline --graph --decorate --all

3. 查看具体版本修改了什么

你已经成功使用了这条命令：

git show eb812b2

它会显示提交说明、作者、时间，以及具体代码差异。

只查看修改了哪些文件和改动数量：

git show --stat eb812b2

只看某次提交涉及的文件名：

git diff-tree --no-commit-id --name-only -r eb812b2

4. 查看当前尚未提交的修改

git diff

显示工作区中尚未暂存的代码差异。

如果文件已经 Stage，想查看暂存区的改动：

git diff --staged

比较最近两次提交：

git diff HEAD~1 HEAD

比较任意两个版本：

git diff ffe13df eb812b2

注意：

git diff A B

比较的是两个版本之间的差异，不会修改文件。

5. 暂存和提交代码

把一个指定文件放入暂存区：

git add assets/js/nvfx-stream-router.js

把当前项目中所有符合 Git 跟踪规则的改动放入暂存区：

git add .

查看暂存状态：

git status

提交版本：

git commit -m "F01 - 修复环形图渲染"

这里的

-m

后面是提交说明。建议每次完成一个功能、修复一个问题，就提交一次。

如果你只想把部分文件纳入版本，使用指定文件的

git add

，不要直接执行

git add .

。

6. 查看某个文件的历史

例如，你想知道 Stream Router JS 以前修改过什么：

git log --oneline -- assets/js/nvfx-stream-router.js

查看该文件某次提交的修改：

git show eb812b2 -- assets/js/nvfx-stream-router.js

查看某个版本中的文件内容，但不覆盖当前文件：

git show eb812b2:assets/js/nvfx-stream-router.js

这非常适合你这种经常修改同一个核心文件的开发方式。

三、出问题时，怎样撤销或恢复？

这一部分最重要。先区分：你是否已经 Commit。

情况 A：改了文件，但还没有暂存

放弃某个文件的未暂存修改：

git restore assets/js/nvfx-stream-router.js

警告： 这会丢弃该文件自上次提交以来的未暂存修改，通常无法通过 Git 找回。执行前务必确认不需要这些改动。

情况 B：已经 Stage，但还没有 Commit

把文件从暂存区移出来：

git restore --staged assets/js/nvfx-stream-router.js

这通常只取消暂存，不会删除工作区里的代码修改。

情况 C：已经 Commit，发现新版本有问题

这是你最应该掌握的情况。

先查看历史：

git log --oneline

假设历史是：

eb812b2 给 Stream Router JS添加作者
ffe13df NewVFX LLM version ：10.26 Author：Jisongbin

如果你发现

eb812b2

这次提交不应该保留，有两种思路。

方法一：撤销某次提交，但保留完整历史。

git revert eb812b2

Git 会创建一个新的提交，用反向修改撤销该提交的改动。一般来说，这是已经共享或希望保留历史时更安全的选择。

方法二：把整个工作区恢复到旧版本。

git switch --detach ffe13df

这会进入旧提交的临时查看状态，适合测试旧版本，不会直接把

master

分支重置到旧版本。

测试结束后，回到当前分支：

git switch master

如果你希望让当前分支正式回到某个旧提交，确实可以使用

git reset

，但它可能改变分支历史并影响未保存的工作。建议先检查

git status

，并确认新提交不再需要，再学习这一步，不要盲目复制执行。

情况 D：想恢复单个文件的旧版本

例如，想把某个文件恢复成

ffe13df

版本：

git restore --source=ffe13df -- assets/js/nvfx-stream-router.js

这会把旧版本文件内容放进当前工作区，不会自动提交。确认文件内容正确后，再执行

git add

和

git commit

。

四、几个非常有用的辅助命令

git branch

git switch master

git diff --check

git status --short

git show HEAD

git rev-parse --short HEAD

git reflog

git remote -v

git reflog

尤其值得记住：当你误操作切换了提交位置时，它有时可以帮助找到之前的提交位置。但它不是永久备份，不能保证所有对象永远存在。

五、给 NewVFX AI 制定一套实际工作流程

建议以后按照这个节奏工作：

第一步：修改之前确认当前状态

git status
git log -3 --oneline

第二步：正常开发和测试

在 Pulsar 修改代码，验证图表渲染、流式路由、Word 导出等功能。

第三步：确认正常后提交

git add assets/js/nvfx-stream-router.js
git commit -m "F01 - 给 Stream Router JS 添加作者"

第四步：需要排查时查看差异

git show --stat HEAD
git show HEAD

这里的文件路径和提交说明只是示例；如果本次改动涉及多个文件，就选择相应文件一起提交。

最后给你一个记忆口诀：

status

看状态，

log

看历史，

show

看提交，

diff

看差异，

add

放暂存，

commit

存版本，

restore

撤改动，

revert

撤提交，

reflog

找位置。

掌握这几个命令，你就已经能够独立完成大多数日常 Git 版本管理工作了。