一、核心概念（先理解，再记命令）

Git 追踪的不是"文件"，而是快照。每次 commit 就是给整个项目拍一张照片，你可以随时回到任何一张照片的状态。

三个区域的关系：

工作区（你写代码的地方）
    ↓ git add
暂存区（选好要拍进照片的内容）
    ↓ git commit
本地仓库（照片存档，只在你电脑上）
    ↓ git push
远程仓库（GitHub，团队共享）

---

二、安装与初始配置（一次性）

bash

# macOS
brew install git

# Ubuntu
sudo apt install git

# 配置你的身份（每次 commit 会记录这些信息）
git config --global user.name "你的名字"
git config --global user.email "your@email.com"

# 设置默认分支名为 main（和 GitHub 保持一致）
git config --global init.defaultBranch main

# 设置默认编辑器为 VS Code（写 commit message 时用）
git config --global core.editor "code --wait"

# 查看当前配置
git config --list

---

三、日常最常用的 10 条命令

1. git init / git clone — 开始一个项目

bash

# 从零开始新项目
mkdir my-ai-app
cd my-ai-app
git init                    # 当前目录变成 Git 仓库

# 从 GitHub 克隆现有项目
git clone https://github.com/username/repo.git
git clone https://github.com/username/repo.git my-folder  # 指定本地目录名

2. git status — 查看当前状态（最高频）

bash

git status

# 输出示例：
# On branch main
# Changes not staged for commit:         ← 修改了但没 add
#   modified:   app/services/llm.py
# Untracked files:                        ← 新文件，Git 还不知道
#   app/services/rag.py

习惯：做任何操作前先 git status，确认当前状态。

3. git add — 选择要提交的内容

bash

git add app/services/llm.py       # 添加单个文件
git add app/services/             # 添加整个目录
git add .                         # 添加所有改动（最常用）
git add -p                        # 交互式选择，精确控制提交哪些改动

4. git commit — 保存快照

bash

git commit -m "feat: add streaming support to chat endpoint"

# 跳过 add，直接提交所有已追踪文件的改动（新文件不行）
git commit -am "fix: handle empty search results"

# 修改最后一次 commit（还没 push 时用）
git commit --amend -m "fix: handle empty search results in RAG service"
```

**commit message 规范**（团队协作必须遵守）：
```
feat:     新功能
fix:      修复 bug
refactor: 重构（不改功能）
docs:     只改文档
test:     只改测试
chore:    构建/依赖/配置相关
perf:     性能优化

示例：
feat: add rerank step to RAG pipeline
fix: prevent prompt injection in user input
refactor: extract embedding service from rag.py
test: add integration tests for document upload
docs: add architecture diagram to README

5. git log — 查看历史

bash

git log                          # 完整历史
git log --oneline                # 每条一行，简洁
git log --oneline -10            # 只看最近 10 条
git log --oneline --graph        # 图形化显示分支合并
git log --oneline app/services/  # 只看某个目录的历史

6. git diff — 查看改动内容

bash

git diff                         # 工作区 vs 暂存区（没 add 的改动）
git diff --staged                # 暂存区 vs 上次 commit（已 add 未 commit）
git diff main feature/rag        # 两个分支的差异
git diff HEAD~1                  # 和上一个 commit 比

7. git branch / git checkout / git switch — 分支操作

bash

# 查看分支
git branch                       # 本地分支
git branch -a                    # 本地 + 远程分支

# 创建并切换分支（推荐用 switch，更现代）
git switch -c feature/rag-pipeline    # 新建并切换
git switch main                        # 切回 main

# 旧写法（效果相同）
git checkout -b feature/rag-pipeline
git checkout main

8. git merge / git rebase — 合并分支

bash

# merge（保留完整历史，团队项目推荐）
git switch main
git merge feature/rag-pipeline

# rebase（让历史更线性，个人分支整理时用）
git switch feature/rag-pipeline
git rebase main          # 把 main 的最新改动接到当前分支基础上

9. git push / git pull — 和远程同步

bash

# push：把本地提交推到 GitHub
git push                             # 推当前分支
git push origin feature/rag          # 推指定分支
git push -u origin feature/rag       # 第一次推，-u 建立追踪关系

# pull：拉取远程最新改动（= fetch + merge）
git pull                             # 拉当前分支
git pull origin main                 # 拉指定分支

# fetch：只下载，不合并（先看看有什么改动）
git fetch origin
git log origin/main --oneline        # 看远程有哪些新提交

10. git stash — 临时搁置改动

bash

# 场景：你在 feature 分支写了一半，突然要去修 main 上的 bug
git stash                        # 把当前改动暂存起来，工作区变干净
git switch main
# 修 bug...
git switch feature/rag
git stash pop                    # 把之前的改动恢复回来

# 有多个 stash 时
git stash list                   # 查看所有 stash
git stash pop stash@{1}          # 恢复指定的
git stash drop stash@{0}         # 删除某个 stash

---

四、.gitignore（必须配置）

告诉 Git 哪些文件不要追踪——API Key、虚拟环境、缓存文件绝对不能进仓库：

gitignore

# .gitignore

# 环境变量（最重要！API Key 不能泄露）
.env
.env.local
.env.*.local

# Python
__pycache__/
*.pyc
*.pyo
.pytest_cache/
*.egg-info/
dist/
build/
.coverage
htmlcov/

