Git 使用手册

本文档是一份全面的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 .      # 取消所有文件的暂存

1.3.4 提交文件（暂存区 → 本地版本库）

# 1. 基础提交（暂存后，提交到本地版本库）
git commit -m "提交说明"  # 简化命令：git ci -m "提交说明"
# 提交说明规范（团队协作必守）：
# - 简洁明了，一句话说明提交目的（不超过50字）
# - 格式：类型: 描述（如：feat: 新增用户登录接口；fix: 修复首页加载缓慢问题）
# - 常见类型：feat（新功能）、fix（修复bug）、docs（文档修改）、style（代码格式调整，不影响功能）、refactor（重构代码）、test（新增/修改测试用例）、chore（构建/依赖调整）

# 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命令

第二章 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密钥（一路回车，无需输入密码）
ssh-keygen -t rsa -C "你的邮箱"  # 邮箱与Git配置的邮箱一致（如：zhangsan@163.com）
# 执行后，会在~/.ssh目录下生成两个文件：
# - id_rsa：私钥（重要，请勿泄露，保存在本地）
# - id_rsa.pub：公钥（需复制到远程仓库）

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

# 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  # 清理本地不存在的远程分支（如远程已删除的分支，本地同步删除）

第三章 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（基于当前分支）
# 基于指定分支创建新分支（推荐，明确分支来源）
git checkout -b 新分支名 基准分支名  # 如：git checkout -b feature/user-login develop（基于develop创建）

# 5. 切换本地分支（切换到已存在的本地分支）
git checkout 分支名  # 简化命令：git co 分支名（如：git co develop）
# 注意：切换分支前，需确保当前分支的修改已提交或暂存，否则会提示冲突

# 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）

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命令（会导致团队成员代码冲突）

3.4 分支管理进阶技巧

# 1. 暂存本地修改（stash，切换分支时常用）
# 场景：当前分支有未提交的修改，需切换到其他分支，又不想提交当前修改
git stash  # 暂存当前所有未提交的修改（工作区+暂存区）
git stash save "暂存说明"  # 带说明的暂存，便于后续区分（如：git stash save "未完成的用户登录功能"）

# 2. 查看所有stash暂存记录
git stash list  # 显示所有暂存，格式：stash@{0}: On 分支名: 暂存说明

# 3. 恢复stash暂存的修改（两种方式）
git stash apply  # 恢复最近一次暂存的修改（stash@{0}），暂存记录保留（可多次恢复）
git stash apply stash@{n}  # 恢复指定的暂存记录（n为暂存索引，如：git stash apply stash@{1}）
git stash pop  # 恢复最近一次暂存的修改，同时删除该暂存记录（推荐，避免暂存记录堆积）

# 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  # 挑选多个提交（按顺序）
# 4. 若出现冲突，处理方式与merge、rebase一致：修改冲突 → git add → git cherry-pick --continue
# 5. 放弃cherry-pick：git cherry-pick --abort

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

第四章 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恢复，需借助第三方工具

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.2 Git 命令别名配置

# 常用别名配置（全局生效）
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、修改时间）