提交 93315742 authored 作者: zhangqianwei's avatar zhangqianwei

cfm_完成模块一 Python 工程化(第一版)

上级 723c1644
# 模块一 Python 工程化
> **本模块导读**:本模块面向 Python 后端 / LLM 应用开发者,目标是建立工程化的 Python 编程基础。包含 5 个章节,从代码版本管理(Git)到面向对象、设计模式(装饰器)、异步编程,最后到代码规范。学完本模块,你应该能像一名"工程化思维"的开发者一样,写出可维护、可协作、可部署的 Python 代码。
>
> **章节列表**:
> - **1.1 Git 使用** ← 本文档当前章节(★5 必会)
> - 1.2 面向对象
> - 1.3 装饰器
> - 1.4 异步编程
> - 1.5 Python 代码规范
>
> **阅读建议**:本模块内容多、实战强,建议边看边敲命令。每章末尾都配有"5 分钟自检",确认自己真的掌握了再往下走。
---
## 1.1 Git 使用
> Git 是每个开发者每天都要用的工具,但它也是新手最容易栽跟头的地方。本章会用**实战驱动**的方式,让你从"只会 add/commit/push 三连"升级到"能独立处理冲突、回退误删、规范提交"的合格协作者。
>
> 📖 预计阅读时长:60 分钟 ⏱️ 实战建议:每个命令跟着敲一遍
### 📋 本章知识点速览
| 编号 | 知识点 | 难度 | 一句话概括 |
| ------- | ------------ | ----- | -------------------- |
| 1.1.1 | 首次配置 | ★★☆ | 装好 Git 后的第一件事 |
| 1.1.2 | 克隆项目 | ★★☆ | 把远程代码下载到本地 |
| 1.1.3 | 分支操作 | ★★★ | 多人协作不打架的关键 |
| 1.1.4 | 同步代码 | ★★★★ | fetch / pull / rebase 的区别 |
| 1.1.5 | 提交代码 | ★★★ | 写完代码怎么"存档" |
| 1.1.6 | 推送代码 | ★★☆ | 把本地存档同步给队友 |
| 1.1.7 | 合并与冲突处理 | ★★★★★ | **新手最怕的环节** |
| 1.1.8 | 查看历史与差异 | ★★☆ | 翻"账本"找答案 |
| 1.1.9 | 版本回退 | ★★★★★ | **救命环节**:误删也能找回来 |
| 1.1.10 | 暂存工作 | ★★★ | 手头活干一半被打断怎么办 |
| 1.1.11 | Commit 规范与分支命名 | ★★☆ | 让团队 review 不抓狂 |
---
### 1.1.0 章节导读:5 分钟读完能上手 Git
> 如果你赶时间,先读这一节。其他小节可以之后回来看。
#### Git 是什么?
Git 是一个**分布式版本控制系统**——说人话就是:**它能给代码做"存档",让你随时回到任意一个历史版本**。
想象你在写毕业论文:
```
v1.docx → v2.docx → v3-改哭了版.docx → v3-真的改哭了.docx → 最终版.docx
```
没有 Git 的世界,你只能靠"最终版_v2_真的不改了.docx"这种文件名后缀来自救。**有 Git 的世界**,你每次提交都相当于做了一次存档,随时可以回到任何一次存档点。
#### 一张图看懂三个核心概念
```
┌─────────────────────────────────────────────────────────────┐
│ │
│ 工作区 暂存区 本地仓库 │
│ (Working (Staging (Repository) │
│ Tree) Area) │
│ │
│ ┌───────┐ ┌───────┐ ┌──────────┐ │
│ │ 你正 │ git │ "购物车"│ git │ 已存档的 │ │
│ │ 在编 │ ──────→ │ 等会 │ ─────────→ │ 所有版本 │ │
│ │ 辑的 │ add │ 要提交 │ commit │ │ │
│ │ 文件 │ ←────── │ 的改动 │ ←──────── │ │ │
│ └───────┘ └───────┘ └──────────┘ │
│ ↑ │ │
│ │ │ │
│ └──────────── git checkout ──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
#### 6 条命令速查表(先背这 6 条)
| 场景 | 命令 | 含义 |
| ------- | ---------------------------------------- | ----------- |
| 看当前状态 | `git status` | 当前改了什么 |
| 看历史 | `git log --oneline` | 列出所有提交 |
| 把改动加入"购物车" | `git add <文件名>` 或 `git add .` | 暂存改动 |
| "结账"提交 | `git commit -m "说明文字"` | 生成一个存档点 |
| 拉取远程 | `git pull` | 下载队友的最新代码 |
| 推送到远程 | `git push` | 把本地存档同步给队友 |
> 🎯 **目标**:读到这里,你应该能在 5 分钟内完成"修改一个文件 → 提交 → 推送到 GitHub"的全流程。如果还不能,跟着下面 11 个子知识点一个一个走。
---
### 1.1.1 首次配置
> 用 1-2 句话说清:**装好 Git 后第一件事**:告诉 Git "你是谁"。否则你提交的代码会被记成"匿名用户",团队 review 时一脸懵。
---
## 什么是首次配置?
Git 是一个**分布式**版本控制系统,每个提交都会记录作者信息(姓名 + 邮箱)。**首次配置 = 给 Git 装上"身份证"**。
### 一句话定义
通过 `git config` 命令设置全局或仓库级的用户名、邮箱、编辑器等偏好。
### 为什么重要
每次 `git commit` 都会带上你的名字和邮箱,团队成员看 `git log` 时能看到谁提交了什么。**配置错了,所有提交都会带错信息**,事后改起来很麻烦。
### 生活类比
Git 就像一个**班级签到表**——每次提交都相当于签到,签到必须写上"姓名 + 学号"。第一次用 Git 必须先"登记"自己的信息,不然签到表上全是"匿名"。
---
## 举个例子
### 输入
```bash
# 1. 设置全局用户名和邮箱(只需要做一次)
git config --global user.name "蔡馥名"
git config --global user.email "caifuming@example.com"
# 2. 设置默认编辑器为 VS Code(推荐)
git config --global core.editor "code --wait"
# 3. 设置默认分支名为 main(GitHub 默认也是 main)
git config --global init.defaultBranch main
```
### 输出
```bash
# 查看刚刚的配置
git config --list | grep -E "user|editor|defaultBranch"
# user.name=蔡馥名
# user.email=caifuming@example.com
# core.editor=code --wait
# init.defaultBranch=main
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -------- | ----------------------------------------------------- | ------------------------------------- |
| 邮箱 | 用自己的**真实邮箱**(公司邮箱或 GitHub 注册邮箱) | 随便填一个邮箱,比如 `123@qq.com` |
| 用户名 | 用**全名**或**统一昵称**,避免中英文混用 | 用中文 + 空格:`蔡馥名 CFM` |
| 范围 | 个人电脑 → `--global`;临时改身份 → 仓库级不加 global | 每次提交前都临时改 |
| 修改已提交的信息 | 用 `git commit --amend --author="新名字 <新邮箱>"` 修改**最近一次** | 直接 `git config` 然后重提(不生效) |
**错误表现**:
```bash
# 没配置就提交
$ git commit -m "first commit"
# 输出(看起来一切正常)
$ git log --format="%an <%ae>"
# 作者显示为:
# Your Name <you@example.com>
# 或者完全空着
```
---
## 实战代码
### 全套配置(建议入职第一天就执行)
```bash
# === 身份信息 ===
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# === 编辑器(VS Code 推荐)===
git config --global core.editor "code --wait"
# === 默认分支名(与 GitHub 保持一致)===
git config --global init.defaultBranch main
# === 中文文件名不乱码 ===
git config --global core.quotepath false
# === 自动转换行尾(Windows 用户强烈建议)===
git config --global core.autocrlf input # Linux/Mac
git config --global core.autocrlf true # Windows
# === 让命令输出带颜色 ===
git config --global color.ui auto
# === 查看所有配置 ===
git config --list
```
### 全局 vs 仓库级 vs 单次命令
| 范围 | 命令示例 | 作用范围 |
| -------- | ----------------------------------------------- | --------------- |
| 全局 `--global` | `git config --global user.name "X"` | 当前用户**所有**仓库 |
| 仓库级(无标志) | `cd my-repo && git config user.name "Y"` | 仅当前仓库 |
| 单次命令 | `git -c user.name="Z" commit -m "..."` | 仅这一次提交 |
---
## 常见问题
**Q:配置错了,已经提交了几十个 commit,能批量改作者信息吗?**
A:能,但要用 `git filter-branch` 或 `git filter-repo`(后者是新版推荐)。⚠️ **警告**:批量改写历史会让所有 commit ID 变化,已经推送到远程的需要强制 `push -f`,会影响所有协作者。**入职前先把个人信息配置好,不要事后改**。
**Q:我有多个 GitHub 账号(个人 + 公司),怎么在不同仓库用不同身份?**
A:在仓库级(不加 `--global`)单独配置:
```bash
cd ~/work/company-repo
git config user.name "Your Work Name"
git config user.email "you@company.com"
```
这样公司仓库用公司身份,个人仓库用 `--global` 的全局身份。
**Q:邮箱设置错了,能隐藏真实邮箱吗?**
A:GitHub 提供了 noreply 邮箱(`username@users.noreply.github.com`),可以在 GitHub Settings → Emails 里勾选"Keep my email addresses private",然后把这个 noreply 邮箱配置进 Git 即可。
---
## 验收标准
```
☐ 能用 git config --global 设置 user.name 和 user.email
☐ 能用 git config --list 查看所有配置
☐ 能区分全局配置、仓库级配置、单次命令配置的使用场景
☐ 能在 Windows 上正确设置 core.autocrlf
☐ 知道为什么要用真实邮箱而不是随便填
```
## 官方来源
- Git 官方文档 - 初次配置 Git:[https://git-scm.com/book/zh/v2/起步-初次运行-Git-前的配置](https://git-scm.com/book/zh/v2/%E8%B5%B7%E6%AD%A5-%E5%88%9D%E6%AC%A1%E8%BF%90%E8%A1%8C-Git-%E5%89%8D%E7%9A%84%E9%85%8D%E7%BD%AE)
- `git-config` 手册页:[https://git-scm.com/docs/git-config](https://git-scm.com/docs/git-config)
## 参考文献
[1] Scott Chacon & Ben Straub. *Pro Git (2nd Edition)*. Apress, 2014. 第 1.5 节.
---### 1.1.2 克隆项目
> 用 1-2 句话说清:**把远程仓库的代码下载到本地**,开始你的开发工作。
---
## 什么是克隆(clone)?
### 一句话定义
`git clone <仓库地址>` 把远程仓库的**完整历史**复制到本地,生成一个全新的工作目录。
### 为什么重要
进入一个新团队,第一件事就是 `git clone`,把项目代码拉下来。**克隆得到的本地仓库和远程仓库完全独立**——你在本地怎么改都不会影响远程,直到你 `git push`。
### 生活类比
- `git clone` = 把一个**连锁店的整套账本**复印一份放到你的工位上
- 你改自己的账本,原店不受影响
- 直到你的版本被 `push` 回去
---
## 举个例子
### 输入
```bash
# 假设公司仓库地址是:git@github.com:cfm-team/smartqa.git
git clone git@github.com:cfm-team/smartqa.git
# 默认克隆到 ./smartqa 目录
```
### 输出
```bash
Cloning into 'smartqa'...
remote: Enumerating objects: 1842, done.
remote: Counting objects: 100% (1842/1842), done.
remote: Compressing objects: 100% (1024/1024), done.
remote: Total 1842 (delta 856), reused 1640 (delta 712), pack-reused 0
Receiving objects: 100% (1842/1842), 4.32 MiB | 5.10 MiB/s, done.
Resolving deltas: 100% (856/856), done.
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -------- | ------------------------------------------- | -------------------------------------- |
| 仓库地址 | 用 SSH 地址:`git@github.com:user/repo.git`(无需每次输密码) | 用 HTTPS 地址但每次 `push` 都要输用户名密码(除非用 PAT) |
| 子目录名 | 默认即可,要改的话用 `git clone <url> <新目录名>` | 克隆完再 mv 改名(容易破坏 git 内部相对路径) |
| 深度 | 完整克隆:`git clone <url>` | 不小心加了 `--depth 1`(后续 `git log` 看不到历史) |
| 已有目录 | 直接克隆到当前目录:先 `cd` 进空目录再 `git clone <url> .`(注意末尾的 `.`) | 在已有内容的目录里克隆(会冲突报错) |
---
## 实战代码
### HTTPS vs SSH 两种方式对比
| 维度 | HTTPS 协议 | SSH 协议 |
| -------- | ----------------------------------------- | ---------------------------------------- |
| 地址格式 | `https://github.com/user/repo.git` | `git@github.com:user/repo.git` |
| 认证方式 | 用户名 + 密码(或 Personal Access Token) | SSH 密钥对(公钥配远程,私钥留本地) |
| 是否每次都要输密码 | 是(除非配 PAT 或 credential helper) | 否,只需配一次 SSH key |
| 适合谁 | 临时克隆开源项目、CI/CD | 日常开发、需要频繁 push/pull |
### 配置 SSH Key(推荐日常使用)
```bash
# 1. 生成 SSH 密钥对(一路回车即可)
ssh-keygen -t ed25519 -C "your.email@example.com"
# 输出:
# Generating public/private ed25519 key pair.
# Enter file in which to save the key (/home/you/.ssh/id_ed25519): [回车]
# Enter passphrase (empty for no passphrase): [回车]
# Your identification has been saved in /home/you/.ssh/id_ed25519
# Your public key has been saved in /home/you/.ssh/id_ed25519.pub
# 2. 复制公钥内容到剪贴板
cat ~/.ssh/id_ed25519.pub
# 把输出粘贴到 GitHub → Settings → SSH and GPG keys → New SSH key
# 3. 测试连接
ssh -T git@github.com
# Hi <your-username>! You've successfully authenticated...
```
### 克隆到指定目录
```bash
# 克隆并改名
git clone git@github.com:user/repo.git my-project
cd my-project
# 克隆到当前空目录(注意末尾的点)
mkdir my-project && cd my-project
git clone git@github.com:user/repo.git .
```
### 只克隆最新一次提交(浅克隆)
```bash
# 适合只想看最新代码、节省时间的场景
git clone --depth 1 git@github.com:user/repo.git
# 后续如需看完整历史:
# git fetch --unshallow
```
---
## 常见问题
**Q:克隆时报错 `Permission denied (publickey)`?**
A:SSH Key 没配好。检查:
1. 私钥路径对不对:`ls ~/.ssh/id_ed25519`
2. 公钥是否已加到 GitHub:`cat ~/.ssh/id_ed25519.pub`
3. SSH agent 加载了没有:`ssh-add ~/.ssh/id_ed25519`
**Q:克隆很慢/超时?**
A:换协议试试:
```bash
# 用 SSH 替代 HTTPS(在国内通常更快)
git clone git@github.com:user/repo.git
```
或者配 git proxy:`git config --global http.proxy http://127.0.0.1:7890`
**Q:克隆完发现忘了 --depth,怎么补全历史?**
A:
```bash
git fetch --unshallow
```
---
## 验收标准
```
☐ 能用 git clone <ssh-url> 把项目拉下来
☐ 能区分 HTTPS 和 SSH 两种协议的使用场景
☐ 能生成 SSH Key 并配置到 GitHub
☐ 知道克隆后默认进入 master/main 分支
☐ 能用 --depth 1 做浅克隆,并能用 --unshallow 补全历史
```
## 官方来源
- `git-clone` 手册页:[https://git-scm.com/docs/git-clone](https://git-scm.com/docs/git-clone)
- GitHub - About SSH:[https://docs.github.com/en/authentication/connecting-to-github-with-ssh](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
## 参考文献
[1] *Pro Git* 第 2.1 节 "获取帮助"。
---
### 1.1.3 分支操作
> 用 1-2 话说清:**分支 = 你的"平行宇宙"**,在分支上随便改不会影响主线,合并时再合到一起。
---
## 什么是分支?
### 一句话定义
分支(branch)是指向某个 commit 的**可移动指针**。新分支让你在不影响主线的情况下自由开发。
### 为什么重要
团队协作的核心机制:**每个人在自己的分支开发,互不干扰**,开发完再合并。多分支让你可以**同时推进多个任务**(修 bug、做新功能、发版本)。
### 生活类比
想象你在写一本书:
- `main` 分支 = 正式发行的版本
- `feature/新章节` 分支 = 你正在写的新章节
- `bugfix/第3章错别字` 分支 = 你同时在改的错别字
三个分支**同时存在、互不干扰**,写完再合并到 `main` 出版。
---
## ASCII 分支示意图
```
main 分支(稳定版)
●───────●─────────●────────●
↖ ↘
feature/login 分支 ↘ ↘ bugfix/typo 分支
●─────●──────●───●
↘ ↘
● (合并回 main)
```
实操中你会看到 `git log --oneline --graph --all` 画出类似的流程图。
---
## 举个例子
### 输入
```bash
# 查看所有分支
git branch -a
# 输出:
# * main
# remotes/origin/main
# remotes/origin/feature/login
# (* 表示当前所在分支)
# 创建新分支
git switch -c feature/login
# 等价于(老写法):git checkout -b feature/login
# 切换分支
git switch main
# 删除已合并分支
git branch -d feature/login
```
### 输出
```bash
$ git switch -c feature/login
Switched to a new branch 'feature/login'
# 当前已切到 feature/login 分支,可以开始开发
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| --------------- | ---------------------------------------------------- | -------------------------------------- |
| 创建并切换分支 | `git switch -c <新分支名>`(Git 2.23+ 推荐) | `git checkout -b <新分支名>`(能用但语义混乱) |
| 仅切换分支 | `git switch <分支名>` | `git checkout <分支名>`(同上) |
| 仅创建分支不切换 | `git branch <新分支名>` | `git switch -c` 不想切换时 |
| 在 main 上直接开发 | ❌ 实际不推荐(实战中应切到 feature 分支) | 实习生最爱犯——直接在 main 改代码然后 push |
| 删未合并的分支 | `git branch -D feature/login`(强制删除) | `git branch -d feature/login`(会被警告分支未合并) |
| 远程分支 | `git switch -c feature/x origin/feature/x`(基于远程建分支) | 手动 `git checkout origin/feature/x` 进入 detached 状态 |
**错误表现**:
```bash
# 在 main 上改代码并直接 push
$ # ... 改了文件 ...
$ git commit -am "改了点东西"
$ git push
# 没问题,但所有人都能看到 main 被你直接改动了——团队 review 抓狂
# 用 -d 删未合并的分支
$ git branch -d feature/login
# error: The branch 'feature/login' is not fully merged.
# If you are sure you want to delete it, run 'git branch -D'.
```
---
## 原理深入
### 分支的本质
Git 的分支**只是一个指向 commit 对象的可变指针**:
```
仓库内部:
.commit → commit 对象(包含快照 + 父提交)
.refs/heads/main → 文件,内容是指向某个 commit 的 SHA-1
.refs/heads/feature/login → 文件,内容是指向某个 commit 的 SHA-1
```
创建分支 = 写入 41 字节(一个 SHA-1)的文件,**几乎是瞬间完成的**。
### HEAD 的含义
`HEAD` 是一个**特殊指针**,指向"当前所在分支"。`git switch` 实际是把 HEAD 指向另一个分支(如 `refs/heads/feature/login`)。
---
## 实战代码
### 一套完整的分支操作流程
```bash
# 1. 从 main 切出 feature 分支
git switch main # 先回到 main
git pull # 确保 main 是最新的
git switch -c feature/add-login # 创建并切到新分支
# 2. 在新分支上开发
echo "登录功能代码" > login.py
git add login.py
git commit -m "feat(login): 新增登录接口"
# 3. 推送到远程
git push -u origin feature/add-login
# 4. 在 main 上合并这个 feature
git switch main
git merge feature/add-login
git push
# 5. 清理已合并的本地分支
git branch -d feature/add-login
```
### 分支命名约定(见 1.1.11 详述)
| 类型 | 前缀 | 示例 |
| ---- | ------------- | ----------------------------- |
| 新功能 | `feature/` | `feature/user-auth` |
| 修复 | `bugfix/` | `bugfix/login-500-error` |
| 紧急修复 | `hotfix/` | `hotfix/critical-security` |
| 实验 | `experiment/` | `experiment/draft-new-idea` |
---
## 常见问题
**Q:`switch` 和 `checkout` 到底用哪个?**
A:**Git 2.23 (2019) 起推荐用 `switch`**,因为 `checkout` 同时承担"切换分支"和"恢复文件"两种语义,容易混淆。新项目统一用 `switch` 即可。
| 任务 | 新写法(推荐) | 老写法 |
| ---- | ---------------------- | -------------- |
| 切换分支 | `git switch main` | `git checkout main` |
| 创建并切换 | `git switch -c dev` | `git checkout -b dev` |
| 恢复文件 | `git restore README.md` | `git checkout HEAD -- README.md` |
**Q:怎么查看所有分支(含远程)?**
A:
```bash
git branch -a # -a 表示 all,包括远程
git branch -r # 只看远程
git branch -vv # 看远程跟踪关系
```
**Q:误删了分支,能找回吗?**
A:能!Git 不会轻易丢弃对象(至少 30 天)。用 `git reflog` 找到删除前的 commit SHA,然后用 `git branch <name> <sha>` 重建。详见 1.1.9。
---
## 验收标准
```
☐ 能用 git branch / switch / checkout 创建、切换、删除分支
☐ 能用 git branch -a 查看本地和远程所有分支
☐ 理解 HEAD 指向的是"当前所在分支"
☐ 能在 feature 分支开发完后合并到 main
☐ 能在合并后清理已合并的 feature 分支
```
## 官方来源
- `git-branch` 手册页:[https://git-scm.com/docs/git-branch](https://git-scm.com/docs/git-branch)
- `git-switch` 手册页:[https://git-scm.com/docs/git-switch](https://git-scm.com/docs/git-switch)
- Git Book - 分支简介:[https://git-scm.com/book/zh/v2/Git-分支-分支简介](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%88%86%E6%94%AF%E7%AE%80%E4%BB%8B)
## 参考文献
[1] *Pro Git* 第 3 章 "Git 分支"。
---
### 1.1.4 同步代码
> 用 1-2 句话说清:从远程把队友的改动拿过来——这一步有 3 种方式,**用错方式会让你后悔**。
---
## 什么是同步代码?
### 一句话定义
"同步"包含**两个动作**:
- **下载**(fetch):把远程的新 commit 拉到本地,但**不修改**你的工作区
- **合并 / 变基**(merge / rebase):把下载下来的 commit 整合到你当前分支
### 为什么重要
多人协作时,大家都在自己的分支上开发。**你需要定期把队友的代码同步到自己本地**,否则你的本地版本会越来越落后,最终合并时产生大量冲突。
### 生活类比
想象你在改论文,老师时不时在共享文档里加批注:
- `git fetch` = **只刷新你本地"看到的批注列表"**,但不改你的文字
- `git pull` = `fetch` + `merge`:刷新列表 + **把你的文字和批注合并到一起**
- `git pull --rebase` = `fetch` + `rebase`:刷新列表 + **把批注"挪到"你的文字前面**
---
## 举个例子
### 输入
```bash
# 方式 1:纯下载,不合并
git fetch origin
# 方式 2:下载 + 自动合并(默认)
git pull origin main
# 方式 3:下载 + 变基(推荐用于个人 feature 分支)
git pull --rebase origin main
```
### 输出
```bash
$ git fetch origin
From github.com:cfm-team/smartqa
* branch main -> FETCH_HEAD
# 没有任何文件被改动,但本地已经"看到"远程的最新 commit
$ git status
On branch main
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
# 提示本地落后 3 个 commit,可以 fast-forward
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ---------- | ---------------------------------------------- | ---------------------------------------- |
| 日常同步 | `git pull --rebase`(保持线性历史) | `git pull`(默认会留下 merge commit,历史难看) |
| 多人共用分支 | `git pull`(用 merge,不要 rebase 别人写过的 commit) | `git pull --rebase`(改写已共享历史会坑队友) |
| 提交前先拉 | 永远**先 fetch/pull,再 commit,再 push** | 写完直接 push(大概率推不上去) |
| 看远程但不动 | `git fetch` | `git pull`(你只是想看看,不一定要合并) |
---
## 原理深入:fetch vs pull vs pull --rebase ASCII 时间线对比
**场景**:你和队友从同一个 commit `A` 出发,各自开发后你提交了 `B`,队友提交了 `C`。
```
初始状态(你俩都从 A 出发):
A
\
B (你写的)
远程上:
A
\
C (队友写的)
你本地 .git 里没有 C
```
### 步骤 1:fetch(下载但不合并)
```
$ git fetch
你的本地仓库:
A
\
B (你)
\
C (新下载到本地,但你的工作区还看不到)
你当前所在分支:main(指向 B)
状态:main 落后 origin/main 3 commits
```
fetch 之后,本地的 `origin/main` 指针更新了指向 `C`,但你的 `main` 还指向 `B`。
```
origin/main (远程指针,本地镜像)
↓
A ←───── C
\
B ←──── main (你当前分支)
```
### 步骤 2a:merge(pull 默认行为)
```
$ git pull # = fetch + merge
合并结果(出现分叉合并):
A ──┬── B (你)
└── C ──M (合并提交)
↑
main
```
历史变成"分叉→合并"的菱形,对人类阅读不友好。
### 步骤 2b:rebase(pull --rebase 行为)
```
$ git pull --rebase # = fetch + rebase
变基结果(线性、干净):
A ── C ── B'(你的 commit 改了个"新爸爸")
↑
main
```
历史是一条直线,**看起来像"先有了 C 再有了你的 B"**——非常适合个人 feature 分支。
### 一张表三选一
| 行为 | 改不改你的 commit? | 历史形态 | 适用场景 |
| -------- | ------------- | ------ | --------------- |
| `fetch` | 不改,仅下载远程 | 不变 | 看一眼远程状态 |
| `pull` | 改,生成 merge commit | 菱形分叉合并 | 多人共用分支、想保留完整拓扑 |
| `pull --rebase` | 改,重写你的 commit"爸爸" | 线性 | 个人 feature 分支提 PR 前 |
---
## 实战代码
### 推荐的标准流程(个人 feature 分支)
```bash
# 1. 早上开工,先 sync 一次
git switch feature/login
git fetch origin
git pull --rebase origin main # 把 main 的改动"挪到"我前面
# 现在我的 feature/login 始终建立在最新 main 之上
# 2. 推上去前再 sync 一次(防止 PR 合并冲突)
git fetch origin
git pull --rebase origin main
git push -f # 因为 rebase 改写了 history,需要 -f
# ⚠️ 注意:-f 仅在你**自己的 feature 分支**上用,main 上永远不要 -f!
```
### 多人共用分支的正确流程
```bash
# 假设 dev 分支是你和同事都在用的
git switch dev
git fetch origin
git pull # 用 merge,不要 rebase 别人写过的 commit
# 如果冲突:编辑冲突文件 → git add → git commit(解决冲突)
```
---
## 常见问题
**Q:我 `git pull` 后报了一堆冲突,怎么办?**
A:`pull --rebase` 冲突比普通 `merge` 更容易处理——因为你的每个 commit 是**逐个**变基的:
```bash
# 方案 1:终止这次 pull,回到 pull 之前的状态
git rebase --abort
# 方案 2:手动解决冲突
# 编辑冲突文件,去掉 <<<<<<< ======= >>>>>>> 标记
git add <冲突文件>
git rebase --continue # 继续处理下一个 commit
```
**Q:什么时候绝对不能用 `rebase`?**
A:**已推送到远程且有别人基于它开发的 commit**。黄金法则:
> "**Don't rebase commits that exist outside your repository and that people have based work on.**" ——Pro Git
>
> 翻译:**不要 rebase 那些"已经离开你电脑、且有别人基于其工作"的 commit**。
**Q:`git pull --rebase` 后我的 commit ID 全变了,会有问题吗?**
A:在**个人 feature 分支上没问题**:
- 自己的 commit 改个 ID 没事,反正你 push 时 Git 会发现是同一个人
- 最后 push 时加 `-f` 强制推送即可
如果分支已经被别人 fork 或者同事已经拉过你的 commit,让他们 `git fetch` + `git reset --hard origin/<branch>` 同步一次。
---
## 验收标准
```
☐ 能区分 fetch / pull / pull --rebase 三者差别
☐ 能用 git pull --rebase 在个人 feature 分支上保持线性
☐ 知道 main 分支绝对不能用 -f
☐ 能用 git pull 后处理冲突
☐ 知道什么时候绝对不能 rebase
```
## 官方来源
- `git-fetch` 手册页:[https://git-scm.com/docs/git-fetch](https://git-scm.com/docs/git-fetch)
- `git-pull` 手册页:[https://git-scm.com/docs/git-pull](https://git-scm.com/docs/git-pull)
- Git Book - 变基:[https://git-scm.com/book/zh/v2/Git-分支-变基](https://git-scm.com/book/zh/v2/Git-%E5%88%86%E6%94%AF-%E5%8F%98%E5%9F%BA)
## 参考文献
[1] *Pro Git* 第 3.6 节 "变基"。
---
### 1.1.5 提交代码
> 用 1-2 句话说清:**把改动"打个存档点"**——存什么、写什么说明、能不能撤回。
---
## 什么是提交(commit)?
### 一句话定义
`git commit` 把**暂存区里的所有改动**打包成一个"存档点"(commit 对象),永久存进 `.git` 数据库。
### 为什么重要
commit 是 Git 最小的"撤销单位"。一个 commit 就是一个完整的快照(不是 diff),所以你可以随时回到任意一个 commit。
### 生活类比
commit = 游戏的**存档点**:
- 每次打 boss 前先存档
- 挂了就读档重来
- 存档有"存档时间/标签"(commit message)
---
## 举个例子
### 输入
```bash
# 完整的提交流程
git status # 看看改了什么
git diff # 看具体改动内容
git add README.md # 选一个文件放进暂存区
git commit -m "docs: 新增 README"
```
### 输出
```bash
$ git status
On branch main
Changes not staged for commit:
modified: README.md
$ git add README.md
$ git status
On branch main
Changes to be committed:
modified: README.md
$ git commit -m "docs: 新增 README"
[main 7a3f2c1] docs: 新增 README
1 file changed, 12 insertions(+)
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| ------------- | -------------------------------------------------- | ------------------------------------------- |
| 提交粒度 | 一个 commit 只做一件事(修一个 bug / 加一个功能) | 一个 commit 改了 10 个无关文件 |
| add 范围 | 用 `git add <具体文件>` 或 `git add -p`(交互式选改动) | 直接 `git add .` 把日志/构建产物一起加进去 |
| commit message | 标题 50 字以内,正文 72 字换行(见 1.1.11) | `git commit -m "fix"` 一个字打发 |
| 修改上一次 commit | `git commit --amend` | 又 commit 一次,造成无意义的 commit |
| 撤回未 push 的 add | `git restore --staged <file>` | 强行手动编辑 .git/index(千万不要) |
| 提交前的最后检查 | `git diff --cached`(看即将提交的内容) | 提交完才发现把 .env 也加进去了 |
**错误表现**:
```bash
# 错误 1:add 范围太大
$ git add .
$ git status
Changes to be committed:
modified: README.md
modified: .env ← 不该提交!含密钥
new file: node_modules/ ← 不该提交!构建产物
```
```bash
# 错误 2:commit message 无意义
$ git log --oneline
a7f8c91 fix
b3e1d24 update
9c2a0aa ok
# 一个月后你自己都不知道改了什么
```
---
## 实战代码
### `git add` 三种模式对比
| 模式 | 含义 | 适用场景 |
| ------------------- | ------------------- | ------------- |
| `git add <文件名>` | 只加这个文件 | 最常用、最安全 |
| `git add .` | 当前目录及子目录下**所有改动** | 快速添加,记得提前看 `git status` |
| `git add -p` | 交互式:逐个 hunk 询问是否 add | 想把一个大改动拆成多个 commit |
### `git commit` 三种写法
```bash
# 1. 单行 message
git commit -m "docs: 新增 README"
# 2. 多行 message(推荐用于重要 commit)
git commit
# 弹出编辑器,写:
# docs: 新增项目说明文档
#
# - 增加安装步骤
# - 增加使用示例
# 3. 修改上一次 commit(追加 / 修改信息)
git commit --amend -m "新的 message"
# ⚠️ 别在已 push 的 commit 上用 --amend,会导致历史分歧
```
### `git restore` vs `git reset` 撤回
| 任务 | 命令 | 备注 |
| --------- | ------------------------------------------------- | ----------------- |
| 撤回 add(保留改动) | `git restore --staged <file>` | 推荐 |
| 撤回 add(旧写法) | `git reset HEAD <file>` | 等价 |
| 撤回工作区改动 | `git restore <file>` | 不可恢复! |
| 撤销旧写法 | `git checkout -- <file>` | |
### amend 的应用场景
```bash
# 场景:刚 commit 完,发现忘 add 了一个文件
# 第一次提交(少了 test 文件)
$ git commit -m "feat: 新增登录接口"
$ git status
modified: tests/test_login.py ← 漏了
# 改写上一次 commit
$ git add tests/test_login.py
$ git commit --amend --no-edit
# 输出:
# [main 8e4d2c3] feat: 新增登录接口
# Date: Thu Jul 7 10:30:00 2026 +0800
# 2 files changed, 45 insertions(+)
# commit ID 变了,但 message 不变;之前的提交并入了这次
```
---
## 常见问题
**Q:commit 后才发现漏了文件,能补进去吗?**
A:用 `--amend`(见上面实战代码)。**注意**:只在**未推送**时用。
**Q:commit 后想撤回?**
A:见 1.1.9 版本回退,三种方式:`reset` / `revert` / `restore`。
**Q:能不能一次性 commit 但分多个逻辑单元?**
A:用 `git add -p` 交互式添加(hunk by hunk),每个 commit 一个逻辑单元。
**Q:commit 后发现 message 写错了,能改吗?**
A:
- 还没 push:`git commit --amend -m "新 message"`
- 已 push:`git rebase -i HEAD~n`(交互式改写,见 1.1.9)或者走 PR 重新提一个 commit
---
## 验收标准
```
☐ 能用 git add / git commit 完成一次提交
☐ 能区分 git add . / git add <文件> / git add -p
☐ 能用 git commit --amend 修改最近一次 commit
☐ 能用 git restore --staged 撤回 add
☐ 能写出格式良好的 commit message(见 1.1.11)
```
## 官方来源
- `git-commit` 手册页:[https://git-scm.com/docs/git-commit](https://git-scm.com/docs/git-commit)
- `git-add` 手册页:[https://git-scm.com/docs/git-add](https://git-scm.com/docs/git-add)
- `git-restore` 手册页:[https://git-scm.com/docs/git-restore](https://git-scm.com/docs/git-restore)
## 参考文献
[1] *Pro Git* 第 2.2 节 "记录每次更新到仓库"。
---
### 1.1.6 推送代码
> 用 1-2 句话说清:**把本地存档同步给队友**——但要小心"覆盖别人"和"-f 的危险"。
---
## 什么是推送(push)?
### 一句话定义
`git push` 把本地分支的 commit **同步到远程仓库**。
### 为什么重要
你 commit 到本地只是给自己存档,**push 才能让队友看到你的改动**。团队协作的"信息源"是远程仓库,所有人通过 push/pull 同步。
### 生活类比
- commit = 在自己的笔记本上做笔记
- push = 把笔记内容拍成照片发给团队群
- 队友 `git pull` = 团队群里把照片保存到自己的笔记本
---
## 举个例子
### 输入
```bash
# 第一次推送当前分支 + 设置 upstream(跟踪关系)
git push -u origin feature/login
# 之后只需
git push
```
### 输出
```bash
$ git push -u origin feature/login
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), 312 bytes | 312.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), done.
To github.com:cfm-team/smartqa.git
* [new branch] feature/login -> feature/login
Branch 'feature/login' set up to track remote branch 'feature/login' from 'origin'.
```
---
## 正解 vs 错误
| 维度 | 正解 ✅ | 错误 ❌ |
| -------- | ------------------------------------------- | ---------------------------------------------------- |
| 首次推送 | `git push -u origin <branch>`(建立跟踪) | 一直 `git push origin <branch>`(每次都写全名) |
| 后续推送 | `git push`(已有跟踪关系时) | 一直 `git push origin HEAD` |
| 强推 | ❌ **几乎永远不要用** `git push -f` | 在 main 上强推,删掉同事的 commit |
| 推送前 | 先 `git pull --rebase` 同步 | 直接 push,被远程拒绝(rejected) |
| 推送 tag | `git push origin v1.0.0` | 打了本地 tag 却没推送,队友 `git fetch --tags` 也看不到 |
**错误表现**:
```bash
# 没先 pull 就 push
$ git push
To github.com:cfm-team/smartqa.git
! [rejected] feature/login -> feature/login (non-fast-forward)
error: failed to push some refs to 'github.com:cfm-team/smartqa.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
```
---
## 原理深入:`-u` 的含义
`-u` = `--set-upstream`,建立**本地分支与远程分支的跟踪关系**。
```
第一次推送:本地 feature/login ─────→ origin/feature/login
│
└─ 建立关联(u)
之后:直接 git push 即可,Git 知道推到哪
```
### 为什么需要 -u?
Git 想避免你"误推到错分支"。第一次推送时,本地分支和远程分支的对应关系**不存在**,Git 不知道把 commit 推到哪个远程分支去。`git push -u` 就是告诉 Git:
> "本地的 feature/login 之后都推给 origin/feature/login"
之后 `git push` 就不用再写 origin 和分支名了。
---
## 实战代码
### 首次推送个人分支
```bash
# 1. 创建本地分支(详见 1.1.3)
git switch -c feature/add-logout
# 2. 开发 + 提交(详见 1.1.5)
echo "logout func" > logout.py
git add logout.py
git commit -m "feat(auth): 新增退出登录接口"
# 3. 首次推送
git push -u origin feature/add-logout
# 输出含 "Branch 'feature/add-logout' set up to track..."
```
### 之后的所有 push
```bash
# 已建立跟踪,直接 push
git commit -am "fix: 修复退出按钮失效"
git push
# 短得不能再短了
```
### `push -f` 的"危险等级"对照表
| 场景 | 能否 `push -f` | 后果 |
| ------------------------ | ----------- | ----------------- |
| 推送到你的**个人 feature 分支** | ✅ 可以(用 `--force-with-lease` 更安全) | 改写自己分支历史,无人受影响 |
| 推送到**多人共用的 dev 分支** | ❌ **绝对禁止** | 删掉同事的 commit,他们全炸了 |
| 推送到 main / master | ❌ **绝对禁止** | 全员受影响,CI 挂一地 |
| 推送到 team 的 release-x 分支 | ❌ **绝对禁止** | 影响版本发布 |
**安全替代**:`--force-with-lease`
```bash
# 比 -f 安全:只有当远程没有被别人新推过时才允许强制推
git push --force-with-lease origin feature/my-branch
```
---
## 常见问题
**Q:push 时报错 `non-fast-forward`,怎么办?**
A:
```bash
# 先拉取,再合并/变基,再 push
git pull --rebase origin <branch>
git push
```
**Q:push 时报错 `Permission denied` / `deny updating non-fast-forward`?**
A:分支保护(GitHub Branch Protection)启用,禁止强推。联系管理员解锁或走 PR 流程。
**Q:我 push 错了,想撤回怎么办?**
A:见 1.1.9 版本回退。一般做法:
- 撤回自己 push 的最后一次 commit:`git revert HEAD && git push`
- 撤回本地的错误 commit 后再 push(如果是自己独有分支):`git reset --hard HEAD^ && git push -f`
---
## 验收标准
```
☐ 能用 git push -u origin <branch> 首次推送个人分支
☐ 能用 git push 推送已建立跟踪的分支
☐ 理解 -u = --set-upstream 的含义
☐ 知道 main 分支绝不能用 -f
☐ 能处理 push 被拒绝(rejected)的场景
```
## 官方来源
- `git-push` 手册页:[https://git-scm.com/docs/git-push](https://git-scm.com/docs/git-push)
- GitHub - About protected branches:[https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)
## 参考文献
[1] *Pro Git* 第 2.5 节 "远程仓库的使用"。
---
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论