Git 最佳实践

Thu, 07 May 2026 00:00:00 +0000

1. Git 要解决什么问题

版本可追溯：你能知道每次改了什么。
可回滚：系统改坏了能立即回到稳定节点。
分支隔离：功能迭代不污染主线（main）。
只提交代码：不把运行缓存、数据库、视频、截图、依赖目录提交进仓库（靠 .gitignore）。

2. 初始状态检查

刚开始时你可能处于：

在 main 分支
没有 commit
文件为 Untracked（未纳入版本管理）

下一步要做的是： .gitignore → git add . → git commit → git tag → git checkout -b

3. 必备：.gitignore

目的：避免提交运行产生的垃圾文件（例如构建产物、node_modules、SQLite、上传视频、截图等）。

3.1 检查 `.gitignore` 是否生效

在项目根目录执行：

`1`	`git status`

你不应该看到这些被 Git 追踪：

node_modules/
.next/ 或其他构建产物目录
数据库/上传/截图等运行时数据目录

3.2 如果发现上述目录出现在 status 里（被追踪了）

说明这些文件可能在 .gitignore 生效之前已经被 Git 记录过。用下面命令"从 Git 里移除追踪，但保留本地文件"：

1
2
3

git rm -r --cached node_modules .next data || true
git add .
git commit -m "chore: stop tracking generated/runtime files"

4. 建立第一个"稳定节点"（baseline checkpoint）

4.1 初始化仓库（若还没执行过）

`1`	`git init`

4.2 将当前版本加入暂存区

`1`	`git add .`

4.3 检查将提交内容（推荐必做）

`1`	`git status`

4.4 创建第一次提交（基线）

`1`	`git commit -m "checkpoint: runnable baseline"`

5. 打标签：做"回滚锚点"

标签（tag）= 你的"存档点"，以后随时可回到这个版本。

5.1 给当前提交打标签

`1`	`git tag v0.1-checkpoint`

5.2 查看标签是否存在

git tag

5.3 查看最近提交（带标签信息）

`1`	`git log --oneline --decorate -10`

6. 分支策略

规则

main：保持稳定、可演示的版本
feature/*：所有新功能/大改动在功能分支做
需要里程碑就打 tag（例如 v0.2 / v0.3）

6.1 创建并切换到功能分支

`1`	`git checkout -b feature/ui-upgrades`

6.2 查看当前分支

`1`	`git branch`

7. 日常工作流

7.1 每次开始一个新功能

从 main 拉一个新分支：

1
2

git checkout main
git checkout -b feature/<task-name>

示例：

`1`	`git checkout -b feature/alert-snapshots`

7.2 开发过程中查看改动

1
2

git status
git diff

7.3 分阶段提交

不要憋成一次超大提交：

1
2

git add .
git commit -m "feat: improve analysis UI"

7.4 完成一个里程碑，打标签（可选）

`1`	`git tag v0.2-ui-polish`

8. 回滚方式

8.1 推荐回滚：从某个 tag 开新分支继续开发（最安全）

不会破坏现有分支，也不会丢历史：

`1`	`git checkout -b rollback-from-v0.1 v0.1-checkpoint`

8.2 只"查看"某个 tag 的版本（不建议长期停留）

`1`	`git checkout v0.1-checkpoint`

注意：这会进入 “detached HEAD” 状态。若要继续开发，请开分支：

`1`	`git checkout -b hotfix/from-v0.1 v0.1-checkpoint`

8.3 强制把当前分支回到某个 tag（慎用：会丢未提交内容）

`1`	`git reset --hard v0.1-checkpoint`

若有未提交改动又不想丢，先 stash：

1
2
3

git stash -u
git reset --hard v0.1-checkpoint
git stash pop

9. 推荐 tag 命名

v0.1-checkpoint：系统跑通
v0.2-alert-snapshots：告警证据截图可用
v0.3-ui-pro：UI 升级到高级控制台
v1.0-demo-ready：最终可演示/可答辩版本

10. 可选：接入远端仓库

如果后面想同步到 GitHub/Gitee：

10.1 添加远端

`1`	`git remote add origin <your-repo-url>`

10.2 推送 main 和 tags

1
2

git push -u origin main
git push --tags

11. 最常用命令速查

git status
git diff
git add .
git commit -m "..."
git checkout -b feature/xxx
git log --oneline --decorate -10
git tag v0.x-xxx
git checkout -b rollback-from-tag <tagname>

Git on Xiang's Blog