“

从零基础到团队实战，渐进式掌握 Git 工作流

目录

  1. Git 核心概念速览
  2. 单人开发流程
  3. 分支管理策略
  4. 远程仓库操作
  5. 多人协作流程
  6. 冲突处理
  7. 常用场景实战
  8. 避坑指南

一、Git 核心概念速览

1.1 四个区域

工作区(Working Dir) → 暂存区(Index/Stage) → 本地仓库(Local Repo) → 远程仓库(Remote)
        git add             git commit            git push
区域 含义
工作区 你电脑上看到的文件，日常编辑的地方
暂存区 git add 后的文件暂存区，标记下次要提交的内容
本地仓库 git commit 后形成永久快照，有完整历史
远程仓库 GitHub/GitLab 等服务器上的仓库，团队协作共享

1.2 三个关键名词

  • **Commit(提交)**：一次快照，包含本次改动的内容和说明
  • **Branch(分支)**：一条独立的历史线，可以并行开发互不干扰
  • **Merge(合并)**：把两个分支的改动合到一起

二、单人开发流程

2.1 从零开始一个新项目

# 1. 初始化 Git 仓库
git init

# 2. 创建 .gitignore（排除不需要提交的文件）
# 内容示例：
# __pycache__/
# .venv/
# .env
# *.log

# 3. 添加所有文件到暂存区
git add .

# 4. 提交（第一次提交通常叫 initial commit）
git commit -m "init: project setup"

# 5. 关联远程仓库
git remote add origin https://github.com/yourname/your-repo.git

# 6. 推送到远程
git push -u origin main   # 或 master

2.2 日常开发循环

# 每次开发都遵循这个循环：
# 编辑代码 → 暂存 → 提交 → 推送

# 1. 查看当前状态（养成好习惯，随时检查）
git status

# 2. 添加改动的文件（按需添加，不要无脑 git add .）
git add main.py
git add rag/rag_chain.py

# 3. 提交并写有意义的消息
git commit -m "feat: add RRF result fusion to search pipeline"

# 4. 推送到远程
git push

2.3 常用命令速查

命令 作用
git status 查看工作区和暂存区的状态
git diff 查看未暂存的改动
git diff --cached 查看已暂存但未提交的改动
git log --oneline 简洁查看提交历史
git log -p 查看每次提交的具体改动
git add <file> 添加指定文件到暂存区
git add . 添加所有改动到暂存区
git commit -m "msg" 提交暂存区内容
git push 推送到远程
git checkout -- <file> 丢弃某个文件的未暂存改动
git reset HEAD <file> 从暂存区取消暂存某个文件

2.4 Commit 消息规范

<type>: <简短描述>

可选的详细描述

可选的 footer

常用 type：

type 含义 示例
feat 新功能 feat: add Milvus vector database integration
fix 修复 bug fix: resolve connection timeout in MilvusClient
docs 文档修改 docs: update README with setup instructions
refactor 重构（无功能变化） refactor: extract embedding logic into separate class
chore 杂务（配置、工具等） chore: update .gitignore for .env files
test 测试相关 test: add unit tests for RRF fusion
style 代码格式（不影响逻辑） style: format imports with isort

三、分支管理策略

3.1 为什么用分支

场景：你正在开发一个新功能，老板突然让你修一个紧急 bug。
如果没有分支：新功能代码写到一半被打断，改 bug 的代码和新功能混在一起。
有了分支：main 保持干净，在功能分支上新写 bug fix，互不干扰。

3.2 基本分支操作

# 创建新分支
git branch feature/new-search

# 切换到新分支
git checkout feature/new-search

# 创建并切换（一步到位，推荐）
git checkout -b feature/new-search

# 查看所有分支（* 表示当前所在分支）
git branch

# 切换回 main
git checkout main

# 合并功能分支到 main
git checkout main
git merge feature/new-search

# 删除已合并的功能分支（可选）
git branch -d feature/new-search

3.3 推荐工作流：功能分支工作流（Feature Branch Workflow）

