simonkoson/tps-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
31fb490b6d186f7656de09c1324052de67a54737
tps-dashboard/docs/git_workflow.md
T

439 lines
11 KiB
Markdown
Raw Blame History

# docs/git_workflow.md — Git 操作手册
> 项目:TPS 中台
> 仓库:`tps-dashboard`(单位 Gitea)
> 文档版本:v1 · 2026-05-06
> 受众:**制片人(不会 Git)** + Cline(自动遵守此规则)
---
## 阅读说明
本手册分两部分:
- **第 1-3 章**:**给制片人看的**——每一步具体到敲哪条命令、看到什么算成功
- **第 4-5 章**:**给 Cline 看的规则**——commit 规范、提交时机、Cline 的边界
不会 Git 没关系——**照本宣科,你只需要会复制粘贴**。
---
## 第 1 章:基础概念(只讲能用上的)
### 1.1 三个核心概念,一分钟搞定
**Git 仓库**:就是一个"被 Git 管起来的文件夹"。打开本地 `D:\TPS-中台\` 这个文件夹,里面有所有项目文件 + 一个隐藏的 `.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 Z:\AIworks\
# 把刚才复制的 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` 是**正常的**——本来就是空仓库,不是错误。
完成后 `Z:\AIworks\` 下多了一个 `tps-dashboard` 文件夹。
### 2.3 进仓库目录
```powershell
cd Z:\AIworks\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. 在 `Z:\AIworks\tps-dashboard\` 下:
- 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
2. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去
3. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去
**最终结构应该是**:
```
Z:\AIworks\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 Z:\AIworks\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 Z:\AIworks\tps-dashboard
git status # 看看本地有没有未提交的改动
git pull # 拉 Gitea 最新(如果别的机器推过)
```
### 3.2 每次离开机器前
```powershell
git status # 看看有没有未提交的
# 如果有改动,让 Cline 自己 commit + push;
# 或者你手工(下面)
```
### 3.3 让 Cline 帮你提交
最方便的方式——**让 Sonnet 在 Plan 里下命令**:
> "现在改完了,请帮我 commit + push,commit message 写: feat: 添加 XXX 功能"
Cline(Sonnet → DeepSeek)会自动跑 git add / git commit / git push。**这是默认推荐方式**。
### 3.4 你自己手工提交(备选)
```powershell
cd Z:\AIworks\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
cd Z:\AIworks\tps-dashboard
git clone http://localhost:3000/simonkoson/tps-dashboard.git
cd tps-dashboard
# 然后跟原来一样开工就行
```
### Q6:某次 commit 写错了想撤回
**只在最近一次 commit 还没 push 时可撤回**:
```powershell
git reset HEAD~1 # 撤回最近一次 commit,文件改动保留
```
**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。
---
## 第 7 章:多设备同步(家用机 ↔ 单位机)
### 离开 A 机器前
```powershell
git status # 看有没有未提交的
git add -A # 加进暂存
git commit -m "..."
git push
```
### 到 B 机器开工
```powershell
git pull # 拉最新
git status # 确认干净
# 开始干活
```
**铁律**:**永远在 push 之前 pull**,永远在开工前 pull。这两条做到,99% 不会冲突。
---
## 第 8 章:版本演进
| 版本 | 日期 | 变化 |
|---|---|---|
| v1 | 2026-05-06 | 初版 |
---
*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*
Reference in New Issue View Git Blame Copy Permalink