# 虚拟环境
.venv/
venv/
env/

# 上传文件（体积大，不应进仓库）
uploads/
*.pdf
*.docx

# IDE
.vscode/settings.json
.idea/
*.swp

# macOS
.DS_Store

# 日志
*.log
logs/
```

---

## 五、团队工作流（Feature Branch Workflow）

这是 AI 应用开发最常用的协作方式：
```
main（始终可部署，只接受 PR 合并）
  ↑ PR
feature/rag-pipeline    ← 你在这里开发
feature/agent-tools     ← 同事在这里开发
fix/prompt-injection    ← 修 bug 的分支

完整的一次开发流程：

bash

# 1. 从最新的 main 开始
git switch main
git pull                              # 确保 main 是最新的

# 2. 新建功能分支
git switch -c feature/rag-pipeline

# 3. 开发，频繁提交（小步提交，每个提交只做一件事）
# 写了文档解析功能
git add app/services/parser.py
git commit -m "feat: add PDF and docx parser"

# 写了切块逻辑
git add app/services/chunking.py
git commit -m "feat: implement recursive chunking with overlap"

# 写了 embedding 调用
git add app/services/embedding.py
git commit -m "feat: add OpenAI embedding service with batch support"

# 4. 推到 GitHub，发 Pull Request
git push -u origin feature/rag-pipeline

# 5. 在 GitHub 上创建 PR，等代码审查

# 6. 审查通过后合并到 main（在 GitHub 上点 Merge）

# 7. 本地清理
git switch main
git pull                              # 拉取合并后的 main
git branch -d feature/rag-pipeline   # 删除已合并的本地分支

---

六、处理冲突

两个人改了同一行代码就会产生冲突，不用慌，按步骤处理：

bash

# 拉取最新代码时发生冲突
git pull
# CONFLICT (content): Merge conflict in app/services/rag.py

# 打开冲突文件，会看到：
<<<<<<< HEAD                          # 你的改动
async def retrieve(query: str, top_k: int = 5):
=======                               # 对方的改动
async def retrieve(query: str, top_k: int = 10, rerank: bool = True):
>>>>>>> origin/main

# 手动编辑，保留正确的版本（删掉标记行）：
async def retrieve(query: str, top_k: int = 10, rerank: bool = True):

# 标记冲突已解决
git add app/services/rag.py
git commit -m "merge: resolve conflict in retrieve function signature"

VS Code 打开冲突文件会有图形化界面，点按钮选"接受当前"/"接受传入"/"两者都要"，比手动编辑方便。

---

七、撤销操作（救命命令）

bash

# 撤销工作区的改动（还没 add，不可恢复）
git restore app/services/llm.py      # 撤销单个文件
git restore .                         # 撤销所有改动

# 撤销 add（还没 commit，改动还在工作区）
git restore --staged app/services/llm.py
git restore --staged .

# 撤销最后一次 commit（保留改动，改动回到工作区）
git reset HEAD~1                     # 最常用
git reset HEAD~1 --soft              # 改动回到暂存区

# 撤销最后一次 commit（丢弃改动，危险！）
git reset HEAD~1 --hard

# 已经 push 了，用 revert（不改历史，只加一条"撤销"的 commit）
git revert HEAD                      # 撤销最后一次 commit
git push                             # 推到远程

# 找回误删的内容
git reflog                           # 查看所有操作历史（包括已删除的）
git reset --hard HEAD@{2}            # 回到某个状态

---

八、AI 应用项目的 Git 实践

项目开始时必做的三件事：

bash

# 1. 初始化仓库
git init
git remote add origin https://github.com/你/你的项目.git

# 2. 先提交 .gitignore（在任何代码之前）
touch .gitignore  # 填入上面的内容
git add .gitignore
git commit -m "chore: add .gitignore"

# 3. 再提交其他文件
git add .
git commit -m "feat: initial project structure"
git push -u origin main

养成这三个习惯，能避免 80% 的 Git 问题：

提交前先 git status，确认改动范围是否符合预期，没有多提交测试文件或 .env。

commit message 用动词开头描述做了什么，不写"update"、"fix bug"这种没有信息量的词。

功能没做完也可以提交——wip: start RAG retrieval service 比几天不提交然后一个大 commit 好得多，出问题时好定位。

---

九、速查卡

场景	命令
查当前状态	git status
提交所有改动	git add . && git commit -m "..."
新建并切换分支	git switch -c feature/xxx
切换已有分支	git switch main
推到 GitHub	git push
拉取最新代码	git pull
临时搁置改动	git stash / git stash pop
查看提交历史	git log --oneline
撤销未提交改动	git restore .
撤销最后一次提交	git reset HEAD~1
查看文件改动	git diff

---

十、推荐资料

资料	链接	说明
Pro Git 中文版	git-scm.com/book/zh/v2	最权威，前3章必读
Learn Git Branching	learngitbranching.js.org/?locale=zh_CN	交互式可视化，分支操作最好的练习工具
GitHub Skills	skills.github.com	在真实 GitHub 仓库里练习
Oh Shit, Git!	ohshitgit.com/zh	专门讲怎么从各种 Git 事故里恢复

学 Git 没有捷径，花一个下午把 Learn Git Branching 的基础关卡全部打通，剩下的命令在实际项目里用就自然记住了。