main ─────────┬──────────────┐──────────────  (稳定版本)
              │              │
              │              │
feature/A ────┤───开发───────┤───合并回 main
              │              │
feature/B ────┤──────开发────┤───合并回 main
              │              │

规则：

  1. main 始终保持可部署状态，永远是可以用的代码
  2. 每个新功能开一个分支，从 main 分出
  3. 功能完成后合并回 main
  4. 分支命名规范：
    • feat/xxx 或 feature/xxx：新功能
    • fix/xxx 或 bugfix/xxx：修复 bug
    • refactor/xxx：重构
    • docs/xxx：文档
    • hotfix/xxx：紧急修复

3.4 实战示例

# 场景：你要给 RAG 系统加一个重排序功能

# 1. 确保在 main 分支
git checkout main
git pull origin main    # 拉取最新代码

# 2. 创建功能分支
git checkout -b feat/rerank

# 3. 开发... 写代码... 测试...
# （期间可以随时 commit）
git add reranker.py
git commit -m "feat: add cross-encoder reranker module"

# 4. 开发完成后合并回 main
git checkout main
git merge feat/rerank --no-ff    # --no-ff 保留分支历史

# 5. 推送
git push origin main

# 6. 删除功能分支
git branch -d feat/rerank

四、远程仓库操作

4.1 远程仓库基础

# 查看远程仓库
git remote -v

# 添加远程仓库
git remote add origin https://github.com/yourname/repo.git

# 修改远程仓库 URL（比如换仓库地址）
git remote set-url origin https://github.com/yourname/new-repo.git

# 删除远程仓库关联
git remote remove origin

4.2 Push 和 Pull

# 推送当前分支到远程
git push

# 首次推送，设置上游分支（-u 等价于 --set-upstream）
git push -u origin main

# 拉取远程最新代码并自动合并
git pull

# 拉取但不合并，先看看再决定
git fetch

4.3 Fetch vs Pull 的区别

git fetch： 只下载远程新提交，不修改你的工作区。安全，可以先看再决定怎么做。
git pull：  下载远程新提交 + 自动合并到你当前分支。方便，但可能产生冲突。

关系：git pull = git fetch + git merge

什么时候用 fetch？

  • 不确定远程有什么变化，想先看看
  • 怕冲突，想手动处理合并

什么时候用 pull？

  • 日常开发，确信远程不会有冲突
  • 快速同步代码

4.4 分支推送

# 推送指定分支到远程
git push origin feature/rerank

# 删除远程分支（本地分支不受影响）
git push origin --delete feature/rerank

# 推送所有分支
git push --all

五、多人协作流程

5.1 经典协作模型

场景：Alice 和 Bob 一起开发同一个项目，远程仓库在 GitHub 上。

Alice                              Bob                              GitHub
  │                                 │                                 │
  │ git clone                       │                                 │
  ├─────────────────────────────> 远程仓库                             │
  │                                 │                                 │
  │ git checkout -b feat/A          │                                 │
  │ 开发... commit...               │                                 │
  │ git push origin feat/A          │                                 │
  ├─────────────────────────────> 新分支 feat/A                        │
  │                                 │                                 │
  │                                 │ git pull origin main            │
  │                                 │ git checkout -b feat/B          │
  │                                 │ 开发... commit...               │
  │                                 │ git push origin feat/B          │
  │                                 ├─────────────────────────────> 新分支 feat/B
  │                                 │                                 │
  │                                 │              Alice 提 PR/MR      │
  │                                 │              Bob review 后合并   │

5.2 Pull Request（PR）协作流程

这是 GitHub/GitLab 上最主流的协作方式。

# 步骤 1：Fork 别人的仓库到你自己的 GitHub 账号
# （在 GitHub 网页上点 Fork 按钮）

# 步骤 2：Clone 你自己的 fork
git clone https://github.com/yourname/repo.git
cd repo

# 步骤 3：添加上游仓库（原作者的仓库）
git remote add upstream https://github.com/original-author/repo.git

