Git 与 GitHub：可复现科研协作¶
对应课程：Week 1
目标：使用 branch → commit → pull request 完成一次可审查的科研改动。
Git 保存项目历史，GitHub 承载协作、审查和证据。课程不要求记住所有命令，但要求每项实验都能追溯到明确的 commit。
模块学习卡与完成路径¶
| 字段 | 本页约定 |
|---|---|
| 对应周次 | Week 1 |
| 适合谁 | 能编辑文本文件，准备建立第一个可复现研究仓库的学生 |
| 预计时间 | 最小 1–2 小时；标准任务 3–4 小时 |
| 学什么 | repository、branch、staging、commit、remote 与 PR 的关系 |
| 官方来源 | Git 与 GitHub 官方文档，以本页“官方学习入口”为准 |
| 最小动作 | 新建分支，完成一次明确 commit，并通过 PR 说明改动和验证方式 |
| 提交证据 | 仓库链接、branch、至少一次 commit、PR 链接及验证输出 |
| 完成自查 | 他人能从 PR 理解改动，仓库不含密钥、隐私数据或不必要的大文件 |
| 下一步 | Python 与可复现环境 |
| 路径 | 完成范围 |
|---|---|
| 最小 | 完成 branch → commit → PR，并写明 How to verify |
| 标准 | 完成本页 Week 1 必做任务、仓库结构、安全检查与自查 |
| 进阶 | 增加 Issue、PR Review、自动化检查或更细粒度 commit 历史 |
学习目标¶
- 区分 repository、working tree、staging area、commit 与 remote；
- 创建分支并编写有意义的 commit；
- 通过 pull request（PR）说明改动、验证和限制；
- 避免提交密钥、隐私数据、模型权重和大型生成文件。
官方学习入口¶
按顺序完成：
- Git tutorial（Git 基本操作）
- GitHub Hello World（repository、branch、commit、PR）
- About Git（GitHub flow）
- Ignoring files（
.gitignore） - About secret scanning（凭据安全）
最小工作流¶
git status
git switch -c week01-research-workflow
# 编辑 README、代码和测试后
git diff
git add README.md src/ tests/
git diff --staged
git commit -m "add document inspection tool"
git push -u origin week01-research-workflow
然后在 GitHub 创建 PR。PR 描述至少包含：
- What：改了什么；
- Why：为什么需要；
- How to verify：如何运行或检查；
- Limitations：已知限制或未完成项。
不要默认使用 git add .
先用 git status 和 git diff 确认范围，再显式添加文件。科研目录常含数据、模型、token、缓存和本地路径，误提交后很难彻底清除。
Week 1 必做任务¶
- 创建个人课程仓库；
- 新建
week01-research-workflow分支； - 添加 README、环境说明和一个最小 Python 工具；
- 至少提交两次：第一次实现、第二次改进测试或文档；
- 推送分支并创建 PR，请同学完成一次 review；
- 根据 review 修改并记录处理结果。
建议仓库结构¶
student-bootcamp/
├── README.md
├── .gitignore
├── environment.yml # 或 requirements.txt / pyproject.toml
├── learning-log.md
├── src/
├── tests/
└── week01/
数据、模型和输出目录是否提交，应由 .gitignore 和项目文档明确说明，而不是依赖个人记忆。
Commit 与 PR 质量¶
推荐 commit 信息使用动作开头，并描述结果：
add PDF page counter
test invalid file handling
document reproduction steps
fix empty input crash
避免 update、test、final、fix bug 等无法说明范围的信息。一个 commit 应聚焦一个可以解释的变化。
自主检查¶
-
git status显示预期文件，无密钥或大文件； - 在独立分支完成工作，没有直接修改
main； - 至少两个内容明确的 commits；
- PR 描述包含运行/验证方式；
- 同伴 review 有一条具体反馈及处理记录；
- README 能让陌生同学找到唯一开始命令；
- 学生能根据 commit 找回任意一次实验状态。
常见问题¶
文件已经被 Git 跟踪，加入 .gitignore 为什么无效？¶
.gitignore 只影响未跟踪文件。先确认文件是否应从版本控制移除；不要在不理解影响时执行批量删除命令。
Push 被拒绝¶
先阅读错误信息，检查远端分支是否更新、是否有权限以及认证方式。不要通过强制推送覆盖同学的提交。
不小心提交了 token¶
立即在对应平台撤销并轮换 token，并通知仓库管理员或相关平台责任人。删除当前文件不足以让已泄漏凭据恢复安全。
下一步¶
继续完成Python 环境，让 PR 中的代码可以在干净环境复现。