メニュー
当用户要求“create git commit”、“manage branches”、“follow git workflow”、“use Conventional Commits”、“handle merge conflicts”，或询问 Git 分支策略、版本控制最佳实践、Pull Request 流程时使用。该 skill 提供面向团队协作的完整 Git workflow 指南。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | git-workflow |
| description | 当用户要求“create git commit”、“manage branches”、“follow git workflow”、“use Conventional Commits”、“handle merge conflicts”，或询问 Git 分支策略、版本控制最佳实践、Pull Request 流程时使用。该 skill 提供面向团队协作的完整 Git workflow 指南。 |
| version | 1.2.0 |
本文定义项目的 Git 使用标准，包括 commit message 格式、branch 管理策略、工作流、merge 策略等。遵循这些标准可以提升协作效率、增强可追溯性、支持自动化并减少冲突。
项目遵循 Conventional Commits 规范：
<type>(<scope>): <subject>
<body>
<footer>
| Type | Description | Example |
|---|---|---|
feat | 新功能 | feat(user): add user export functionality |
fix | Bug 修复 | fix(login): fix captcha not refreshing |
docs | 文档更新 | docs(api): update API documentation |
refactor | 重构 | refactor(utils): refactor utility functions |
perf | 性能优化 | perf(list): optimize list performance |
test | 测试相关 | test(user): add unit tests |
chore | 其他变更 | chore: update dependency versions |
add、fix、update、remove、optimize更细的规范和示例见 references/commit-conventions.md。
| Branch Type | Naming Convention | Description | Lifecycle |
|---|---|---|---|
| master | master | 主分支，可发布状态 | 长期存在 |
| develop | develop | 开发分支，集成最新代码 | 长期存在 |
| feature | feature/feature-name | 功能分支 | 完成后删除 |
| bugfix | bugfix/issue-description | Bug 修复分支 | 修复后删除 |
| hotfix | hotfix/issue-description | 紧急修复分支 | 修复后删除 |
| release | release/version-number | 发布分支 | 发布后删除 |
feature/user-management # 用户管理功能
feature/123-add-export # 关联 issue 的功能分支
bugfix/login-error # 登录错误修复
hotfix/security-vulnerability # 安全漏洞紧急修复
release/v1.0.0 # 版本发布
当任务涉及科研代码、实验配置、ablation、分析报告或论文材料时，同时使用 project-layout-governance 判断文件放置和 artifact Git policy。
| Branch Type | Naming Convention | Use When | Notes |
|---|---|---|---|
| feature | feat/<short-slug> | 可复用模型组件、训练能力、数据管线或 CLI 能力 | 对应源码、测试、配置应可合并回主线 |
| fix | fix/<short-slug> | 修复训练、评估、数据或报告生成 bug | 记录验证命令和受影响实验 |
| experiment | exp/<experiment-slug> | 探索性实验、baseline、ablation 或大幅配置/代码试验 | 与 EXP-* package 或 tracker run 对齐 |
| analysis | analysis/<experiment-slug> | post-run 统计、figure、结果报告，不改训练逻辑 | 引用稳定 run id 和 artifact path |
| paper | paper/<short-slug> | manuscript-facing 图表、表格、写作材料 | 不混入未验证实验改动 |
推荐使用 git worktree 的场景：
exp/* 分支需要同时运行或检查，不能频繁切换工作区。Git 只隔离代码状态和决策历史；实验事实、metrics、artifact 路径仍应写入 experiment package、tracker 或 manifest。不要把大型 checkpoint、完整日志、raw/processed data 直接提交到普通 Git，除非项目明确使用 Git LFS/DVC 管理。
master 分支：
develop 分支：
详细分支策略见 references/branching-strategies.md。
# 1. 同步最新代码
git checkout develop
git pull origin develop
# 2. 创建 feature branch
git checkout -b feature/user-management
# 3. 开发并提交
git add .
git commit -m "feat(user): add user list page"
# 4. 推送到远端
git push -u origin feature/user-management
# 5. 创建 Pull Request 并请求 Code Review
# 6. 通过 PR 合并到 develop
# 7. 删除 feature branch
git branch -d feature/user-management
git push origin -d feature/user-management
# 1. 从 master 创建修复分支
git checkout master
git pull origin master
git checkout -b hotfix/critical-bug
# 2. 修复并提交
git add .
git commit -m "fix(auth): fix authentication bypass vulnerability"
# 3. 合并到 master
git checkout master
git merge --no-ff hotfix/critical-bug
git tag -a v1.0.1 -m "hotfix: fix authentication bypass vulnerability"
git push origin master --tags
# 4. 回同步到 develop
git checkout develop
git merge --no-ff hotfix/critical-bug
git push origin develop
# 1. 创建 release branch
git checkout develop
git checkout -b release/v1.0.0
# 2. 更新版本号和文档
# 3. 提交版本更新
git add .
git commit -m "chore(release): prepare release v1.0.0"
# 4. 合并到 master
git checkout master
git merge --no-ff release/v1.0.0
git tag -a v1.0.0 -m "release: v1.0.0 official release"
git push origin master --tags
# 5. 回同步到 develop
git checkout develop
git merge --no-ff release/v1.0.0
git push origin develop
| Feature | Merge | Rebase |
|---|---|---|
| History | 保留完整历史 | 线性历史 |
| Use case | 公共分支 | 私有分支 |
| Recommended for | 合并到主分支 | 同步上游代码 |
rebasemerge --no-ffmerge --no-ff# ✅ 推荐：feature branch 同步 develop
git checkout feature/user-management
git rebase develop
# ✅ 推荐：feature branch 合并到 develop
git checkout develop
git merge --no-ff feature/user-management
# ❌ 不推荐：在公共分支上 rebase
git checkout develop
git rebase feature/xxx # 危险操作
项目约定： feature branch 合并时统一使用 --no-ff，保留分支历史。
详细 merge 策略见 references/merge-strategies.md。
<<<<<<< HEAD
// Current branch code
const name = 'Alice'
=======
// Branch being merged
const name = 'Bob'
>>>>>>> feature/user-management
# 1. 查看冲突文件
git status
# 2. 手工编辑文件解决冲突
# 3. 标记为已解决
git add <file>
# 4. 完成 merge / rebase
git commit
# 或
git rebase --continue
# 保留当前分支版本
git checkout --ours <file>
# 保留传入分支版本
git checkout --theirs <file>
# 中止 merge / rebase
git merge --abort
git rebase --abort
更详细的冲突处理见 references/conflict-resolution.md。
# 忽略所有 .log 文件
*.log
# 忽略目录
node_modules/
# 忽略根目录下的目录
/temp/
# 忽略所有目录中的文件
**/.env
# 不忽略特定文件
!.gitkeep
node_modules/
dist/
build/
.idea/
.vscode/
.env
.env.local
logs/
*.log
.DS_Store
Thumbs.db
更细的模式说明见 references/gitignore-guide.md。
使用 Semantic Versioning：
MAJOR.MINOR.PATCH[-PRERELEASE]
v1.0.0 → v2.0.0）v1.0.0 → v1.1.0）v1.0.0 → v1.0.1）# 创建 annotated tag（推荐）
git tag -a v1.0.0 -m "release: v1.0.0 official release"
# 推送 tag
git push origin v1.0.0
git push origin --tags
# 查看 tag
git tag
git show v1.0.0
# 删除 tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
PR 应包含：
## Change Description
<!-- 描述本次变更的内容与目的 -->
## Change Type
- [ ] New feature (feat)
- [ ] Bug fix (fix)
- [ ] Code refactoring (refactor)
## Testing Method
<!-- 说明如何验证 -->
## Related Issue
Closes #xxx
## Checklist
- [ ] Code has been self-tested
- [ ] Documentation has been updated
Review 重点关注：
详细协作规范见 references/collaboration.md。
# 修改最近一次提交内容（尚未 push）
git add forgotten-file.ts
git commit --amend --no-edit
# 修改最近一次提交说明
git commit --amend -m "new commit message"
# 先拉再推
git pull origin master
git push origin master
# 想要更整洁历史时可用 rebase
git pull --rebase origin master
git push origin master
# 重置到指定 commit（丢弃其后提交）
git reset --hard abc123
# 创建反向提交（推荐，保留历史）
git revert abc123
git stash save "work in progress"
git stash list
git stash pop
git log -- <file>
git log -p -- <file>
git blame <file>
✅ 建议：
❌ 禁止：
✅ 建议：
--no-ff 保留历史❌ 禁止：
✅ 建议：
❌ 禁止：
更详细的专题指南见：
references/commit-conventions.md - commit message 规范与示例references/branching-strategies.md - 完整 branch 管理策略references/merge-strategies.md - merge、rebase 与冲突处理references/conflict-resolution.md - 冲突处理与预防细则references/advanced-usage.md - Git 性能优化、安全、submodule 与高级技巧references/collaboration.md - Pull Request 和 code review 指南references/gitignore-guide.md - .gitignore 模式与项目配置examples/ 中的可运行示例：
examples/commit-messages.txt - 优质 commit message 示例examples/workflow-commands.sh - 常用 workflow 命令片段本文定义了项目的 Git 标准：
merge --no-ff遵循这些标准可以提升协作效率、保证代码质量，并简化版本管理。
Use when the user asks to generate or refresh an architecture map, structure diagram, core call flow, local viewer assets, or runs ~map. Produces hello-scholar native architecture-map.json plus compact Markdown and Mermaid companion artifacts.
Use when the user asks to open the architecture viewer, view diagrams, inspect node evidence, export the local architecture map, or troubleshoot hello-scholar map view/export behavior.
实验分析命令，基于 experiment package、runs、metrics 和 evidence 形成结果解释与下一轮实验计划。
实现命令，把 plan package、change record 或 experiment package 落成代码、配置、文档或实验变更。
Use only when the user explicitly types ~map. Generates or refreshes the hello-scholar native architecture map by invoking the architecture-map workflow, then validates and points to the local viewer.
用于涉及编写或修改源码的日常编码任务。