本文档是一份全面的Git使用手册,从基础入门到进阶实战,涵盖Git核心概念、对象模型与底层原理、本地操作、远程协作、分支管理与策略、标签管理、问题排查、高级技巧与生态工具等所有高频使用场景,适配新手入门、日常开发、团队协作等不同需求,所有命令均经过实战验证,可直接复制使用,同时补充常见坑点与避坑方案,助力快速掌握Git操作。

适用人群:Git新手、开发工程师、测试工程师、运维工程师、团队管理者;适配系统:Windows、Mac、Linux(所有命令通用,仅安装与配置有细微差异)。

第一章 Git 基础入门

1.1 Git 核心概念

在使用Git前,需先理解3个核心概念,避免后续操作混乱,这是区别于其他版本控制工具(如SVN)的关键:

  • 工作区(Workspace):本地电脑中存放项目文件的目录,就是我们日常编辑代码、修改文件的地方,也是最常操作的区域。

  • 暂存区(Stage/Index):临时存放修改的文件,相当于工作区和版本库之间的“中转站”。修改文件后,需先提交到暂存区,再从暂存区提交到版本库,可灵活选择部分修改提交。

  • 版本库(Repository):Git的核心,存放所有版本信息的地方,分为本地版本库(.git目录,隐藏)和远程版本库(如GitHub、Gitee、GitLab)。

核心流程:工作区修改 → 暂存区暂存 → 版本库提交 → 远程仓库推送(团队协作)。

1.2 Git 安装与初始配置