# 步骤 4：从上游拉取最新代码
git checkout main
git pull upstream main

# 步骤 5：创建功能分支
git checkout -b feat/new-feature

# 步骤 6：开发...
git add .
git commit -m "feat: add new feature"
git push origin feat/new-feature

# 步骤 7：在 GitHub 上提 Pull Request
# （网页上点 "New Pull Request"）

# 步骤 8：等人 review，通过后合并

5.3 团队内协作（同一仓库）

如果团队所有人都有同一个仓库的写权限：

# 步骤 1：Clone 团队共享仓库
git clone https://github.com/team/repo.git
cd repo

# 步骤 2：创建功能分支
git checkout -b feat/my-feature

# 步骤 3：开发并提交
git add .
git commit -m "feat: implement feature"

# 步骤 4：推送到远程新分支
git push -u origin feat/my-feature

# 步骤 5：在 GitHub 上创建 PR，请同事 review

# 步骤 6：Review 通过后合并到 main

5.4 每天开工前的标准操作

# 1. 切回 main
git checkout main

# 2. 拉取远程最新代码
git pull origin main

# 3. 从 main 分出新的功能分支
git checkout -b feat/today-task

# 4. 开始开发...

5.5 每天收工前的标准操作

# 1. 确认代码能跑
# 2. 提交今天的改动
git add .
git commit -m "feat: xxx"

# 3. 推送到远程
git push

# 4. 如果功能完成了，提 PR 请求合并到 main

六、冲突处理

6.1 什么是冲突

场景：
Alice 修改了 main.py 第 10 行
Bob   也修改了 main.py 第 10 行
当 Alice 的改动和 Bob 的改动要合并时，Git 不知道该用谁的。

6.2 冲突发生在哪里

<<<<<<< HEAD
你的代码版本
=======
别人的代码版本
>>>>>>> branch-name

6.3 解决冲突的步骤

# 1. 拉取最新代码时发生冲突
git pull origin main

# 输出：CONFLICT (content): Merge conflict in main.py

# 2. 打开冲突文件，找到 <<<< 和 >>>> 标记
# 手动编辑文件，决定保留哪些代码，删除标记符号

# 3. 标记冲突已解决
git add main.py

# 4. 完成合并
git commit -m "fix: resolve merge conflict in main.py"

# 5. 如果有多个冲突文件，重复步骤 2-3 解决所有冲突后再 commit

6.4 预防冲突的技巧

技巧 说明
频繁 pull 每天开工前 git pull，减少代码差异
小步提交 每次 commit 改得少，冲突概率低
不同文件 团队内约定，不同人改不同文件
及时合并 功能做完就提 PR 合并，别拖着
分支同步 长期分支定期 git merge main 保持同步

七、常用场景实战

7.1 场景：临时切出去修 bug

# 正在开发功能，突然要修紧急 bug

# 方法一：git stash（暂存改动）
git stash                    # 保存当前未提交的改动
git checkout main            # 切回 main
git checkout -b hotfix/bug   # 创建修复分支
# 修 bug...
git add .
git commit -m "fix: xxx"
git checkout main
git merge hotfix/bug
git push origin main

# 修完 bug 回来继续开发
git checkout feat/my-feature
git stash pop                # 恢复之前暂存的改动

7.2 场景：提交错了，想修改最后一次 commit

# 情况 A：提交消息写错了
git commit --amend -m "correct message"

# 情况 B：漏了一个文件没加
git add forgot-this.py
git commit --amend --no-edit    # 加到上一次提交中，不改消息

7.3 场景：想撤销一次错误的提交

# 方法一：git revert（推荐，安全）
git revert HEAD    # 创建一个新提交，撤销上次的改动
                   # 不修改历史，适合已推送的提交

# 方法二：git reset（危险，会丢提交）
git reset --hard HEAD~1    # 回退一个提交，本地改动全丢
git reset --soft HEAD~1    # 回退提交，但改动保留在暂存区

7.4 场景：想把多个小提交合并成一个

