simonkoson
501 lines
14 KiB
Markdown
501 lines
14 KiB
Markdown
# docs/git_workflow.md — Git 操作手册
|
||
|
||
> 项目:TPS 中台
|
||
> 仓库:`tps-dashboard`(腾讯云 Gitea: http://101.42.29.217:3000/simonkoson/tps-dashboard）
|
||
> 文档版本:v3 · 2026-07-03
|
||
> 受众:**制片人(不会 Git)** + Cline(自动遵守此规则)
|
||
|
||
---
|
||
|
||
## 阅读说明
|
||
|
||
本手册分两部分:
|
||
|
||
- **第 1-3 章**:**给制片人看的**——每一步具体到敲哪条命令、看到什么算成功
|
||
- **第 4-5 章**:**给 Cline 看的规则**——commit 规范、提交时机、Cline 的边界
|
||
|
||
不会 Git 没关系——**照本宣科,你只需要会复制粘贴**。
|
||
|
||
---
|
||
|
||
## 第 1 章:基础概念(只讲能用上的)
|
||
|
||
### 1.1 三个核心概念,一分钟搞定
|
||
|
||
**Git 仓库**:就是一个"被 Git 管起来的文件夹"。打开本地 `E:\tps-dashboard\` 这个文件夹,里面有所有项目文件 + 一个隐藏的 `.git` 子目录。**不要删 `.git`**,删了等于把保险撕了。
|
||
|
||
**commit(提交)**:相当于"存档"。每一次 commit 是一个时间点的快照,以后可以回到这个时间点。
|
||
|
||
**push(推送)**:把本地的 commit 同步到 Gitea 服务器。**push 之后才算"上传"了**,不 push 同事看不到。
|
||
|
||
**pull(拉取)**:把 Gitea 上的最新代码拉到本地。多设备开发时,**每天开工第一件事就是 pull**。
|
||
|
||
### 1.2 用菜场买菜类比
|
||
|
||
- 在家做饭(写代码)= 本地修改
|
||
- 用保鲜盒装好放冰箱(commit) = 本地存档
|
||
- 把保鲜盒带去单位食堂大冰柜(push) = 推到 Gitea
|
||
- 同事来食堂找出你的盒子带回家(pull) = 拉到他自己电脑
|
||
|
||
只要保鲜盒进了食堂大冰柜,谁来都能拿。
|
||
|
||
---
|
||
|
||
## 第 2 章:首次仓库初始化(Phase 0 Day 1 下午做)
|
||
|
||
> 单位 4090D 已装 Git、已配 用户名+邮箱(爱德华项目时弄好)。本章从创建新仓库开始。
|
||
|
||
### 2.1 在 Gitea 创建新仓库
|
||
|
||
**操作位置**:浏览器打开单位 Gitea 网址(就是你登爱德华项目的那个 Gitea)
|
||
|
||
1. 右上角点 `+` → 选 `新建仓库`(或英文 `New Repository`)
|
||
2. 填写表单:
|
||
- **仓库名称**:`tps-dashboard`
|
||
- **描述**:`TPS 中台 — 央视《军事科技》栏目内部工作台`
|
||
- **可见性**:勾选 **"私有"** 或 **"团队可见"**(注意:跟爱德华那个公开仓库**不一样**,这个不公开)
|
||
- **勾选项一定不要勾**:**不要勾** "Initialize Repository(With selected files and template)" —— 我们要的是空仓库
|
||
3. 点底部 `创建仓库`
|
||
|
||
**成功标志**:页面跳到一个新页面,显示 `tps-dashboard` 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准):
|
||
|
||
```
|
||
git clone http://localhost:3000/simonkoson/tps-dashboard.git
|
||
```
|
||
|
||
**把这一行复制下来,下一步要用**。
|
||
|
||
### 2.2 在本地 clone 仓库
|
||
|
||
**操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `)
|
||
|
||
```powershell
|
||
# 切换到你想放项目的位置
|
||
cd E:\tps-dashboard\
|
||
|
||
# 把刚才复制的 clone 命令粘贴运行
|
||
git clone http://localhost:3000/simonkoson/tps-dashboard.git
|
||
```
|
||
|
||
**期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。
|
||
|
||
**成功标志**:终端显示类似:
|
||
```
|
||
Cloning into 'tps-dashboard'...
|
||
warning: You appear to have cloned an empty repository.
|
||
done.
|
||
```
|
||
|
||
`warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。
|
||
|
||
完成后 `E:\tps-dashboard\` 下多了一个 `tps-dashboard` 文件夹。
|
||
|
||
### 2.3 进仓库目录
|
||
|
||
```powershell
|
||
cd E:\tps-dashboard\
|
||
```
|
||
|
||
之后所有 git 命令都在这个目录里跑。
|
||
|
||
### 2.4 把五件套 + log 拷进来
|
||
|
||
> 你应该已经从 Claude.ai 下载了这五份文件:`.clinerules`、`project_plan.md`、`dev_plan.md`、`docs/git_workflow.md`、`README.md`,加上 `logs/phase1_log.md`。
|
||
|
||
**手动操作**(用 Windows 资源管理器):
|
||
|
||
1. 在 `E:\tps-dashboard\` 下:
|
||
- 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
|
||
|
||
2. 在 `E:\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去
|
||
|
||
3. 在 `E:\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去
|
||
|
||
**最终结构应该是**:
|
||
|
||
```
|
||
E:\tps-dashboard\
|
||
├── .clinerules
|
||
├── project_plan.md
|
||
├── dev_plan.md
|
||
├── README.md
|
||
├── docs\
|
||
│ └── git_workflow.md
|
||
└── logs\
|
||
└── phase1_log.md
|
||
```
|
||
|
||
### 2.5 创建 .gitignore
|
||
|
||
`.gitignore` 是"告诉 Git 哪些文件不要管"的清单。
|
||
|
||
**操作**:在 VS Code 终端里执行:
|
||
|
||
```powershell
|
||
cd E:\tps-dashboard\
|
||
notepad .gitignore
|
||
```
|
||
|
||
记事本会弹出来(可能问你"找不到文件,要创建吗?"——选 **是**)。
|
||
|
||
把下面这些粘贴进去,**保存**:
|
||
|
||
```
|
||
# Python
|
||
__pycache__/
|
||
*.pyc
|
||
*.pyo
|
||
*.pyd
|
||
.venv/
|
||
venv/
|
||
env/
|
||
|
||
# Node
|
||
node_modules/
|
||
dist/
|
||
build/
|
||
.vite/
|
||
|
||
# 环境配置(永远不上传)
|
||
.env
|
||
.env.local
|
||
|
||
# 编辑器
|
||
.vscode/
|
||
.idea/
|
||
*.swp
|
||
|
||
# 操作系统
|
||
.DS_Store
|
||
Thumbs.db
|
||
|
||
# 日志运行产物
|
||
*.log
|
||
cookie.txt
|
||
|
||
# 临时文件
|
||
*.tmp
|
||
*.bak
|
||
```
|
||
|
||
### 2.6 第一次 commit 和 push
|
||
|
||
**操作**:VS Code 终端里依次执行:
|
||
|
||
**第 1 条:看看 Git 看到了哪些文件**
|
||
|
||
```powershell
|
||
git status
|
||
```
|
||
|
||
**成功标志**:终端会列出一堆文件(.clinerules、project_plan.md 等),颜色应该是**红色**(表示"未跟踪")。
|
||
|
||
**第 2 条:把所有文件加进暂存区**
|
||
|
||
```powershell
|
||
git add -A
|
||
```
|
||
|
||
**成功标志**:命令执行无任何输出(Git 的传统是"没消息就是好消息")。再跑一次 `git status`,文件应该变成**绿色**了。
|
||
|
||
**第 3 条:第一次 commit**
|
||
|
||
```powershell
|
||
git commit -m "chore: 项目宪法五件套 + Phase 1 家用机日志初始化"
|
||
```
|
||
|
||
**成功标志**:终端显示类似:
|
||
```
|
||
[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
|
||
6 files changed, 1234 insertions(+)
|
||
create mode 100644 .clinerules
|
||
...
|
||
```
|
||
|
||
**第 4 条:推送到 Gitea**
|
||
|
||
```powershell
|
||
git push -u origin main
|
||
```
|
||
|
||
> 如果你的 Gitea 默认分支不叫 main 而叫 master,把命令里的 `main` 换成 `master`。
|
||
|
||
**期间可能要求输入 Gitea 账号密码**,输入即可。
|
||
|
||
**成功标志**:终端显示类似:
|
||
```
|
||
Enumerating objects: ...
|
||
Writing objects: 100% (...)
|
||
To http://localhost:3000/simonkoson/tps-dashboard.git
|
||
* [new branch] main -> main
|
||
branch 'main' set up to track 'origin/main'.
|
||
```
|
||
|
||
### 2.7 验证:浏览器看 Gitea
|
||
|
||
刷新一下 Gitea 那个 `tps-dashboard` 页面——**应该能看到所有文件出现了**,不再是空仓库。
|
||
|
||
**到此 Phase 0 Day 1 下午的 Git 部分完成**。继续 Day 2 装 VS Code + Cline。
|
||
|
||
---
|
||
|
||
## 第 3 章:日常使用(每天会用到的命令)
|
||
|
||
### 3.1 每天开工第一件事
|
||
|
||
```powershell
|
||
cd E:\tps-dashboard\
|
||
git status # 看看本地有没有未提交的改动
|
||
git pull # 拉 Gitea 最新(如果别的机器推过)
|
||
```
|
||
|
||
### 3.2 每次离开机器前
|
||
|
||
```powershell
|
||
git status # 看看有没有未提交的
|
||
# 如果有改动,让 Cline 自己 commit + push;
|
||
# 或者你手工(下面)
|
||
```
|
||
|
||
### 3.3 让 Cline 帮你提交
|
||
|
||
最方便的方式——**让 MiniMax M2.7 在 Plan 里下命令**:
|
||
|
||
> "现在改完了,请帮我 commit + push,commit message 写: feat: 添加 XXX 功能"
|
||
|
||
Cline(MiniMax M2.7)会自动跑 git add / git commit / git push。**这是默认推荐方式**。
|
||
|
||
### 3.4 你自己手工提交(备选)
|
||
|
||
```powershell
|
||
cd E:\tps-dashboard\
|
||
git add -A
|
||
git commit -m "fix: 修复登录页跳转问题"
|
||
git push
|
||
```
|
||
|
||
### 3.5 Phase 收尾仪式(打 tag)
|
||
|
||
每完成一个 Phase,**让 Cline 替你做这一套动作**:
|
||
|
||
```powershell
|
||
git tag -a phase1-complete -m "Phase 1 后端 + 前端骨架完工"
|
||
git push origin phase1-complete
|
||
```
|
||
|
||
**tag 命名规则**(`.clinerules` 第 7.4 节锁定):
|
||
|
||
- `phase0-env-ready`
|
||
- `phase1-complete`
|
||
- `phase2-dashboard-done`
|
||
- `phase3-knowledge-base`
|
||
- `phase4a-mvp-launch` ← **这是项目第一次对内发布,郑重一点**
|
||
- `phase4b-tps-complete`
|
||
- `phase4c-radar`
|
||
- `phase5-production` ← **这是项目正式上线**
|
||
|
||
---
|
||
|
||
## 第 4 章:commit message 规范(给 Cline 守的规矩)
|
||
|
||
### 4.1 格式
|
||
|
||
```
|
||
<type>: <中文正文>
|
||
|
||
[可选:更详细的中文说明]
|
||
```
|
||
|
||
### 4.2 type 取值表
|
||
|
||
| type | 中文 | 示例 |
|
||
|---|---|---|
|
||
| `feat` | 新功能 | `feat: 添加用户登录接口` |
|
||
| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 报错` |
|
||
| `docs` | 改文档 | `docs: 更新 phase1_log` |
|
||
| `chore` | 杂项(依赖、配置)| `chore: 升级 bcrypt 到 4.0.1` |
|
||
| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
|
||
| `style` | 格式化(空格/缩进)| `style: 统一前端缩进为 2 空格` |
|
||
| `test` | 加测试 | `test: 添加 auth 接口测试` |
|
||
|
||
**前缀英文小写,正文中文**——前缀方便工具分类,正文方便人阅读。
|
||
|
||
### 4.3 提交时机
|
||
|
||
每个独立动作单独 commit,**不要堆一坨大 commit**:
|
||
|
||
- 装完依赖 → 立刻 commit
|
||
- 建完 SQL 表 → 立刻 commit
|
||
- 写完一个完整接口 → 立刻 commit
|
||
- 修完一个 bug → 立刻 commit
|
||
|
||
**禁止**:"晚上一起 commit"或"一个 commit 多功能"。
|
||
|
||
---
|
||
|
||
## 第 5 章:Cline 的 Git 边界(给 AI 守的规矩)
|
||
|
||
### 5.1 Cline 可以自动执行(无需问用户)
|
||
|
||
- `git add`
|
||
- `git commit`
|
||
- `git push`(限当前分支)
|
||
- `git pull`
|
||
- `git status`
|
||
- `git log`(查看历史)
|
||
- `git tag -a` + `git push origin <tag>`
|
||
|
||
### 5.2 Cline 必须停下问用户
|
||
|
||
- `git reset --hard`(任何形式的 hard reset)
|
||
- `git push --force` / `git push -f`
|
||
- `git rebase`(任何形式)
|
||
- 删除分支:`git branch -d` / `git branch -D`
|
||
- 删除 tag:`git tag -d` / `git push origin --delete <tag>`
|
||
- 删除远程引用
|
||
|
||
### 5.3 永远禁止
|
||
|
||
- 删除整个 `.git/` 目录
|
||
- 修改 `.git/` 目录内任何文件
|
||
|
||
---
|
||
|
||
## 第 6 章:常见问题速查
|
||
|
||
### Q1:我推不上去,提示"Permission denied"
|
||
|
||
**原因**:Gitea 账号密码错或没权限
|
||
**解决**:确认你登录 Gitea 网页版能正常访问 `tps-dashboard` 仓库;如果能,重新输入账号密码即可。
|
||
|
||
### Q2:`git push` 时提示"rejected,请先 pull"
|
||
|
||
**原因**:Gitea 上有别的设备推过新内容,本地落后了
|
||
**解决**:先 `git pull`,再 `git push`。如果 pull 时报 conflict(冲突),停下问 Cline 或我。
|
||
|
||
### Q3:`git status` 看到一堆 .pyc 或 node_modules
|
||
|
||
**原因**:`.gitignore` 没生效
|
||
**解决**:确认 `.gitignore` 文件就在仓库根目录(`D:\tps-dashboard\.gitignore`),内容跟第 2.5 节一致。
|
||
|
||
### Q4:不小心 commit 了 .env 文件怎么办
|
||
|
||
**严重**:`.env` 含密码,绝不能进 Gitea。
|
||
**解决**:**立刻停下找 Claude Opus 4.7 处理**——这事儿要小心做,不要自己瞎搞,容易把历史搞乱。
|
||
|
||
### Q5:换了一台机器,怎么把代码搞过来
|
||
|
||
```powershell
|
||
# 在新机器上 clone 云端仓库
|
||
git clone http://101.42.29.217:3000/simonkoson/tps-dashboard.git
|
||
cd tps-dashboard
|
||
# 然后按第 7 章流程开工
|
||
```
|
||
|
||
### Q6:某次 commit 写错了想撤回
|
||
|
||
**只在最近一次 commit 还没 push 时可撤回**:
|
||
|
||
```powershell
|
||
git reset HEAD~1 # 撤回最近一次 commit,文件改动保留
|
||
```
|
||
|
||
**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。
|
||
|
||
---
|
||
|
||
## 第 7 章:双机开发同步(单位 + 家里)
|
||
|
||
> **2026-07-03 恢复**:项目远程仓库迁至腾讯云 Gitea,单位和家里两台电脑均可开发。
|
||
|
||
### 7.0 仓库架构
|
||
|
||
| 项目 | 云端地址 | 说明 |
|
||
|---|---|---|
|
||
| **TPS 工作台(主项目)** | `http://101.42.29.217:3000/simonkoson/tps-dashboard.git` | 所有主干代码 + doco/ai-labeling 等子项目目录 |
|
||
| **配音工具** | `http://101.42.29.217:3000/simonkoson/military-tech-voice3.0.git` | 独立小应用,将来作为 tps-dashboard 子功能合入 |
|
||
|
||
云端 Gitea 用户名统一 `simonkoson`。
|
||
|
||
### 7.1 每天开工铁律(无论在哪台电脑)
|
||
|
||
```powershell
|
||
cd E:\tps-dashboard\ # 单位机路径;家里机路径按实际调整
|
||
git pull # 拉云端最新代码
|
||
git status # 确认本地干净,无冲突
|
||
# 开始干活
|
||
```
|
||
|
||
### 7.2 离开机器前铁律
|
||
|
||
```powershell
|
||
git status # 确认改动
|
||
git add -A # 暂存所有
|
||
git commit -m "feat/fix/...: 改了什么"
|
||
git push # 推到云端
|
||
```
|
||
|
||
**不 push 就关机 = 另一台电脑拿不到你的改动,下次必出冲突。**
|
||
|
||
### 7.3 换到另一台电脑
|
||
|
||
```powershell
|
||
git pull # 先拉最新
|
||
git status # 确认干净
|
||
# 正常开发
|
||
```
|
||
|
||
### 7.4 铁律三条(Cline 和人都必须守)
|
||
|
||
1. **开工先 pull** — 每次打开项目第一条命令就是 `git pull`
|
||
2. **收工必 push** — 做完改动 commit 后必须 push,不过夜
|
||
3. **push 前先 pull** — 防止另一台机器推过内容导致冲突
|
||
|
||
做到这三条,99% 不会冲突。万一冲突,**停下来找 Claude 处理,不要自己瞎搞**。
|
||
|
||
### 7.5 家里电脑首次克隆(只做一次)
|
||
|
||
```powershell
|
||
cd D:\myApp\lanhao2.0 # 家里机器的工作目录(按实际调整)
|
||
git clone http://101.42.29.217:3000/simonkoson/tps-dashboard.git
|
||
cd tps-dashboard
|
||
# 克隆完毕,以后按 7.1-7.3 流程开发
|
||
```
|
||
|
||
克隆时会要求输入 Gitea 用户名密码(simonkoson / 你的密码)。
|
||
|
||
### 7.6 .gitignore 不入库的文件(两台电脑都适用)
|
||
|
||
以下文件/目录**永远不推到云端**,只存在本地:
|
||
- `.env` / `.env.local`(密码密钥)
|
||
- `node_modules/` / `.venv/`(依赖,各机器自己装)
|
||
- `*.mp4` / `*.mov` / `*.psd`(大文件)
|
||
- `*.dump`(数据库备份)
|
||
- `backup_before_*.dump`(迁移备份)
|
||
- 各种中间产物(详见 `.gitignore`)
|
||
|
||
**家里电脑 clone 后需要自己装依赖**:
|
||
```powershell
|
||
# 前端
|
||
cd frontend && npm install
|
||
|
||
# 后端
|
||
cd backend && python -m venv .venv
|
||
.venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 第 8 章:版本演进
|
||
|
||
| 版本 | 日期 | 变化 |
|
||
|---|---|---|
|
||
| v1 | 2026-05-06 | 初版 |
|
||
| v2 | 2026-05-14 | 项目目录从 NAS(Z:\AIworks\)迁移至本地 SSD(E:\tps-dashboard\);家用机退役,唯一开发环境为单位 4090D;Phase 2 起 MiniMax M2.7 正式日常使用 |
|
||
| **v3** | **2026-07-03** | **远程仓库从本地 Gitea(localhost:3000) 迁至腾讯云 Gitea(101.42.29.217:3000);恢复双机开发模式(单位+家里);git 历史清理大文件(mp4/psd);.gitignore 加强** |
|
||
|
||
---
|
||
|
||
*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*
|