1.2.1 安装步骤

  1. 下载安装包:访问Git官方网站(https://git-scm.com/),根据系统选择对应版本(Windows选64-bit Git for Windows Setup,Mac选macOS Installer)。

  2. 安装操作:

    • Windows:双击安装包,默认下一步即可,建议勾选“Add Git Bash Here”(右键菜单添加Git命令行入口),其余默认配置。

    • Mac:双击.dmg文件,拖拽Git到Applications目录,或通过Homebrew安装(命令:brew install git)。

    • Linux:通过系统包管理器安装,Ubuntu/Debian命令:sudo apt-get install git;CentOS/RHEL命令:sudo yum install git。

  3. 验证安装:打开终端(Windows打开Git Bash),输入命令 git --version,若显示版本号(如git version 2.43.0),则安装成功。

1.2.2 初始配置

安装完成后,需配置用户名和邮箱,这会作为后续所有提交记录的标识(绑定远程仓库时也需匹配),配置分为全局配置和局部配置(单个项目)。

# 1. 全局配置(所有本地项目通用,推荐优先配置)
git config --global user.name "你的用户名"  # 例如:git config --global user.name "ZhangSan"
git config --global user.email "你的邮箱"    # 例如:git config --global user.email "zhangsan@163.com"

# 2. 局部配置(仅当前项目生效,优先级高于全局配置)
# 需先进入项目目录(cd 项目路径),再执行以下命令
git config user.name "你的用户名"
git config user.email "你的邮箱"

# 3. 查看配置信息(验证配置是否生效)
git config --list  # 查看所有配置(全局+局部)
git config user.name  # 单独查看用户名
git config user.email  # 单独查看邮箱

# 4. 清除配置(如需修改)
git config --global --unset user.name  # 清除全局用户名
git config --global --unset user.email  # 清除全局邮箱
git config --unset user.name  # 清除当前项目用户名(需在项目目录下)

1.2.3 可选配置

# 1. 配置默认文本编辑器(如VS Code,可替换为自己常用的编辑器)
git config --global core.editor "code --wait"

# 2. 配置忽略文件权限变化(避免Windows和Mac/Linux之间协作出现权限冲突)
git config --global core.filemode false

# 3. 配置命令别名(简化输入,可选)
git config --global alias.st status  # 用git st 代替 git status
git config --global alias.co checkout  # 用git co 代替 git checkout
git config --global alias.br branch  # 用git br 代替 git branch
git config --global alias.ci commit  # 用git ci 代替 git commit
git config --global alias.logg "log --graph --pretty=oneline --abbrev-commit"  # 简化日志查看

1.3 Git 本地基础操作

本地操作是Git使用的基础,涵盖项目初始化、文件修改、暂存、提交、日志查看等核心步骤,所有操作均在终端(Git Bash)中执行。

1.3.1 初始化本地仓库

# 场景1:新建本地项目,初始化Git仓库(从无到有)
# 1. 新建项目目录(可选,也可进入已存在的目录)
mkdir git-demo  # 新建目录(目录名可自定义)
cd git-demo     # 进入项目目录

# 2. 初始化Git仓库(执行后,目录下会生成隐藏的.git文件夹,即本地版本库)
git init

# 场景2:克隆远程仓库到本地(已有远程项目,如GitHub上的项目)
# 命令格式:git clone 远程仓库地址(HTTPS或SSH)
git clone https://github.com/xxx/xxx.git  # HTTPS地址(无需配置SSH,每次推送需输账号密码)
git clone git@github.com:xxx/xxx.git      # SSH地址(需配置SSH密钥,无需重复输账号密码)

# 说明:克隆后,本地会自动生成与远程仓库同名的目录,且已关联远程仓库,可直接进行后续操作

1.3.2 文件修改与状态查看

# 1. 查看当前Git仓库状态(最常用命令,每天必用)
git status  # 简化命令:git st(需配置别名)
# 常见状态说明:
# - Untracked files:未跟踪文件(新创建的文件,Git未记录)
# - Changes not staged for commit:已修改但未暂存的文件(修改了已跟踪的文件)
# - Changes to be committed:已暂存但未提交的文件(已添加到暂存区)
# - nothing to commit, working tree clean:工作区干净,无修改、无未跟踪文件

# 2. 查看文件具体修改内容(对比工作区与暂存区的差异)
git diff  # 查看所有修改文件的差异
git diff 文件名  # 查看指定文件的修改差异(如:git diff README.md)

# 3. 查看暂存区与本地版本库的差异(暂存后,未提交前)
git diff --cached  # 或 git diff --staged

1.3.3 暂存文件(工作区 → 暂存区)

# 1. 暂存指定文件(推荐,精准控制暂存内容)
git add 文件名1 文件名2  # 例如:git add README.md src/main.java

# 2. 暂存所有已修改、已删除的文件(不包含未跟踪文件)
git add -u  # 或 git add --update

# 3. 暂存所有文件(包含未跟踪、已修改、已删除,常用但需谨慎)
git add .  # 注意:是英文句号,不是星号(*)
# 说明:git add . 会暂存当前目录及子目录下的所有变化,适合一次性暂存所有修改,但需避免暂存无用文件(如编译产物、日志)

# 4. 取消暂存(暂存区 → 工作区,未提交前可撤销)
git reset HEAD 文件名  # 取消指定文件的暂存(如:git reset HEAD README.md)
git reset HEAD .      # 取消所有文件的暂存
# 2.23+ 推荐使用语义更清晰的 git restore --staged,见 1.3.6 节
git restore --staged 文件名  # 等价于 git reset HEAD 文件名
git restore --staged .      # 等价于 git reset HEAD .

# 5. 交互式暂存(按代码块挑选部分修改提交,常用于拆分提交)
git add -p 文件名  # 按代码块(hunk)逐个询问是否暂存,输入 y 暂存 / n 跳过 / s 拆分更细 / e 手动编辑 / q 退出
git add -p         # 对所有已修改文件进行交互式暂存
# 交互式选项说明:
# - y(yes):暂存当前块
# - n(no):跳过当前块
# - s(split):将当前块进一步拆分为更小的块(若可拆分)
# - e(edit):手动编辑当前块,可删除部分行实现精准暂存
# - a(all):暂存当前文件剩余所有块
# - d(discard):跳过当前文件剩余所有块
# - q(quit):退出交互模式
# - ?(help):查看帮助
# 场景:一个文件中既有功能代码改动,又有调试日志或格式化调整,需拆为两个独立提交,便于评审与回溯


#### 1.3.4 提交文件(暂存区 → 本地版本库)

```bash
# 1. 基础提交(暂存后,提交到本地版本库)
git commit -m "提交说明"  # 简化命令:git ci -m "提交说明"
# 提交说明规范(团队协作必守,遵循 Conventional Commits 1.0.0):
# 完整格式:<type>[optional scope]: <description>
# 
#           [optional body]
# 
#           [optional footer(s)]
#
# - type 类型(必填,小写):
#   feat(新功能)、fix(修复 bug)、docs(文档)、style(格式调整,不影响代码运行,如空格、分号)、
#   refactor(重构,非新增功能也非修复)、perf(性能优化)、test(测试相关)、build(构建系统或外部依赖)、
#   ci(CI 配置)、chore(杂项,不修改 src 或测试)、revert(回滚之前的提交)
# - scope(可选):影响范围,如模块名、组件名,放在括号内,如 feat(auth): 新增邮箱登录
# - description(必填):简洁明了,祈使句现在时(如 "add" 而非 "added"),不超过 50 字
# - body(可选):详细说明动机、与之前行为的对比,每行不超过 72 字,与说明之间留一空行
# - footer(可选):
#   - BREAKING CHANGE: 大写开头,描述破坏性变更(如 BREAKING CHANGE: 移除 legacy-login 接口)
#   - 或使用 ! 标记:如 feat(api)!: 重构登录返回结构(破坏性变更,等价于 BREAKING CHANGE)
#   - 关闭 Issue:如 Closes #123, #456;或 Resolves #123
# 示例:
# git commit -m "feat(auth): 新增邮箱验证码登录" -m "支持国内外邮箱,验证码有效期 5 分钟" -m "Closes #88"
# 多个 -m 参数之间会以空行分隔,自动拼装为 body 与 footer


# 2. 跳过暂存区,直接提交已修改的跟踪文件(不推荐频繁使用)
git commit -a -m "提交说明"  # 或 git commit --all -m "提交说明"
# 说明:相当于先执行 git add -u,再执行 git commit -m,未跟踪文件无法用此命令提交

# 3. 补充提交(修改上次提交,未推送远程前可用)
# 场景:上次提交遗漏文件,或提交说明写错,无需新增一个提交记录
git commit --amend  # 会打开文本编辑器,修改上次的提交说明
git commit --amend -m "新的提交说明"  # 直接修改提交说明,不修改文件
git add 遗漏的文件 && git commit --amend  # 补充遗漏的文件,合并到上次提交

# 4. 取消提交(本地版本库 → 暂存区,未推送远程前可撤销)
git reset --soft HEAD~1  # 撤销上次提交,暂存区内容保留(可重新提交)
git reset --mixed HEAD~1 # 撤销上次提交,暂存区内容也撤销(回到“已修改未暂存”状态,默认)
git reset --hard HEAD~1  # 撤销上次提交,暂存区和工作区内容全部撤销(谨慎使用,会丢失本地修改)
# 说明:HEAD~1 表示上一个版本,HEAD~2 表示上上个版本,以此类推

1.3.5 查看提交日志

# 1. 查看所有提交日志(按时间倒序,最新的在最上面)
git log  # 简化命令:git logg(需配置别名,显示更简洁的图形化日志)

# 2. 查看简洁版日志(只显示提交ID、提交人、提交时间、提交说明)
git log --oneline  # 每个提交占一行,提交ID显示前7位(足够唯一)

# 3. 查看图形化日志(清晰显示分支合并记录,推荐团队协作时使用)
git log --graph --oneline --abbrev-commit  # 简化命令:git logg(配置别名后)

# 4. 查看指定数量的日志(如查看最近3次提交)
git log -3  # 查看最近3次提交,可替换为任意数字
git log --oneline -5  # 简洁版,查看最近5次提交

# 5. 查看指定文件的提交日志(跟踪文件的修改历史)
git log 文件名  # 如:git log README.md

# 6. 查看提交的详细修改内容(包含每次提交的文件变化)
git log -p  # 查看所有提交的详细差异
git log -p -2  # 查看最近2次提交的详细差异
git log -p 文件名  # 查看指定文件的提交差异

1.3.6 撤销本地修改(工作区操作)

# 场景1:未暂存的修改(已修改,未执行git add),撤销到上次提交后的状态
git checkout -- 文件名  # 如:git checkout -- README.md(简化命令:git co -- README.md)
git checkout -- .      # 撤销所有未暂存的修改(谨慎使用,会丢失所有本地未暂存的修改)

# 场景2:已暂存的修改(执行了git add,未执行git commit),先撤销暂存,再撤销修改
git reset HEAD 文件名  # 1. 撤销暂存
git checkout -- 文件名  # 2. 撤销修改

# 场景3:已提交的修改(执行了git commit,未推送远程),撤销到上一个版本(保留修改)
git reset --soft HEAD~1  # 撤销提交,修改保留在暂存区
git reset --mixed HEAD~1 # 撤销提交和暂存,修改保留在工作区(默认)

# 注意:以上命令均只影响本地,未推送远程前可安全使用;若已推送远程,请勿随意使用reset命令

1.3.7 语义化命令 git restore 与 git switch

Git 2.23 起官方将 checkout 的多重重载职责拆分,引入 git restore(恢复工作区/暂存区)与 git switch(切换/创建分支)两条语义清晰的命令。新仓库建议优先使用,checkout 旧写法仍兼容,无需修改历史脚本。

# 1. git restore:恢复工作区文件(替代 git checkout --)
git restore 文件名            # 用暂存区内容覆盖工作区,丢弃工作区未暂存修改
git restore .                 # 恢复所有跟踪文件的工作区修改
git restore --source=HEAD~1 文件名  # 用指定提交的内容恢复,可跨版本回滚
git restore --staged 文件名   # 用 HEAD 内容覆盖暂存区,取消暂存(替代 git reset HEAD 文件名)
git restore --staged --worktree 文件名  # 同时还原暂存区与工作区,等同于完全丢弃该文件改动
git restore --source=origin/master 文件名  # 用远程分支内容恢复,常用于丢弃本地修改与远程对齐

# 2. git switch:切换与创建分支(替代 git checkout 的分支相关用法)
git switch 分支名             # 切换到已存在的本地分支
git switch -c 新分支名        # 创建并切换到新分支(替代 git checkout -b)
git switch -c 新分支名 基准分支  # 基于指定分支创建并切换
git switch -                  # 切回上一个分支(类似 cd -)
git switch --detach 提交ID    # 进入分离 HEAD 状态,常用于查看历史版本

# 3. git restore 的冲突场景
# 若当前文件存在 merge/rebase 冲突标记,git restore 不会覆盖未解决的冲突内容,需先解决冲突再恢复

1.4 Git 对象模型与底层原理

掌握 Git 的对象模型,可从根本上理解 add、commit、branch、reset、stash 等命令的运行机制,也是排查复杂问题(如 reflog 恢复、rebase 冲突、对象损坏)的基础。Git 与 SVN 等集中式版本控制工具的根本区别即在于此。

1.4.1 四类核心对象

Git 的所有版本数据均存储于 .git 目录下,本质是一个内容寻址的键值存储(key-value store),键为对象内容的 SHA-1 哈希值,值为对象本身。共有四类对象:

  • blob:文件内容快照,仅存储文件内容,不含文件名与路径。相同内容的不同文件共享同一个 blob,节省空间。
  • tree:目录快照,记录目录下的条目(文件名、子目录名、对应 blob 或子 tree 的哈希、文件模式)。一个 tree 描述一个完整的目录结构。
  • commit:提交对象,包含一个顶层 tree 的哈希、父提交的哈希(merge 提交有多个父提交)、作者/提交人信息、时间戳与提交说明。提交之间通过父提交哈希构成有向无环图(DAG)。
  • tag(annotated):附注标签对象,包含被标记 commit 的哈希、标签作者、说明等。轻量标签不生成独立对象,仅是一个引用。

关系链路:commit → tree →(子 tree / blob)。git cat-file -p <对象哈希> 可查看任意对象内容,git cat-file -t <对象哈希> 可查看对象类型,常用于排查仓库内部结构。

1.4.2 引用(refs)与 HEAD

引用(ref)是指向某个 commit 哈希的命名指针,存储于 .git/refs 目录下:

  • 本地分支引用:.git/refs/heads/<分支名>,内容为该分支最新提交的哈希。
  • 远程分支引用:.git/refs/remotes/<远程别名>/<分支名>,记录远程分支在本地最后一次 fetch 时的位置。
  • 标签引用:.git/refs/tags/<标签名>,附注标签指向 tag 对象,轻量标签直接指向 commit。
  • HEAD:.git/HEAD 是特殊引用,记录当前所在分支(如 ref: refs/heads/master),间接指向当前分支最新提交。

除 HEAD 外,Git 还维护若干临时引用指针,常用于命令执行失败后回滚:

  • ORIG_HEAD:上一次会改变 HEAD 的危险操作(merge、rebase、reset、pull)执行前的 HEAD 位置,git reset --hard ORIG_HEAD 可快速回滚。
  • FETCH_HEAD:最近一次 git fetch 拉取的远程分支引用与提交记录。
  • MERGE_HEAD:合并进行中指向被合并分支的提交。
  • CHERRY_PICK_HEAD、REBASE_HEAD 等:对应操作进行中的临时指针。

1.4.3 配置文件优先级

Git 配置按读取顺序与覆盖关系,分为三层,优先级从低到高:

  • system(系统级):/etc/gitconfig(Windows 为 Git 安装目录下的 etc/gitconfig),作用于该机器所有用户与所有仓库。读取命令:git config --system --list。
  • global(用户级):~/.gitconfig(Windows 为 C:\Users\<用户名>\.gitconfig),作用于当前用户的所有仓库。读取命令:git config --global --list。
  • local(仓库级):.git/config,仅作用于当前仓库,优先级最高。读取命令:git config --local --list。

同名配置低层被高层覆盖,最终生效值可用 git config <键> 查询,全量生效配置可用 git config --list 查看(含来源标注需配合 --show-origin)。

1.4.4 对象的不可变性与垃圾回收

Git 对象一旦创建即不可修改,所有"修改"操作(amend、rebase、reset)本质是创建新对象并移动分支引用,旧对象并不会立即删除,而是成为"悬挂对象"(dangling object),仍可通过 reflog 或哈希访问。这也是误删分支、误 reset 后能恢复的根本原因。

git gc 与 git prune 会清理超过保留期(默认 90 天,reflog 引用的为 30 天)的不可达对象,回收磁盘空间。配置项 gc.reflogExpire 与 gc.reflogExpireUnreachable 可调整保留时长,重要仓库可适当延长,确保恢复窗口充足。

第二章 Git 远程仓库操作

本地仓库仅适合个人开发,团队协作需依赖远程仓库(如GitHub、Gitee、GitLab),核心操作包括关联远程仓库、推送代码、拉取代码、拉取远程分支等,确保团队成员代码同步。

2.1 远程仓库核心概念

  • 远程仓库地址:分为HTTPS和SSH两种,用于本地仓库与远程仓库的连接。

    • HTTPS地址:无需配置密钥,每次推送/拉取需输入远程仓库账号密码(适合新手、临时使用)。

    • SSH地址:需配置SSH密钥,配置后无需重复输入账号密码(适合长期开发、团队协作,推荐)。

  • 远程仓库别名:Git默认给远程仓库起别名为“origin”,可自定义别名(如“gitee”“github”),简化命令输入。

  • 远程分支:远程仓库中的分支,与本地分支对应,团队协作需同步本地分支与远程分支。

2.2 SSH密钥配置

若使用SSH地址连接远程仓库,需先配置SSH密钥(本地生成密钥,远程仓库添加公钥),配置一次,终身可用(同一台电脑)。

# 1. 检查本地是否已存在SSH密钥(避免重复生成)
cd ~/.ssh  # 进入SSH密钥目录(Windows目录:C:\Users\你的用户名\.ssh)
# 若提示“没有那个文件或目录”,说明未生成过密钥,直接执行下一步;否则可跳过生成步骤

# 2. 生成SSH密钥(一路回车,无需输入密码)
# 推荐:使用 ed25519 算法(更短、更快、更安全,GitHub/Gitee/GitLab 均优先推荐)
ssh-keygen -t ed25519 -C "你的邮箱"  # 邮箱与Git配置的邮箱一致(如:zhangsan@163.com)
# 执行后,会在~/.ssh目录下生成两个文件:
# - id_ed25519:私钥(重要,请勿泄露,保存在本地)
# - id_ed25519.pub:公钥(需复制到远程仓库)

# 兼容:旧系统或旧版 Git 不支持 ed25519 时,使用 RSA 算法(建议至少 4096 位)
ssh-keygen -t rsa -b 4096 -C "你的邮箱"  # 生成 id_rsa / id_rsa.pub
# 注意:RSA-2048 及以下已被 GitHub/Gitee 逐步弃用,新密钥请勿使用

# 3. 查看并复制公钥内容
# Windows:打开Git Bash,执行以下命令
cat ~/.ssh/id_ed25519.pub  # ed25519 公钥
# 或 RSA 公钥:cat ~/.ssh/id_rsa.pub
# Mac/Linux:执行以下命令,或直接打开文件复制
cat ~/.ssh/id_ed25519.pub
# 复制输出的所有内容(从 ssh-ed25519 开始,到邮箱结束,不要遗漏任何字符)

# 4. 远程仓库添加公钥(以Gitee为例,GitHub、GitLab操作类似)
# 1. 登录Gitee,进入“个人设置” → “SSH公钥”
# 2. 粘贴复制的公钥内容,填写标题(自定义,如“我的笔记本电脑”)
# 3. 点击“确定”,添加完成

# 5. 验证SSH配置是否生效
ssh -T git@gitee.com  # Gitee验证命令
ssh -T git@github.com  # GitHub验证命令
# 若提示“Hi 用户名! You've successfully authenticated...”,说明配置成功

2.3 远程仓库基础操作

2.3.1 关联远程仓库(本地仓库 → 远程仓库)

# 1. 查看当前关联的远程仓库
git remote  # 查看远程仓库别名(默认origin,若未关联,无输出)
git remote -v  # 查看远程仓库别名及对应的地址(详细信息)

# 2. 关联远程仓库(本地已有仓库,首次关联远程)
# 命令格式:git remote add 远程别名 远程仓库地址
git remote add origin git@github.com:xxx/xxx.git  # SSH地址,别名origin(推荐)
git remote add origin https://github.com/xxx/xxx.git  # HTTPS地址,别名origin

# 3. 修改远程仓库地址(如远程仓库地址变更,或误关联错误地址)
git remote set-url origin 新的远程仓库地址  # 替换origin对应的地址

# 4. 删除远程仓库关联(如需取消关联)
git remote rm origin  # 删除别名origin对应的远程仓库关联

2.3.2 推送本地代码到远程仓库(本地 → 远程)

# 1. 首次推送本地分支到远程仓库(需指定分支,绑定本地与远程分支)
# 命令格式:git push -u 远程别名 本地分支名:远程分支名
git push -u origin master:master  # 推送本地master分支到远程master分支(可简写为git push -u origin master)
git push -u origin develop:develop  # 推送本地develop分支到远程develop分支
# 说明:-u 参数表示绑定本地分支与远程分支,后续推送可简化命令(无需指定分支)

# 2. 非首次推送(已绑定分支,本地提交后直接推送)
git push  # 简化命令,默认推送当前分支到绑定的远程分支
git push origin 本地分支名  # 若未绑定分支,需指定分支(如:git push origin master)

# 3. 推送本地所有分支到远程仓库(不推荐,按需使用)
git push --all origin

# 4. 强制推送(谨慎使用!覆盖远程仓库对应分支的内容,会丢失远程修改)
# 场景:本地撤销了已推送的提交,需强制同步到远程(仅自己使用的分支可使用)
git push -f origin 本地分支名  # 或 git push --force origin 本地分支名
# 注意:团队共用分支(如master、develop)严禁使用强制推送,会导致团队成员代码丢失

# 5. 推送标签到远程仓库(后续标签管理会详细说明)
git push origin 标签名  # 推送指定标签
git push origin --tags  # 推送所有标签

2.3.3 拉取远程代码到本地仓库(远程 → 本地)

拉取操作用于同步远程仓库的最新代码到本地,避免本地代码与远程代码冲突,团队协作时,每天开发前需先拉取远程代码。

# 1. 拉取远程分支最新代码(不合并到本地当前分支,仅下载到本地版本库)
git fetch origin 远程分支名  # 如:git fetch origin master(下载远程master分支最新代码)
git fetch origin  # 下载所有远程分支的最新代码

# 2. 拉取远程分支最新代码,并合并到本地当前分支(最常用,相当于fetch + merge)
git pull  # 简化命令,拉取当前分支绑定的远程分支代码,并合并(已绑定分支)
git pull origin 远程分支名:本地分支名  # 拉取指定远程分支,合并到本地指定分支
# 例如:git pull origin master:master(拉取远程master,合并到本地master)
# 例如:git pull origin develop:my-feature(拉取远程develop,合并到本地my-feature分支)

# 3. 拉取远程分支到本地,创建新的本地分支(本地无对应分支时)
git pull origin 远程分支名:本地新分支名  # 如:git pull origin feature/user:feature/user

# 注意:拉取代码时,若本地有未提交的修改,会提示冲突,需先提交本地修改,或 stash 暂存本地修改(后续会讲)

2.3.4 拉取远程新分支到本地

场景:团队成员在远程仓库新建了一个分支(如feature/pay),本地需拉取该分支,进行开发。

# 方法1:先fetch,再创建本地分支并关联远程分支
git fetch origin  # 下载所有远程分支最新信息
git checkout -b 本地分支名 origin/远程分支名  # 创建本地分支,并关联远程分支
# 例如:git checkout -b feature/pay origin/feature/pay(本地分支名与远程一致,推荐)

# 方法2:直接拉取,自动创建本地分支并关联
git pull origin 远程分支名:本地分支名  # 如:git pull origin feature/pay:feature/pay

# 验证关联:执行git branch -vv,查看本地分支对应的远程分支

2.4 远程仓库其他常用操作

# 1. 查看远程仓库的详细信息(如分支、提交记录)
git remote show origin  # 查看别名origin对应的远程仓库详细信息

# 2. 从远程仓库删除分支(需有远程仓库操作权限)
git push origin --delete 远程分支名  # 如:git push origin --delete feature/old

# 3. 从远程仓库删除标签(需有远程仓库操作权限)
git push origin --delete tag 标签名  # 如:git push origin --delete tag v1.0.0

# 4. 同步远程仓库的分支信息(更新本地对远程分支的认知)
git remote update origin --prune  # 清理本地不存在的远程分支(如远程已删除的分支,本地同步删除)

2.5 凭据持久化配置

HTTPS 连接方式每次推送/拉取均会询问账号密码,体验较差。Git 提供凭据存储机制,避免重复输入。三种模式:

  • cache:凭据保存在内存中,进程退出后仍保留一段时间(默认 900 秒),不写入磁盘,适合公用机器。
  • store:凭据明文保存在 ~/.git-credentials 文件,长期有效但明文存储有泄露风险,仅适用于个人机器。
  • osxkeychain(Mac)/ manager(Windows Git for Windows 自带)/ libsecret(Linux):调用系统钥匙串或凭据管理器,安全且推荐。
# 1. 配置凭据存储模式(全局生效)
git config --global credential.helper store          # 明文文件存储(不推荐敏感场景)
git config --global credential.helper cache         # 内存缓存,默认 15 分钟
git config --global credential.helper 'cache --timeout=3600'  # 自定义缓存时长(秒)

# Windows:默认使用 manager(Git Credential Manager),首次推送时弹出系统凭据框
# Mac:使用 osxkeychain
git config --global credential.helper osxkeychain
# Linux(需安装 libsecret):git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

# 2. 多账号场景:按远程主机分别配置凭据
# 编辑 ~/.gitconfig,使用 conditional includes 或 URL 重写
# 示例:公司 GitLab 与个人 GitHub 使用不同账号
# [credential "https://gitlab.company.com"]
#     helper = store
# [credential "https://github.com"]
#     helper = store

# 3. 使用访问令牌(Personal Access Token, PAT)替代密码
# GitHub 自 2021 年起密码鉴权已禁用,需使用 PAT
# 推送时用户名填账号名,密码位置填 PAT(如 ghp_xxx)
# 或将 PAT 嵌入 URL:git remote set-url origin https://<用户名>:<PAT>@github.com/<用户名>/<仓库>.git(注意 PAT 会写入 .git/config,慎用)

# 4. 清除已保存的凭据
# Windows:控制面板 → 凭据管理器 → Windows 凭据 → 找到对应远程仓库凭据删除
# Mac:钥匙串访问 → 搜索远程仓库域名 → 删除
# store 模式:删除 ~/.git-credentials 文件中对应行
git config --global --unset credential.helper  # 取消凭据助手配置

2.6 Pull Request 与 Merge Request

Pull Request(PR,GitHub/Gitee 用语)与 Merge Request(MR,GitLab 用语)是远程仓库托管的代码评审机制,并非 Git 本身命令,但属于团队协作的核心环节。

  • 本质:一个分支合并请求,请求将源分支合并到目标分支,附带评审、讨论、CI 检查、冲突解决等功能。
  • 源分支:开发者提交修改的分支(如 feature/user-login),通常称为 head branch。
  • 目标分支:合并目标(如 develop、master),通常称为 base branch。
  • 生命周期:推送源分支 → 在托管平台发起 PR/MR → 评审(评论、变更请求、批准) → CI 通过 → 合并 → 删除源分支。

发起 PR/MR 前的本地准备:

# 1. 基于最新目标分支创建源分支,避免后续冲突
git switch develop
git pull origin develop
git switch -c feature/user-login

# 2. 完成开发并提交(遵循 Conventional Commits)
git add .
git commit -m "feat(user): 新增用户注册接口"

# 3. 推送源分支到远程
git push -u origin feature/user-login

# 4. 在托管平台(GitHub/Gitee/GitLab)页面点击 "New Pull Request" / "New Merge Request"
# 选择源分支 feature/user-login 与目标分支 develop,填写标题、说明(关联 Issue),发起评审

合并前的同步与冲突预处理(高频操作):

# 1. 拉取目标分支最新代码到本地
git switch develop
git pull origin develop
git switch feature/user-login

# 2. 将目标分支合并/变基到源分支,提前解决冲突,避免 PR/MR 显示 "Conflicts" 状态
git merge develop                  # 方式一:合并,保留分支历史
git rebase develop                 # 方式二:变基,历史更简洁(个人 feature 分支推荐)
git push -f origin feature/user-login  # rebase 后需强制推送(仅个人分支)

# 3. 合并策略选择
# - Squash and merge:将源分支多个提交压缩为一个,目标分支历史干净,适合小特性分支
# - Rebase and merge:逐个应用源分支提交,无 merge 提交
# - Merge commit:保留分支历史与 merge 提交,适合长期特性分支
# 平台页面提供选项,命令行对应:
git merge --squash feature/user-login && git commit -m "feat(user): 新增用户注册接口"

合并后清理与回滚:

# 1. 删除本地源分支(已合并,可安全删除)
git switch develop
git branch -d feature/user-login

# 2. 删除远程源分支(PR/MR 合并时平台通常提供 "删除源分支" 选项)
git push origin --delete feature/user-login

# 3. 误合并回滚(PR/MR 已合并到目标分支,需撤销)
# 通过平台 "Revert" 按钮自动生成反向合并提交(推荐,保留历史)
# 或命令行:基于合并提交 ID 创建反向提交
git switch develop
git revert -m 1 <合并提交ID>     # -m 1 指定保留目标分支(第一父提交)侧
git push origin develop

第三章 Git 分支管理

分支是Git的核心功能之一,用于隔离不同的开发任务(如新功能开发、bug修复),避免不同任务的代码相互干扰,团队协作需遵循规范的分支管理流程(如Git Flow、GitHub Flow)。

3.1 分支核心概念与规范

3.1.1 常见分支类型

  • master/main 分支:主分支,存放正式上线的代码,禁止直接在该分支上开发、提交,仅通过合并其他分支(如develop、hotfix)更新代码。

  • develop 分支:开发分支,团队共用的开发分支,所有新功能开发、bug修复均基于该分支创建子分支,开发完成后合并回develop分支。

  • feature 分支:功能分支,用于开发单个新功能(如feature/user-login、feature/pay),基于develop分支创建,开发完成后合并回develop分支,合并后可删除该分支。

  • hotfix 分支:紧急修复分支,用于修复线上正式版本的bug(如hotfix/login-error),基于master/main分支创建,修复完成后同时合并到master/main和develop分支,合并后可删除该分支。

  • release 分支:发布分支,用于版本发布前的测试、优化(如release/v1.0.0),基于develop分支创建,测试完成后合并到master/main和develop分支,合并后可删除该分支。

3.1.2 分支命名规范

  • feature分支:feature/功能描述(小写,用连字符连接),如feature/user-register、feature/order-list。

  • hotfix分支:hotfix/bug描述,如hotfix/fix-login-fail、hotfix/fix-payment-error。

  • release分支:release/版本号,如release/v1.0.0、release/v1.1.0。

3.2 分支基础操作

# 1. 查看本地分支
git branch  # 列出所有本地分支,当前所在分支前会有“*”标记
git branch -v  # 查看本地分支的最新提交记录(简洁版)
git branch -vv # 查看本地分支及其关联的远程分支(团队协作常用)

# 2. 查看所有分支(本地+远程)
git branch -a  # 远程分支会以“remotes/origin/分支名”显示

# 3. 创建本地分支(基于当前所在分支创建)
git branch 新分支名  # 如:git branch feature/user-login(仅创建,不切换)

# 4. 创建并切换到新分支(最常用,一步完成)
git checkout -b 新分支名  # 简化命令:git checkout -b feature/user-login(基于当前分支)
# 2.23+ 推荐使用语义化命令 git switch -c:
git switch -c 新分支名  # 等价于 git checkout -b 新分支名
# 基于指定分支创建新分支(推荐,明确分支来源)
git checkout -b 新分支名 基准分支名  # 如:git checkout -b feature/user-login develop(基于develop创建)
git switch -c 新分支名 基准分支名     # 等价写法

# 5. 切换本地分支(切换到已存在的本地分支)
git checkout 分支名  # 简化命令:git co 分支名(如:git co develop)
git switch 分支名    # 2.23+ 推荐写法,语义更清晰
git switch -        # 切回上一个分支(如从 develop 切到 feature 后又切回 develop)
# 注意:切换分支前,需确保当前分支的修改已提交或暂存,否则会提示冲突
# switch 拒绝切换到不存在的分支(更安全),checkout 会自动创建;如需自动创建用 git switch -c

# 6. 删除本地分支(分支已合并到其他分支,可安全删除)
git branch -d 分支名  # 如:git branch -d feature/user-login
# 强制删除本地分支(分支未合并,需强制删除,谨慎使用)
git branch -D 分支名  # 如:git branch -D feature/old-feature(会丢失分支上的修改)

# 7. 重命名本地分支(当前未切换到该分支)
git branch -m 旧分支名 新分支名  # 如:git branch -m feature/old feature/new
# 重命名当前所在分支
git branch -m 新分支名  # 如:当前在feature/old分支,执行git branch -m feature/new

3.3 分支合并操作

分支开发完成后,需将其合并到目标分支(如feature分支合并到develop分支),合并分为两种方式:merge(普通合并,保留分支历史)和rebase(变基合并,整理分支历史,更简洁)。

3.3.1 普通合并

merge,推荐新手、团队共用分支

# 场景:将feature/user-login分支合并到develop分支
# 1. 先切换到目标分支(develop)
git checkout develop  # 或 git co develop

# 2. 拉取目标分支最新代码(避免合并时出现冲突,团队协作必做)
git pull origin develop

# 3. 合并源分支(feature/user-login)到当前分支(develop)
git merge feature/user-login

# 4. 合并后,推送目标分支到远程仓库(同步到远程)
git push origin develop

# 5. 合并完成后,删除源分支(feature/user-login,可选)
git branch -d feature/user-login

# 合并冲突处理(重点!)
# 当合并时,Git提示“Automatic merge failed; fix conflicts and then commit the result”,说明出现冲突
# 冲突原因:两个分支修改了同一个文件的同一行内容,Git无法自动判断保留哪一个
# 冲突解决步骤:
# 1. 打开提示冲突的文件,文件中会有冲突标记:
#    <<<<<<< HEAD(当前分支的内容)
#    冲突内容1
#    =======
#    冲突内容2
#    >>>>>>> feature/user-login(源分支的内容)
# 2. 编辑文件,删除冲突标记(<<<<<<<、=======、>>>>>>>),修改冲突内容为最终需要的内容
# 3. 保存文件后,执行git add 冲突文件名(暂存冲突文件)
# 4. 执行git commit -m "merge: 合并feature/user-login分支,解决冲突"(提交合并结果)
# 5. 推送目标分支到远程(git push origin develop)

# 合并模式与策略参数(重要,控制合并提交的生成与冲突解决方向):
# --no-ff:禁止快进合并,强制生成 merge 提交,保留分支拓扑(团队共用分支推荐,可追溯特性分支来源)
git merge --no-ff feature/user-login
# --ff-only:仅允许快进合并,若目标分支有新提交(非快进)则合并失败,保护目标分支历史线性
git merge --ff-only feature/user-login
# --ff:默认行为,能快进则快进,不能则生成 merge 提交
# --squash:将源分支所有提交压缩为一个暂存修改,不生成 merge 提交,需手动 commit
git merge --squash feature/user-login && git commit -m "feat: 合并用户登录特性"

# 递归策略的冲突解决倾向(-X):
git merge -X ours feature/user-login     # 冲突时优先保留当前分支内容(仍生成 merge 提交,注意与 -s ours 策略不同)
git merge -X theirs feature/user-login   # 冲突时优先保留源分支内容
# -X ours/theirs 仅影响冲突块的选择,非冲突部分正常合并;-s ours 策略则完全丢弃源分支所有修改

# 自动生成冲突解决(自动化场景,需人工复核):
git merge -X renormalize feature/user-login  # 重新规范化行尾符后再合并
# 大型重构合并可考虑 strategy-option:
# -X patience:使用 patience diff 算法,冲突块更易理解
# -X ignore-all-space / -X ignore-space-change:忽略空白差异
git merge -X patience feature/user-login

3.3.2 变基合并

rebase,推荐个人开发分支、追求简洁历史

# 场景:将feature/user-login分支的修改,变基到develop分支(整理历史,无merge记录)
# 1. 切换到源分支(feature/user-login)
git checkout feature/user-login

# 2. 拉取源分支最新代码(确保本地分支是最新的)
git pull origin feature/user-login

# 3. 执行变基操作(基于develop分支,整理当前分支的提交)
git rebase develop

# 4. 变基过程中出现冲突,处理方式:
# 1. Git提示冲突,打开冲突文件,按照merge冲突的方式修改(删除冲突标记,修改内容)
# 2. 保存文件后,执行git add 冲突文件名(暂存冲突文件)
# 3. 执行git rebase --continue(继续变基,直到所有冲突处理完成)
# 4. 若需放弃变基,执行git rebase --abort(回到变基前的状态)

# 5. 变基完成后,切换到目标分支(develop)
git checkout develop

# 6. 合并源分支到目标分支(此时合并会是“快进合并”,无merge记录,历史简洁)
git merge feature/user-login

# 7. 推送目标分支到远程仓库
git push origin develop

# 8. 推送源分支到远程仓库(变基后,本地分支与远程分支不一致,需强制推送,谨慎!)
# 注意:仅个人开发的feature分支可执行强制推送,团队共用分支严禁使用
git push -f origin feature/user-login

# 9. 合并完成后,删除源分支(可选)
git branch -d feature/user-login

# 变基与merge的区别(重点):
# - merge:保留分支历史,会生成一个新的merge提交记录,适合团队共用分支(如develop、master)
# - rebase:整理分支历史,将当前分支的提交"移动"到目标分支的最新提交之后,无merge记录,适合个人开发分支
# - 禁忌:已推送远程、且被其他团队成员使用的分支,严禁使用rebase命令(会导致团队成员代码冲突)

# 交互式变基 git rebase -i(整理提交历史的高频工具):
# 语法:git rebase -i <基准>(基准可以是分支名、提交ID、HEAD~n)
git rebase -i HEAD~3   # 整理最近 3 次提交,打开编辑器列出待整理的提交列表
# 每行格式:<action> <提交哈希前7位> <提交说明>
# 第一列 action 决定对该提交的处理方式:
# - pick(简写 p):保留该提交,原样应用
# - reword(简写 r):保留提交,但修改提交说明(弹出编辑器编辑 message)
# - edit(简写 e):保留提交,但暂停变基,便于修改该提交的代码内容(如拆分提交、修改文件)
# - squash(简写 s):将该提交合并到前一个提交,并合并提交说明(弹出编辑器拼接 message)
# - fixup(简写 f):将该提交合并到前一个提交,但丢弃该提交的说明(保留前一个说明)
# - drop(简写 d):删除该提交
# - exec(简写 x):执行一条 shell 命令(如 x npm test,验证该提交通过测试)
# - break(简写 b):在此处暂停变基,便于手动处理后再 git rebase --continue
# - label / reset / merge:高级分支拓扑操作,少用
# 整理流程:编辑列表 → 保存退出 → 按列表逐个处理 → 全部完成变基完成
# 场景:
# 1. 合并脏提交:将多次零散提交 squash/fixup 到主提交,保持历史简洁
# 2. 修改历史提交:用 edit 暂停后修改文件,git add → git rebase --continue
# 3. 删除无用提交:用 drop 直接剔除(注意依赖关系,避免编译失败)
# 4. 调整提交顺序:直接调整 pick 行的顺序

# 注意:rebase -i 会重写提交哈希,已推送远程的分支整理后需强制推送(git push -f),仅个人分支可使用

3.4 分支管理进阶技巧

# 1. 暂存本地修改(stash,切换分支时常用)
# 场景:当前分支有未提交的修改,需切换到其他分支,又不想提交当前修改
git stash  # 暂存当前所有未提交的修改(工作区+暂存区),默认不含未跟踪文件
git stash push -m "暂存说明"  # 带说明的暂存(Git 2.13+ 推荐写法,等价于旧版 git stash save)
# 进阶选项:
git stash -u              # 同时暂存未跟踪文件(untracked),适合需要切分支又怕丢新文件的场景
git stash -a              # 暂存所有变更,包括 .gitignore 忽略的文件(慎用)
git stash --keep-index    # 仅暂存未暂存的修改,保留暂存区内容(用于分阶段提交)
git stash -p              # 交互式选择代码块暂存(类似 git add -p)
git stash --include-untracked --message "说明"  # 组合用法
# 仅暂存部分文件:git stash push <文件路径>  或 git stash push -m "说明" <文件1> <文件2>
git stash push -m "仅暂存 README" README.md

# 2. 查看所有stash暂存记录
git stash list  # 显示所有暂存,格式:stash@{0}: On 分支名: 暂存说明
git stash show -p stash@{n}  # 查看指定暂存的内容差异(详细 diff)
git stash show stash@{n}    # 查看指定暂存的文件统计

# 3. 恢复stash暂存的修改(两种方式)
git stash apply  # 恢复最近一次暂存的修改(stash@{0}),暂存记录保留(可多次恢复)
git stash apply stash@{n}  # 恢复指定的暂存记录(n为暂存索引,如:git stash apply stash@{1})
git stash apply --index  # 同时恢复暂存区状态(默认只恢复工作区)
git stash pop  # 恢复最近一次暂存的修改,同时删除该暂存记录(推荐,避免暂存记录堆积)
git stash pop stash@{n}  # 恢复并删除指定暂存
# stash apply/pop 冲突处理:
# 若恢复时与当前工作区冲突,Git 会标记冲突(与 merge 冲突标记一致),需先解决冲突:
# 1. 打开冲突文件,按 merge 冲突规则处理(删除 <<<<<<< ======= >>>>>>> 标记,合并内容)
# 2. git add 冲突文件
# 3. git commit(pop 时)或 git stash drop stash@{0}(apply 时手动清除记录)
# 若 apply 触发冲突,原 stash 记录不会被删除,需手动 drop

# 4. 删除stash暂存记录
git stash drop  # 删除最近一次暂存记录(stash@{0})
git stash drop stash@{n}  # 删除指定的暂存记录
git stash clear  # 删除所有暂存记录(谨慎使用)

# 5.  cherry-pick(挑选单个/多个提交,合并到当前分支)
# 场景:其他分支的某个提交,需要合并到当前分支,无需合并整个分支
# 1. 查看目标提交的ID(通过git log --oneline 查看,取前7位)
# 2. 切换到当前分支(如develop)
git checkout develop
# 3. 挑选提交合并到当前分支
git cherry-pick 提交ID  # 如:git cherry-pick a1b2c3d(单个提交)
git cherry-pick 提交ID1 提交ID2  # 挑选多个提交(按顺序列举)
# 区间挑选(从分支或提交区间批量复制):
git cherry-pick 提交ID1..提交ID2     # 左开右闭区间(含提交ID2,不含提交ID1)
git cherry-pick 提交ID1^..提交ID2    # 闭区间(含提交ID1与提交ID2)
git cherry-pick 分支A..分支B         # 复制 分支A 之后到 分支B 的所有提交
# -n / --no-commit:仅将提交内容应用到工作区与暂存区,不生成提交,便于后续合并修改
git cherry-pick -n 提交ID
# --strategy-option/-X:复用 merge 策略参数,如 -X theirs 自动解决冲突时偏向源提交
git cherry-pick -X theirs 提交ID
# 4. 若出现冲突,处理方式与merge、rebase一致:修改冲突 → git add → git cherry-pick --continue
# 5. 放弃cherry-pick:git cherry-pick --abort
# 6. 跳过当前提交继续下一个:git cherry-pick --skip(区间挑选时某个提交冲突暂不处理)
# 7. 编辑提交说明:git cherry-pick --edit 提交ID(强制弹出编辑器修改说明)

# 注意:cherry-pick 会生成新的提交记录,与原提交记录ID不同,适合跨分支复用单个提交

3.5 分支策略对比与选型

分支命名规范解决"叫什么",分支策略解决"如何流转、何时合并"。常见四种工作流对比如下:

3.5.1 Git Flow(经典重型)

Vincent Driessen 于 2010 年提出,五类分支协作,结构清晰但流程较重:

  • master:正式发布版本,每个提交对应一个 tag。
  • develop:日常集成分支,特性分支合并至此。
  • feature/*:基于 develop 拆分,开发完合并回 develop。
  • release/*:基于 develop 拆分,预发布测试与修正,完成后合并至 master 与 develop。
  • hotfix/*:基于 master 拆分,紧急修复,完成后合并至 master 与 develop。

适用场景:发布周期长、需多版本并行维护的产品(如桌面软件、企业级应用)。配合 git flow 扩展命令可简化操作。缺点:分支多、合并点多、新人上手成本高。

3.5.2 GitHub Flow(轻量)

GitHub 提出,仅 master 与 feature 两类分支:

  • master 始终可部署,通过 PR 合并,PR 须通过 CI 与人工评审。
  • feature/* 直接基于 master 拆分,合并后立即部署。

适用场景:Web 产品、SaaS、CI/CD 完善且希望快速迭代的团队。优点:流程极简,部署频率高。缺点:缺少 release 分支,难以同时维护多个线上版本。

3.5.3 GitLab Flow(环境隔离)

在 GitHub Flow 基础上增加环境分支:

  • master 仍为集成分支,feature/* 经 PR 合并至 master。
  • 通过环境分支串联部署:master → pre-production → production,每级通过 PR 推进。
  • 可选 release/* 分支用于版本回溯。

适用场景:多环境部署(开发/预发布/生产)、需追踪环境状态的服务端项目。优点:环境与分支对应,部署可追溯。缺点:环境分支过多时同步成本上升。

3.5.4 Trunk-Based Development(主干开发)

Google、Facebook 等大型团队采用,所有人直接向 master 提交:

  • 短期 feature 分支(通常 < 24 小时),合并回 master 后立即删除。
  • 未完成特性通过 Feature Flag(功能开关)控制可见性,避免长期分支。
  • master 始终可发布,依赖完善的 CI 与自动化测试。
  • 发布时基于 master 拉取 release 分支或直接打 tag。

适用场景:高部署频率(一日多次)、强 CI/CD、高测试覆盖率的成熟工程团队。优点:反馈快、合并冲突少。缺点:对工程能力要求高,无强测试保障时风险大。

3.5.5 选型建议

按团队规模与发布节奏粗略参考:

  • 个人 / 小团队、Web 项目:GitHub Flow。
  • 中型团队、多环境部署:GitLab Flow。
  • 重型产品、长周期发布、需多版本并行:Git Flow。
  • 大型团队、强 CI/CD、追求高频部署:Trunk-Based。
  • 起步阶段或不确定:从 GitHub Flow 起步,按需演进至 GitLab Flow。

选定后应配套分支命名规范、PR/MR 模板、CI 流水线与合并权限策略,形成可落地的协作约定,避免策略与执行脱节。

第四章 Git 标签管理

版本发布必备

标签(Tag)用于标记版本号(如v1.0.0、v1.1.0),对应项目的正式发布版本,便于后续回溯版本、发布迭代,标签一旦创建,通常不建议修改或删除。

4.1 标签核心概念

  • 轻量标签(Lightweight Tag):仅标记一个提交ID,无额外信息,适合临时标记。

  • 附注标签(Annotated Tag):包含标签名、标签作者、标签时间、标签说明等信息,适合正式版本发布(推荐)。

4.2 标签基础操作

# 1. 查看所有标签
git tag  # 列出所有本地标签(按字母顺序排列)
git tag -l "v1.*"  # 筛选标签(如:查看所有v1.x版本的标签)

# 2. 查看标签详细信息(仅附注标签有详细信息)
git show 标签名  # 如:git show v1.0.0

# 3. 创建轻量标签(简单标记,无说明)
git tag 标签名  # 如:git tag v1.0.0(默认标记当前所在分支的最新提交)
git tag 标签名 提交ID  # 标记指定提交(如:git tag v1.0.0 a1b2c3d)

# 4. 创建附注标签(正式版本发布,推荐)
git tag -a 标签名 -m "标签说明"  # 如:git tag -a v1.0.0 -m "第一个正式发布版本,包含用户登录、首页展示功能"
git tag -a 标签名 提交ID -m "标签说明"  # 标记指定提交(如:git tag -a v1.0.0 a1b2c3d -m "正式发布版本")

# 5. 删除本地标签
git tag -d 标签名  # 如:git tag -d v1.0.0

# 6. 推送标签到远程仓库(标签不会随git push自动推送,需手动推送)
git push origin 标签名  # 推送指定标签(如:git push origin v1.0.0)
git push origin --tags  # 推送所有本地标签(推荐,版本发布时使用)

# 7. 从远程仓库拉取标签(本地无对应标签时)
git fetch origin --tags  # 拉取所有远程标签到本地

# 8. 从远程仓库删除标签(需有远程仓库操作权限)
git push origin --delete tag 标签名  # 如:git push origin --delete tag v1.0.0

# 9. 基于标签创建分支(回溯版本,修复旧版本bug)
# 场景:v1.0.0版本已发布,发现bug,需基于该版本创建分支修复
git checkout -b hotfix/v1.0.1 v1.0.0  # 基于v1.0.0标签,创建hotfix/v1.0.1分支

第五章 Git 问题排查与常见坑点

日常使用Git时,难免会遇到各种问题(如冲突、提交错误、分支混乱等),本章整理高频问题及解决方案,帮助快速排查,避免踩坑。

5.1 高频问题及解决方案

问题1:拉取/推送代码时,提示“fatal: Authentication failed for 'https://xxx.git/'”(认证失败)

# 原因:HTTPS地址连接,账号密码输入错误,或密码已修改
# 解决方案:
# 方法1:重新输入账号密码(Windows会弹出密码框,Mac/Linux在终端输入)
# 方法2:清除本地保存的账号密码,重新输入
# Windows:控制面板 → 凭据管理器 → 找到对应远程仓库的凭据,删除后重新拉取/推送
# Mac:终端执行命令:git config --global --unset credential.helper(清除凭据缓存)
# 方法3:切换为SSH地址连接(推荐,一劳永逸,配置SSH密钥后无需输密码)

问题2:合并/变基时,出现冲突,无法继续操作

# 解决方案(通用):
1. 执行git status,查看冲突的文件;
2. 打开冲突文件,删除冲突标记(<<<<<<<、=======、>>>>>>>),修改冲突内容为最终需要的版本;
3. 执行git add 冲突文件名(暂存冲突文件);
4. 若为merge冲突:执行git commit -m "merge: 解决冲突";
   若为rebase冲突:执行git rebase --continue;
5. 若需放弃操作:merge冲突直接执行git merge --abort;rebase冲突执行git rebase --abort。

# 注意:冲突处理后,务必检查代码是否正常运行,避免误删有效代码

问题3:误提交代码到错误分支(如误提交到master分支,需转移到feature分支)

# 解决方案(未推送远程前):
1. 切换到目标分支(feature分支),确保该分支是最新的;
git checkout feature/user-login
git pull origin feature/user-login

2. 切换回错误分支(master),暂存未提交的修改(若有);
git checkout master
git stash(若有未提交修改)

3. 撤销错误分支的提交(保留修改,回到暂存区);
git reset --soft HEAD~1(撤销上次提交,若误提交多次,改为HEAD~n,n为提交次数)

4. 切换到目标分支,合并暂存的修改;
git checkout feature/user-login
git stash pop(恢复暂存的修改,若无暂存,直接执行下一步)
git add .
git commit -m "feat: 新增xxx功能"(重新提交)

5. 推送目标分支到远程,错误分支(master)若有推送,需强制推送撤销(谨慎!);
git push origin feature/user-login
git checkout master
git push -f origin master(仅自己使用的master分支可执行,团队共用分支严禁使用)

问题4:误删除本地分支,如何恢复

# 解决方案:通过git reflog 查找分支的最后一次提交ID,基于该ID重建分支
1. 查看本地所有操作记录(包含删除的分支提交);
git reflog  # 找到删除分支的最后一次提交ID(如:a1b2c3d HEAD@{0}: commit: feat: 新增xxx功能)

2. 基于该提交ID,重建本地分支;
git checkout -b 被删除的分支名 提交ID  # 如:git checkout -b feature/user-login a1b2c3d

3. 验证分支是否恢复,若需同步到远程,推送分支;
git push origin 被删除的分支名

问题5:本地代码被误删,如何恢复(未提交到版本库)

# 解决方案:利用Git的工作区恢复功能,仅适用于已被Git跟踪的文件(未跟踪文件无法恢复)
git checkout -- 被删除的文件名  # 如:git checkout -- src/main.java
git checkout -- .  # 恢复所有被删除的跟踪文件

# 注意:未被Git跟踪的文件(新创建,未执行git add),删除后无法通过Git恢复,需借助第三方工具

问题6:推送被拒,提示 "! [rejected] master -> master (non-fast-forward)" 或 "Updates were rejected"

# 原因:远程分支已有新提交,本地分支落后,直接推送会被覆盖
# 解决方案:先拉取远程最新代码,合并/变基后再推送

# 方法1:rebase(推荐,保持线性历史)
git pull --rebase origin master
# 出现冲突按 rebase 冲突处理:解决 → git add → git rebase --continue
git push origin master

# 方法2:merge(保留合并提交)
git pull origin master
# 出现冲突按 merge 冲突处理:解决 → git add → git commit
git push origin master

# 方法3:放弃本地提交,强制与远程对齐(仅个人分支)
git fetch origin
git reset --hard origin/master   # 本地修改全部丢失,谨慎

问题7:rebase 后丢失提交,分支历史似乎被改写

# 原因:rebase 会创建新提交,旧提交哈希变化,看似"丢失",实际仍可通过 reflog 找回
# 解决方案:通过 reflog 定位 rebase 前的 HEAD 位置

# 1. 查看 reflog,找到 rebase 操作前的 HEAD
git reflog
# 输出示例:
# a1b2c3d HEAD@{0}: rebase (finish)
# b2c3d4e HEAD@{1}: rebase (start)
# c3d4e5f HEAD@{2}: commit: feat: 上次正常提交  ← rebase 前的位置

# 2. 创建临时分支保留旧提交(避免 reset 误操作)
git switch -c recover-branch c3d4e5f

# 3. 或直接 reset 回 rebase 前状态
git reset --hard c3d4e5f

# 4. 若已强制推送,且远程分支被覆盖,团队成员需:
git fetch origin
git reset --hard origin/<分支名>  # 同步新历史
# 旧提交仍可在 reflog 中找到,直到过期清理

问题8:submodule 拉取后处于 detached HEAD 状态,无法提交

# 原因:submodule 默认按主仓库记录的提交 ID 检出,处于分离 HEAD 状态
# 解决方案:在子模块内切换到对应分支再开发

# 1. 进入子模块目录
cd third-party/lib

# 2. 切换到子模块的开发分支
git switch master      # 或子模块约定分支
# 若不知道分支名,可先查看:git branch -a

# 3. 正常开发并提交到子模块远程
git add . && git commit -m "feat: 修改子模块" && git push origin master

# 4. 回主仓库,记录子模块新提交 ID
cd 回主仓库根目录
git add third-party/lib
git commit -m "chore: 升级 lib 子模块"

# 预防:配置子模块默认检出指定分支
git config -f .gitmodules submodule.third-party/lib.branch master
git submodule sync
git submodule update --remote --merge

问题9:误入 detached HEAD 状态(HEAD 不在任何分支上)

# 现象:git status 提示 "HEAD detached at xxx",提交后不属于任何分支,切换分支后丢失
# 原因:直接 checkout 提交 ID 或 tag,或 rebase/cherry-pick 中途退出

# 解决方案1:将当前提交创建为新分支(推荐,保留改动)
git switch -b new-branch-name    # 当前提交成为新分支起点

# 解决方案2:合并回原分支
git switch master
git merge new-branch-name         # 或 cherry-pick 提交 ID

# 解决方案3:仅查看历史版本,不提交(仅作只读探索)
git switch master                 # 直接切回,不保留 detached 状态下的修改

# 预防:使用 git switch --detach 显式进入 detached 状态(语义清晰)
# 提交后立即 git switch -c <分支名> 保存

问题10:误提交大文件导致 .git 目录膨胀,clone 缓慢

# 原因:大文件已进入历史,git rm 仅删除当前版本,历史对象仍在
# 解决方案:用 git filter-repo 改写历史,移除大文件(详见 6.13)

# 1. 备份当前仓库(避免改写失败造成损失)
cp -r project project.bak

# 2. 安装 git-filter-repo 并执行改写
pip install git-filter-repo
git filter-repo --path target/big-file.zip --invert-paths

# 3. 重新设置远程并强制推送(团队需重新克隆)
git remote add origin <远程地址>
git push --force --all
git push --force --tags

# 4. 通知所有团队成员重新克隆,避免历史错位

# 预防:对大文件配置 .gitattributes 走 LFS(详见 6.12),或加入 .gitignore

5.2 常见坑点(严禁操作)

  • 严禁在master/main分支直接开发、提交代码:master分支是正式上线分支,仅通过合并其他分支更新,直接修改会导致线上版本混乱。

  • 严禁对已推送远程、且被其他团队成员使用的分支执行git reset -f、git rebase命令:会导致分支历史错乱,团队成员代码冲突、丢失。

  • 严禁随意执行git push -f(强制推送):仅个人开发、未被他人使用的分支可使用,团队共用分支(develop、master)严禁使用。

  • 提交说明请勿随意填写:简洁明了,遵循规范,便于后续回溯提交记录、排查问题。

  • 请勿忽略.gitignore文件:避免将编译产物(如target、node_modules)、日志文件、配置文件(如数据库密码)提交到远程仓库。

第六章 Git 高级技巧与优化

6.1 .gitignore 文件配置

.gitignore 文件用于指定Git忽略的文件/目录,避免无用文件(如编译产物、日志、IDE配置文件)被提交到版本库,每个项目根目录下均可创建该文件。

# 示例:Java项目的.gitignore文件内容(可直接复制使用)
# IDE配置文件
.idea/
.vscode/
*.iml
*.ipr
*.iws

# 编译产物
target/
classes/
build/

# 日志文件
*.log
logs/

# 配置文件(包含敏感信息,如数据库密码)
application-dev.yml
application-prod.yml

# 依赖包
node_modules/
vendor/

# 临时文件
*.tmp
*.swp
.DS_Store(Mac系统临时文件)

# 说明:
# 1. 每行表示一个忽略规则,支持通配符(*表示任意字符,/表示目录);
# 2. # 开头表示注释,不生效;
# 3. ! 开头表示反向忽略(即不忽略该文件/目录),如:!application.yml(不忽略application.yml);
# 4. 若已将忽略的文件提交到版本库,需先删除远程的该文件,再配置.gitignore,否则忽略无效:
#    git rm --cached 文件名(删除远程的文件,本地保留)
#    git commit -m "docs: 删除被忽略的文件"
#    git push origin 分支名

6.1.1 .gitkeep 与空目录处理

Git 基于文件内容寻址,仅跟踪文件,不跟踪空目录。空目录在 add 与 commit 时会被自动忽略,导致目录结构无法提交,影响模板、占位、构建产物目录等的版本管理。约定俗成的方案是放入一个名为 .gitkeep(或 .keep)的占位空文件,使目录非空从而被跟踪:

# 1. 在空目录中创建 .gitkeep 占位文件
mkdir -p src/main/resources/templates
touch src/main/resources/templates/.gitkeep
git add src/main/resources/templates/.gitkeep
git commit -m "chore: 新增 templates 目录占位"

# 2. 文件名无强制约定,可用 .gitkeep、.keep、.gitignore(同名时直接作为忽略规则文件)等
# 推荐使用 .gitkeep,社区默认习惯,可读性最佳

# 3. .gitkeep 文件内容可空,也可写入说明(如该目录用途)
# 4. .gitkeep 本身需被跟踪,不可加入 .gitignore 规则

6.2 Git 命令别名配置

1.2.3 已列出基础别名(st/co/br/ci/logg),本节补充团队协作常用别名。建议按需启用,避免别名过多反而影响他人阅读脚本。

# 常用别名配置(全局生效)
git config --global alias.st status  # git st → git status
git config --global alias.co checkout  # git co → git checkout
git config --global alias.br branch  # git br → git branch
git config --global alias.ci commit  # git ci → git commit
git config --global alias.logg "log --graph --pretty=oneline --abbrev-commit"  # 简洁图形化日志
git config --global alias.mer "merge --no-ff"  # 禁止快进合并,保留merge记录
git config --global alias.rb "rebase"  # git rb → git rebase
git config --global alias.cp "cherry-pick"  # git cp → git cherry-pick
git config --global alias.stashl "stash list"  # git stashl → git stash list

# 查看所有别名配置
git config --global --get-regexp alias

# 删除别名
git config --global --unset alias.别名  # 如:git config --global --unset alias.st

6.3 Git 缓存优化

# 1. 配置Git缓存大小(适用于大型项目,避免缓存不足)
git config --global core.deltaBaseCacheLimit 2g  # 缓存大小设置为2G(可根据电脑配置调整)

# 2. 开启Git文件系统缓存(提升文件状态查询速度)
git config --global core.fscache true

# 3. 压缩Git对象(减少本地仓库占用空间)
git gc  # 手动执行垃圾回收,压缩对象(大型项目定期执行)

6.4 其他高级技巧

# 1. 查看两个分支的差异(对比两个分支的所有修改)
git diff 分支1 分支2  # 如:git diff develop feature/user-login
git diff 分支1 分支2 -- 文件名  # 对比两个分支中指定文件的差异

# 2. 批量修改提交记录(如修改作者信息、提交说明)
# 注意:仅本地未推送的提交可修改,已推送的提交严禁修改
git rebase -i HEAD~n  # n为需要修改的提交数量(如HEAD~3,修改最近3次提交)
# 执行后,会打开文本编辑器,将需要修改的提交前的pick改为edit,保存退出
# 然后执行git commit --amend(修改提交信息/作者),修改完成后执行git rebase --continue,重复直到所有提交修改完成

# 3. 导出指定版本的代码(无需克隆整个仓库)
git archive --format=zip --output=v1.0.0.zip v1.0.0  # 导出v1.0.0标签对应的代码,保存为v1.0.0.zip

# 4. 查看文件的修改历史(每一行的修改记录)
git blame 文件名  # 如:git blame README.md(显示每一行的最后修改人、提交ID、修改时间)
git blame -L 10,30 文件名  # 仅查看 10-30 行的修改记录
git blame -w 文件名  # 忽略空白差异,更准确归因

6.5 .gitattributes 文件配置

.gitattributes 用于为路径指定属性,覆盖行尾符、二进制识别、diff/merge 行为、导出忽略等。跨平台协作与大型项目必备,与 .gitignore 互为补充。

# 1. 行尾符自动转换(跨平台必备,Windows 与 Linux/Mac 协作)
* text=auto                  # 所有文本文件自动转换:提交时统一为 LF,检出时按系统转换(Windows 转 CRLF)
* text=auto eol=lf           # 强制检出为 LF(不转 CRLF,适合 Linux 项目)
* text=auto eol=crlf         # 强制检出为 CRLF(Windows 项目)
*.sh text eol=lf             # 脚本必须为 LF,避免 Windows 拉取后无法执行
*.bat text eol=crlf          # Windows 批处理必须为 CRLF
*.ps1 text eol=lf            # PowerShell 推荐 LF

# 2. 标记二进制文件,避免误判与误合并
*.png binary
*.jpg binary
*.pdf binary
*.zip binary
*.jar binary

# 3. 自定义 diff/merge 工具
*.docx diff=pandoc           # 用 pandoc 比较 docx 内容
*.lock merge=ours            # 锁文件冲突时优先保留当前分支

# 4. 导出忽略(git archive 时排除,仅影响归档输出,不影响版本库)
export-ignore                # 该文件不出现在 archive 输出中
*.secrets export-ignore      # 敏感配置导出时排除

# 5. 指定语言统计(GitHub Linguist 用,避免误识别语言)
*.h linguist-language=cpp    # 将 .h 文件计为 C++ 而非 C
docs/* linguist-documentation # 将 docs 目录排除在语言统计外
vendor/* linguist-vendored   # 第三方依赖不计入语言占比

6.6 Git Hooks 钩子

Git Hooks 是在特定事件触发时自动执行的脚本,存放于 .git/hooks 目录,默认为 .sample 后缀示例,去掉后缀即生效。本地钩子不随仓库共享,团队级强制需配合服务端钩子(GitHub/GitLab Webhooks 或自建 Git 服务器)。

常见客户端钩子:

# 1. pre-commit:提交前触发,常用于代码检查、格式化、敏感信息扫描
# 文件路径:.git/hooks/pre-commit(可执行权限:chmod +x .git/hooks/pre-commit)
#!/bin/sh
# 示例:阻止包含 console.log 的提交
if git diff --cached | grep -q "console.log"; then
  echo "禁止提交 console.log,请清理后再提交"
  exit 1
fi
exit 0

# 2. commit-msg:提交说明校验,常用于 Conventional Commits 规范
# 接收参数:$1 为 .git/COMMIT_EDITMSG 路径
#!/bin/sh
# 示例:强制提交说明以 feat/fix/docs 等开头
msg=$(cat "$1")
if ! echo "$msg" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+"; then
  echo "提交说明须符合 Conventional Commits,如 feat: 新增登录功能"
  exit 1
fi

# 3. pre-push:推送前触发,常用于运行测试或阻止推送受保护分支
# 接收参数:$1 远程名 $2 远程URL,stdin 为 待推送引用列表
#!/bin/sh
while read local_ref local_sha remote_ref remote_sha; do
  if [[ "$remote_ref" == "refs/heads/master" ]]; then
    echo "禁止直接推送 master 分支,请走 PR 流程"
    exit 1
  fi
done

# 4. post-merge:merge 后触发,常用于更新依赖或重启服务
# 5. pre-rebase:rebase 前触发,可拦截危险 rebase

团队共享钩子推荐使用 husky(Node 项目)、pre-commit 框架(多语言)等工具,将钩子脚本纳入版本库,成员克隆后统一初始化,避免本地钩子不一致。

6.7 GPG 签名提交

GPG 签名让提交与标签可验证身份,防止冒充。GitHub/Gitee/GitLab 在签名通过时显示 "Verified" 标记,适合开源项目与供应链安全场景。

# 1. 安装 GPG(Windows 随 Git for Windows 自带;Mac:brew install gnupg;Linux:apt/yum install gnupg)
gpg --version  # 验证安装

# 2. 生成 GPG 密钥(建议 ed25519,更快更安全)
gpg --quick-generate-key "你的名字 <你的邮箱>" ed25519 sign 0
# 或交互式生成:gpg --full-generate-key,选择 ECC (sign and encrypt) → Curve 25519

# 3. 查看密钥并复制密钥 ID
gpg --list-secret-keys --keyid-format=long
# 输出示例:sec   ed25519/3AA41C2B2C3D4E5F 2026-01-01 [SC]
# 密钥 ID 为 3AA41C2B2C3D4E5F(/ 后部分)

# 4. 导出公钥并上传到 GitHub/Gitee
gpg --armor --export 3AA41C2B2C3D4E5F  # 输出公钥文本,复制到托管平台 "GPG keys" 设置

# 5. 配置 Git 使用该密钥签名
git config --global user.signingkey 3AA41C2B2C3D4E5F
git config --global commit.gpgsign true       # 默认所有提交签名(可省 -S)
git config --global gpg.program gpg           # 指定 gpg 可执行路径(多版本时)

# 6. 签名提交与标签
git commit -S -m "feat: 重要改动"             # 单次签名提交(未开启默认签名时)
git tag -s v1.0.0 -m "正式发布"               # 创建签名附注标签

# 7. 验证签名
git log --show-signature -1                   # 查看最近一次提交的签名验证结果
git tag -v v1.0.0                             # 验证标签签名

# 8. 排错
# 报错 "gpg: signing failed: Inappropriate ioctl for device":
#   export GPG_TTY=$(tty)  (写入 ~/.bashrc 持久生效)
# 报错 "secret key not available":
#   检查 gpg --list-secret-keys,确认密钥存在且未过期

6.8 git bisect 二分查找

bisect 用于在大量提交中定位引入 bug 的具体提交,原理是二分搜索:标记一个好版本(good)与坏版本(bad),Git 自动 checkout 中间提交测试,根据测试结果缩小范围,直至定位首个坏提交。

# 1. 启动 bisect
git bisect start

# 2. 标记坏提交(当前 HEAD 即包含 bug 的版本)与好提交(已知正常工作的版本)
git bisect bad                   # 标记当前 HEAD 为坏
git bisect good v1.0.0           # 标记 v1.0.0 标签为好(或提交 ID、分支名)

# 3. Git 自动 checkout 中间提交,运行测试,根据结果继续标记
mvn test                         # 或 npm test、pytest 等
git bisect good                  # 若测试通过,标记当前为好(继续往后找)
git bisect bad                   # 若测试失败,标记当前为坏(往前找)
# 重复直至输出 "xxx is the first bad commit"

# 4. 自动化 bisect(推荐,用脚本自动判定,免手动操作)
git bisect start HEAD v1.0.0 -- -- mvn test
# 参数:HEAD 为坏,v1.0.0 为好,-- 后为判定命令(命令返回 0 视为 good,非 0 视为 bad)

# 5. 查看 bisect 进度与剩余范围
git bisect log                   # 输出已标记记录,可保存用于恢复

# 6. 结束 bisect,回到原分支
git bisect reset

# 7. 跳过无法编译或无法测试的提交
git bisect skip                  # 跳过当前提交

# 注意:
# - bisect 依赖可重现的测试,CI 与单测越完善,定位越快
# - 提交数 N 经 log2(N) 次即可定位(1000 提交约 10 次)
# - 期间工作区被 bisect 占用,无法开发,必要时 stash

6.9 git reflog 详解

reflog 记录 HEAD 与分支引用的所有变更(commit、reset、pull、rebase、checkout 等),是误操作的救命稻草。区别于 git log(提交历史),reflog 是本地操作日志,不随 push 同步,仅本机可见。

# 1. 查看 HEAD 的 reflog(默认)
git reflog                       # 等价于 git reflog show HEAD
# 输出格式:a1b2c3d HEAD@{0}: commit: feat: xxx
#          b2c3d4e HEAD@{1}: reset: moving to HEAD~1
# HEAD@{n} 表示倒数第 n 次操作前的 HEAD 位置

# 2. 查看指定分支的 reflog
git reflog show develop          # 仅 develop 分支的引用变更
git reflog show stash            # stash 的变更记录

# 3. 恢复误 reset/rebase 丢失的提交(高频救命场景)
git reflog                       # 找到操作前的提交 ID,如 b2c3d4e HEAD@{2}
git reset --hard b2c3d4e          # 强制回到该提交(工作区与暂存区都被覆盖)
# 或更安全的 cherry-pick:仅取出需要的提交,不影响当前分支
git cherry-pick b2c3d4e

# 4. 恢复误删分支
git reflog show 已删除分支名      # 找到该分支最后位置
git switch -c 已删除分支名 提交ID  # 基于提交重建分支

# 5. reflog 与过期清理
# reflog 默认保留 90 天(可达提交)、30 天(不可达提交),过期后 git gc 会清理
# 调整保留时长:
git config --global gc.reflogExpire "200 days"
git config --global gc.reflogExpireUnreachable "60 days"
# 立即清理(慎用,会丢失恢复窗口):
git reflog expire --expire=now --all && git gc --prune=now

# 6. 与 ORIG_HEAD 配合快速回滚上一次危险操作
git reset --hard ORIG_HEAD       # 回滚最近一次 merge/rebase/reset/pull

6.10 git worktree 工作树

worktree 允许同一仓库在多个目录同时检出不同分支,免去频繁 stash/switch,适合并行处理多任务(如同时改 feature 与紧急修复 hotfix)、长时间编译某分支、对比新旧版本。

# 1. 创建工作树(在另一目录检出指定分支)
git worktree add ../project-hotfix hotfix/login  # 在 ../project-hotfix 检出 hotfix/login
git worktree add -b feature/new ../project-feature develop  # 基于 develop 创建新分支并检出

# 2. 查看所有工作树
git worktree list
# 输出示例:
# /path/to/project       abc1234 [master]
# /path/to/project-hotfix def5678 [hotfix/login]

# 3. 在工作树中操作(cd 到该目录后正常使用 git 命令)
cd ../project-hotfix
git pull origin hotfix/login
# 修改并提交,提交归属同一仓库,分支互不干扰

# 4. 删除工作树(先清理工作区,再 prune)
cd 回主工作树
git worktree remove ../project-hotfix       # 删除工作树目录(分支保留)
git worktree prune                          # 清理已物理删除但未注册移除的工作树

# 5. 锁定工作树(防止误删,长期使用的工作树可锁)
git worktree lock ../project-hotfix --reason "等待发布"
git worktree unlock ../project-hotfix

# 注意:
# - 同一分支不可同时在多个工作树检出(除主工作树外)
# - worktree 共享 .git 仓库,提交、对象、引用统一管理
# - 工作树目录可位于仓库外,但建议放在同级或邻近目录便于管理

6.11 git submodule 与 git subtree

submodule 与 subtree 用于在一个仓库中引用另一个独立仓库,常见于引入第三方库、共享通用模块。

6.11.1 git submodule(子模块)

子模块将外部仓库作为子目录引用,保持独立 .git,主仓库仅记录子模块的提交 ID。

# 1. 添加子模块
git submodule add https://github.com/xxx/lib.git third-party/lib
git commit -m "chore: 引入 lib 子模块"
# 主仓库生成 .gitmodules 文件记录子模块配置

# 2. 克隆含子模块的仓库(默认不初始化子模块)
git clone --recurse-submodules https://github.com/xxx/main.git  # 自动初始化与更新
# 或已克隆后补初始化:
git submodule update --init --recursive  # 初始化并检出,递归处理嵌套子模块

# 3. 更新子模块到其远程最新
cd third-party/lib
git switch master && git pull
cd 回主仓库根目录
git add third-party/lib
git commit -m "chore: 升级 lib 子模块到最新"

# 4. 修改子模块代码并提交(需在子模块目录操作)
cd third-party/lib
# 修改文件,git add → git commit → git push origin <子模块分支>
# 主仓库记录子模块新提交 ID

# 5. 拉取主仓库后同步子模块
git pull origin master
git submodule update --init --recursive

# 6. 删除子模块
git submodule deinit third-party/lib      # 取消初始化
git rm third-party/lib                     # 从版本库删除
rm -rf .git/modules/third-party/lib       # 删除内部 .git 数据
git commit -m "chore: 移除 lib 子模块"

# 常见冲突:
# - 主仓库拉取后子模块未同步:git submodule update --init --recursive
# - 子模块切换到 detached HEAD:在子模块内 git switch <分支名> 后再开发

6.11.2 git subtree(子树合并)

subtree 将外部仓库合并为子目录,历史并入主仓库,无独立 .git,对使用者透明(无需特殊命令即可克隆使用)。

# 1. 添加 subtree(首次,将 lib 仓库内容放入 third-party/lib)
git remote add lib https://github.com/xxx/lib.git
git subtree add --prefix=third-party/lib lib master --squash
# --squash 压缩历史,避免主仓库混入子仓库完整历史

# 2. 更新 subtree 到子仓库最新
git subtree pull --prefix=third-party/lib lib master --squash

# 3. 修改子目录代码并推送回子仓库
git subtree push --prefix=third-party/lib lib master

# 4. 区别对比
# submodule:子仓库独立,主仓库仅记录 ID,克隆需 --recurse-submodules
# subtree:子仓库内容并入主仓库,历史合并,对克隆者透明,但历史可能膨胀
# 选型:外部维护、希望子仓库独立演进 → submodule;内部共享、希望对用户透明 → subtree

6.12 git lfs 大文件存储

Git LFS(Large File Storage)将大文件(二进制资源、视频、模型、安装包)存储于独立的 LFS 服务器,主仓库仅保留指针文件,避免 .git 目录膨胀与克隆缓慢。

# 1. 安装 Git LFS(一次性)
# Windows:随 Git for Windows 自带
# Mac:brew install git-lfs
# Linux:apt/yum install git-lfs
git lfs install   # 初始化(写入 ~/.gitconfig 的 filter 配置)

# 2. 配置 LFS 跟踪规则(仓库级,需提交 .gitattributes)
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "assets/*"
# 生成的 .gitattributes 需提交:
git add .gitattributes
git commit -m "chore: 配置 LFS 跟踪规则"

# 3. 正常添加大文件(自动转 LFS 存储)
git add assets/demo.psd
git commit -m "feat: 新增 demo 设计稿"
git push origin master

# 4. 克隆含 LFS 文件的仓库
git clone https://github.com/xxx/xxx.git  # 默认拉取 LFS 文件
git clone --no-lfs ...                    # 不拉取 LFS 文件(仅指针)
git lfs pull                              # 后续补拉 LFS 文件

# 5. 查看与校验
git lfs ls-files                          # 列出 LFS 跟踪的文件
git lfs status                            # 查看当前修改是否触发 LFS

# 6. 迁移已提交的大文件至 LFS(历史改写,谨慎,已推送分支慎用)
git lfs migrate import --include="*.psd" --everything  # 改写所有历史中的 psd 文件
# 配合 git push --force-with-lease 推送

6.13 git filter-repo 与 filter-branch

历史改写工具,用于清理敏感信息(密码、密钥)、删除误提交的大文件、修改作者信息等。git filter-branch 已被官方标注弃用(性能慢、易出错),推荐使用第三方工具 git-filter-repo。

# 1. 安装 git-filter-repo(Python 脚本,pip 安装)
pip install git-filter-repo
# 或直接下载脚本:https://raw.githubusercontent.com/newren/git-filter-repo/main/git-filter-repo

# 2. 清理误提交的敏感文件(如 config/local.env,从所有历史中删除)
git filter-repo --path config/local.env --invert-paths
# --invert-paths 表示排除该路径,即从历史删除

# 3. 清理指定大文件
git filter-repo --path target/big-data.bin --invert-paths

# 4. 批量删除符合模式的文件
git filter-repo --path-glob '*.log' --invert-paths

# 5. 修改作者邮箱(如旧邮箱迁移到新邮箱)
git filter-repo --mailmap mailmap.txt
# mailmap.txt 格式:<新邮箱> <旧邮箱>
# 或直接命令:
git filter-repo --commit-callback '
    if commit.author_email == b"old@company.com":
        commit.author_email = b"new@company.com"
        commit.committer_email = b"new@company.com"
'

# 6. 替换敏感字符串(如 API Key)
git filter-repo --replace-text expressions.txt
# expressions.txt 格式:
# api_key_abc123==>REDACTED
# password=secret==>password=REDACTED

# 7. 改写后强制推送(已推送的远程分支,谨慎)
git push --force-with-lease --all
git push --force-with-lease --tags
# 团队成员需重新克隆,避免历史错位

# 8. filter-branch 兼容(已弃用,仅作了解)
git filter-branch --tree-filter 'rm -f config/local.env' --prune-empty HEAD
# 速度慢,且会留下 refs/original/ 备份,需手动清理:
git for-each-ref --format='%(refname)' refs/original/ | xargs -n1 git update-ref -d

# 注意:
# - filter-repo 默认要求仓库为 fresh clone,避免改写未同步历史
# - 改写后所有提交哈希变化,标签与分支需重新推送
# - 团队协作时改写历史属高风险操作,需提前通知并约定重新克隆时间

6.14 git sparse-checkout 稀疏检出

针对超大仓库,仅检出部分目录到工作区,避免克隆全量文件造成磁盘与时间浪费。Monorepo(多包仓库)场景常用。

# 1. 启用 sparse-checkout(Git 2.25+)
git clone --no-checkout https://github.com/xxx/monorepo.git
cd monorepo
git sparse-checkout init --cone          # 启用 cone 模式(推荐,基于目录匹配,性能更好)

# 2. 设置需要检出的目录
git sparse-checkout set packages/app packages/common
# 仅 packages/app 与 packages/common 会出现在工作区,其余仅索引

# 3. 添加更多目录
git sparse-checkout add packages/admin

# 4. 查看当前稀疏检出配置
git sparse-checkout list

# 5. 取消稀疏检出(检出全部)
git sparse-checkout disable

# 6. cone 模式与非 cone 模式区别
# cone 模式:基于目录树匹配,性能优,推荐
# 非 cone 模式:支持通配符与复杂规则,但慢,需手动编辑 .git/info/sparse-checkout
# 切换:git sparse-checkout set --no-cone <目录>

# 注意:
# - 未检出的目录在工作区不存在,但仍在 .git 索引中,切换分支可能恢复
# - 与 LFS 配合可进一步降低首次克隆成本
# - IDE 可能误识别未检出目录为已删除,需配置 IDE 忽略

6.15 常见 GUI 与可视化工具

GUI 工具适合可视化分支、合并、stash 与提交历史,新手或评审场景效率更高。命令行仍是基础,GUI 仅作辅助。

  • 命令行增强:

    • tig:终端 Git 浏览器,键位 vim 风格,查看 log/diff/blame 速度快。
    • lazygit:终端 TUI,鼠标与键盘双操作,stash/cherry-pick/rebase -i 可视化操作。
    • gitui:Rust 实现,性能好,类似 lazygit。
  • 桌面 GUI:

    • GitHub Desktop:GitHub 官方,操作简洁,适合新手与 GitHub 用户。
    • Sourcetree:Atlassian 出品,功能全面,分支图清晰,Mac/Windows 均有。
    • GitKraken:跨平台,UI 现代化,支持 GitHub/GitLab/Bitbucket 集成,免费版限公开仓库。
    • Fork:轻量快速,Mac/Windows,免费版功能已足够日常使用。
    • Tower:Mac/Windows 商业软件,功能与稳定性均佳,适合重度用户。
  • IDE 集成:

    • IntelliJ IDEA / WebStorm / PyCharm:内置 Git 工具,diff/merge/conflict 解决体验佳。
    • VS Code:内置 Git 与 GitLens 扩展,blame/diff 可视化,配合 GitHub Pull Requests 扩展可发起/评审 PR。
    • Eclipse:EGit 插件,团队迁移成本低。
  • 远程托管平台:

    • GitHub:开源生态最大,Actions CI/CD 强大。
    • GitLab:自建首选,内置 CI/CD、Issue、Wiki 一体化。
    • Gitee:国内访问快,适合国内团队。
    • Bitbucket:Atlassian 生态,与 Jira/Confluence 联动。
    • 自建 Gitea / Gogs:轻量自建,资源占用低,私有化部署首选。

工具选型无标准答案,按团队习惯与项目托管平台决定,命令行能力仍是地基,GUI 仅作可视化的延伸。