# 方法：交互式 rebase
git rebase -i HEAD~3    # 把最近 3 个提交合并

# 编辑器里会把 pick 改成 squash：
# pick abc123 feat: step 1
# squash def456 feat: step 2    ← 改成 squash
# squash ghi789 feat: step 3    ← 改成 squash

# 保存退出后，Git 会让你写一个新的合并提交消息

7.5 场景：远程有更新，本地有未提交的改动

# 错误做法：直接 git pull（可能冲突）

# 正确做法：
git stash                    # 先暂存本地改动
git pull origin main         # 拉取远程更新
git stash pop                # 恢复本地改动
# 如果有冲突，手动解决

7.6 场景：想看看某次提交改了什么

# 查看某次提交的改动
git show <commit-hash>

# 查看某次提交修改了哪些文件
git show --stat <commit-hash>

# 查看两个提交之间的差异
git diff <hash1> <hash2>

八、避坑指南

8.1 永远不要做的事

行为 后果
git push --force 到 main 覆盖别人的提交，团队灾难
在 main 上直接开发 不稳定代码进入主分支
提交 .env、密码、API Key 泄露敏感信息（即使删了提交历史也能找回）
超大文件提交（>100MB） GitHub 会拒绝，后续处理很麻烦
长时间不提交 改动太多难以 review，容易出问题

8.2 .gitignore 必须排除的

# Python
__pycache__/
*.pyc
*.pyo
*.egg-info/
.venv/
venv/

# 环境变量
.env
.env.local
.env.production

# IDE
.idea/
.vscode/

# OS
.DS_Store
Thumbs.db

# 本地数据（大文件）
*.db
*.sqlite
data/raw/

8.3 Git 黄金法则

  1. 频繁提交，小步前进：每次提交只做一个小改动
  2. 提交前检查： git diff 看一下改了啥
  3. 写好提交消息：让别人（和未来的你）知道为什么改
  4. main 永远可用：不稳定的代码只在功能分支上
  5. 每天同步： git pull 保持本地和远程一致
  6. 敏感信息不进 Git： .gitignore 排除 .env，用环境变量管理密钥

8.4 出了问题怎么办

# 终极救命命令（查看所有操作历史）
git reflog

# 这个命令记录了你的每一次 HEAD 变化
# 哪怕你误删了分支、reset 错了，都能从 reflog 找回来

# 恢复到某个历史状态
git reset --hard HEAD@{5}    # 回到 5 步之前的状态

附录：命令速查卡

单人开发

git init                              # 初始化仓库
git add .                             # 添加所有文件
git commit -m "msg"                   # 提交
git remote add origin <url>           # 关联远程仓库
git push -u origin main               # 首次推送
git status                            # 查看状态
git log --oneline                     # 查看历史

分支操作

git branch                            # 查看分支
git branch <name>                     # 创建分支
git checkout <name>                   # 切换分支
git checkout -b <name>                # 创建并切换
git merge <branch>                    # 合并分支
git branch -d <name>                  # 删除分支

远程操作

git remote -v                         # 查看远程仓库
git fetch                             # 拉取远程更新（不合并）
git pull                              # 拉取 + 合并
git push                              # 推送
git push origin --delete <branch>     # 删除远程分支

撤销与修复

git stash                             # 暂存未提交的改动
git stash pop                         # 恢复暂存的改动
git commit --amend                    # 修改最后一次提交
git reset HEAD <file>                 # 从暂存区移除
git checkout -- <file>                # 丢弃未暂存的改动
git revert HEAD                       # 撤销最近一次提交
git reflog                            # 查看所有操作历史

本文由 mdnice 多平台发布

# 后端
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

编程代理的下一站，是给自己造一具“身体“

avatar AI编程社区
cover

AtomCode 源码编译与二次开发入门：从 Clone 仓库到自定义 Agent 工具的完整指南

avatar AI编程社区
cover

ChatGPT、Codex实战：为什么AI明明理解了代码，却还是改不对？

avatar AI编程社区