simonkoson/tps-dashboard

Fork 0

Files

T

simonkoson 2bee0ce8c8 docs: git_workflow.md 第 2/3 章路径残留 Z:\AIworks → E:\tps-dashboard 修正

2026-05-15 09:35:17 +08:00

12 KiB

Raw Blame History

docs/git_workflow.md — Git 操作手册

项目:TPS 中台仓库:tps-dashboard(单位 Gitea) 文档版本:v2 · 2026-05-14 受众:制片人(不会 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)

右上角点 + → 选 新建仓库(或英文 New Repository)
填写表单:
- 仓库名称:tps-dashboard
- 描述:TPS 中台 — 央视《军事科技》栏目内部工作台
- 可见性:勾选 "私有" 或 "团队可见"(注意:跟爱德华那个公开仓库不一样,这个不公开)
- 勾选项一定不要勾:不要勾 "Initialize Repository(With selected files and template)" —— 我们要的是空仓库
点底部 创建仓库

成功标志:页面跳到一个新页面,显示 tps-dashboard 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准):

git clone http://localhost:3000/simonkoson/tps-dashboard.git

把这一行复制下来,下一步要用。

2.2 在本地 clone 仓库

操作位置:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 Ctrl + `)

# 切换到你想放项目的位置
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 进仓库目录

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 资源管理器):

在 E:\tps-dashboard\ 下:
- 直接拷入 .clinerules、project_plan.md、dev_plan.md、README.md(平铺四份)
在 E:\tps-dashboard\ 下新建文件夹 docs,把 git_workflow.md 拷进去
在 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 终端里执行:

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 看到了哪些文件

git status

成功标志:终端会列出一堆文件(.clinerules、project_plan.md 等),颜色应该是红色(表示"未跟踪")。

第 2 条:把所有文件加进暂存区

git add -A

成功标志:命令执行无任何输出(Git 的传统是"没消息就是好消息")。再跑一次 git status,文件应该变成绿色了。

第 3 条:第一次 commit

git commit -m "chore: 项目宪法五件套 + Phase 1 家用机日志初始化"

成功标志:终端显示类似:

[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
 6 files changed, 1234 insertions(+)
 create mode 100644 .clinerules
 ...

第 4 条:推送到 Gitea

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 每天开工第一件事

cd E:\tps-dashboard\
git status                # 看看本地有没有未提交的改动
git pull                  # 拉 Gitea 最新(如果别的机器推过)

3.2 每次离开机器前

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 你自己手工提交(备选)

cd E:\tps-dashboard\
git add -A
git commit -m "fix: 修复登录页跳转问题"
git push

3.5 Phase 收尾仪式(打 tag)

每完成一个 Phase,让 Cline 替你做这一套动作:

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 永远禁止

第 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:换了一台机器,怎么把代码搞过来

cd E:\tps-dashboard\
git clone http://localhost:3000/simonkoson/tps-dashboard.git
cd tps-dashboard
# 然后跟原来一样开工就行

Q6:某次 commit 写错了想撤回

只在最近一次 commit 还没 push 时可撤回:

git reset HEAD~1     # 撤回最近一次 commit,文件改动保留

已经 push 的 commit:不要自行处理,找 Claude Opus 4.7。

第 7 章:多设备同步(已废弃)

⚠️ 2026-05-14 更新:家用机已于 2026-05-14 退役,项目统一在单位 4090D 开发。本章描述的多设备同步模式已废弃,保留仅供历史参考。当前工作流:单一开发机,每日开工 git pull,离开前 git push。

7.1 历史模式(已废弃)

离开 A 机器前

git status         # 看有没有未提交的
git add -A         # 加进暂存
git commit -m "..."
git push

到 B 机器开工

git pull           # 拉最新
git status         # 确认干净
# 开始干活

铁律:永远在 push 之前 pull,永远在开工前 pull。这两条做到,99% 不会冲突。

第 8 章:版本演进

版本	日期	变化
v1	2026-05-06	初版
v2	2026-05-14	项目目录从 NAS(Z:\AIworks)迁移至本地 SSD(E:\tps-dashboard);家用机退役,唯一开发环境为单位 4090D;Phase 2 起 MiniMax M2.7 正式日常使用;更新版本演进记录

本文件与 .clinerules 第七章互为补充。Cline 必须遵守第 4-5 章规则。

12 KiB Raw Blame History

docs/git_workflow.md — Git 操作手册

阅读说明

第 1 章:基础概念(只讲能用上的)

1.1 三个核心概念,一分钟搞定

1.2 用菜场买菜类比

第 2 章:首次仓库初始化(Phase 0 Day 1 下午做)

2.1 在 Gitea 创建新仓库

2.2 在本地 clone 仓库

2.3 进仓库目录

2.4 把五件套 + log 拷进来

2.5 创建 .gitignore

2.6 第一次 commit 和 push

2.7 验证:浏览器看 Gitea

第 3 章:日常使用(每天会用到的命令)

3.1 每天开工第一件事

3.2 每次离开机器前

3.3 让 Cline 帮你提交

3.4 你自己手工提交(备选)

3.5 Phase 收尾仪式(打 tag)

第 4 章:commit message 规范(给 Cline 守的规矩)

4.1 格式

4.2 type 取值表

4.3 提交时机

第 5 章:Cline 的 Git 边界(给 AI 守的规矩)

5.1 Cline 可以自动执行(无需问用户)

5.2 Cline 必须停下问用户

5.3 永远禁止

第 6 章:常见问题速查

Q1:我推不上去,提示"Permission denied"

Q2:git push 时提示"rejected,请先 pull"

Q3:git status 看到一堆 .pyc 或 node_modules

Q4:不小心 commit 了 .env 文件怎么办

Q5:换了一台机器,怎么把代码搞过来

Q6:某次 commit 写错了想撤回

第 7 章:多设备同步(已废弃)

7.1 历史模式(已废弃)

离开 A 机器前

到 B 机器开工

第 8 章:版本演进

12 KiB

Raw Blame History

Q2:`git push` 时提示"rejected,请先 pull"

Q3:`git status` 看到一堆 .pyc 或 node_modules