发布于

Git 详细教程

Authors

本教程面向初学者到中级用户,覆盖:安装与配置、核心概念与工作原理、日常命令、分支与合并、远程协作、撤销与回退、高级技巧,以及常见问题排查。

目录

  1. 什么是 Git
  2. 安装与初始配置
  3. 工作原理
  4. 快速上手:第一个仓库
  5. 基础命令详解
  6. 分支管理
  7. 合并与变基
  8. 远程仓库与协作
  9. 撤销与回退
  10. 暂存与清理
  11. 标签
  12. 查看历史与比较差异
  13. 高级命令
  14. .gitignore 与 .gitattributes
  15. 常见工作流
  16. 常见问题与排错
  17. 命令速查表

1. 什么是 Git

Git 是一个分布式版本控制系统,由 Linus Torvalds 于 2005 年为管理 Linux 内核源码而创建。

它解决的问题:

  • 记录文件的每一次修改,随时回到任意历史版本
  • 多人并行开发,互不干扰,并能合并成果
  • 离线工作:每个人本地都有完整的仓库和历史
  • 通过分支低成本地试验新想法

集中式 vs 分布式

特性集中式(如 SVN)分布式(Git)
完整历史存放位置仅服务器每个开发者本地都有完整副本
离线提交不支持支持
分支成本较高极低(只是一个指针)
单点故障服务器损坏会丢失历史任何克隆都可恢复

Git 与 GitHub 的区别

  • Git:本地运行的版本控制软件
  • GitHub / GitLab / Gitee / Bitbucket:托管 Git 仓库的在线平台,提供协作、代码审查、CI 等功能

2. 安装与初始配置

2.1 安装

Windows

  1. 访问 git-scm.com 下载安装包并运行
  2. 默认选项通常即可;建议选择 "Git from the command line and also from 3rd-party software"
  3. 也可以使用包管理器:
winget install --id Git.Git -e --source winget
# 或
choco install git
# 或
scoop install git

macOS

# 方式一:Xcode 命令行工具(自带 Git)
xcode-select --install

# 方式二:Homebrew(版本更新)
brew install git

Linux

# Debian / Ubuntu
sudo apt update && sudo apt install git

# Fedora / RHEL / CentOS
sudo dnf install git

# Arch Linux
sudo pacman -S git

# openSUSE
sudo zypper install git

验证安装

git --version
# 输出示例:git version 2.47.0

2.2 初始配置

Git 的配置分三个层级,优先级从低到高:

级别参数文件位置作用范围
系统级--system/etc/gitconfig本机所有用户
用户级--global~/.gitconfig当前用户所有仓库
仓库级--local(默认).git/config当前仓库

必做配置:用户身份

每次提交都会记录作者信息,必须先设置:

git config --global user.name "你的名字"
git config --global user.email "you@example.com"

推荐配置

# 默认分支名使用 main
git config --global init.defaultBranch main

# 设置编辑器(例如 VS Code)
git config --global core.editor "code --wait"

# 换行符处理
# Windows:提交时转 LF,检出时转 CRLF
git config --global core.autocrlf true
# macOS / Linux:提交时转 LF,检出不转换
git config --global core.autocrlf input

# 彩色输出
git config --global color.ui auto

# pull 时默认使用 merge(可改为 rebase),
# false:关闭 rebase 模式。既然不使用 rebase,Git 就会默认使用传统且安全的 merge(合并) 模式。
git config --global pull.rebase false

# 中文文件名不转义
git config --global core.quotepath false

# 设置常用别名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --graph --oneline --decorate --all"

查看配置

git config --list              # 查看所有配置
git config --global --list     # 仅查看全局配置
git config user.name           # 查看单项
git config --global --edit     # 用编辑器打开全局配置文件

2.3 配置 SSH 密钥(推荐)

使用 SSH 连接远程仓库,可避免反复输入密码。

# 1. 生成密钥(推荐 ed25519)
ssh-keygen -t ed25519 -C "you@example.com"
# 一路回车即可,密钥默认保存在 ~/.ssh/id_ed25519

# 2. 启动 ssh-agent 并添加密钥
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 3. 复制公钥内容
cat ~/.ssh/id_ed25519.pub

将公钥内容粘贴到 GitHub / GitLab 的 Settings → SSH and GPG keys 中,然后测试:

ssh -T git@github.com
# Hi username! You've successfully authenticated...

3. 工作原理

理解原理是掌握 Git 的关键。很多"诡异"的现象,在理解了内部模型后都会变得自然。

3.1 三个区域

Git 中文件存在于三个区域之间流动:

┌────────────────┐   git add    ┌────────────────┐  git commit  ┌────────────────┐
│    工作区       │ ───────────► │   暂存区        │ ───────────► │   本地仓库      │
│ Working Dir    │              │ Staging / Index │              │ Repository     │
│ (你编辑的文件) │ ◄─────────── │ (下次提交的快照)│              │ (.git 目录)   │
└────────────────┘  git restore └────────────────┘              └────────────────┘
        ▲                                                               │
        └───────────────────── git checkout / switch ◄──────────────────┘
  • 工作区(Working Directory):你在磁盘上看到并编辑的文件
  • 暂存区(Staging Area / Index):一个清单,记录"下一次提交将包含什么"
  • 本地仓库(Repository):.git 目录,保存全部历史

3.2 文件的四种状态

状态含义
Untracked未跟踪,Git 尚不认识此文件
Unmodified已跟踪,且与最新提交一致
Modified已修改,但未暂存
Staged已暂存,将进入下一次提交

3.3 Git 是快照,不是差异

许多旧系统存储"每个版本相对上一版本的差异"。Git 则是在每次提交时,对整个项目目录拍一张快照。未改变的文件不会重复存储,只保存指向之前相同文件的链接,因此既快又省空间。

3.4 四种对象

Git 的底层是一个内容寻址的键值数据库。所有数据保存在 .git/objects 中,以 SHA-1(新版本可选 SHA-256)哈希作为键。共有四种对象:

对象作用类比
blob存储文件内容(不含文件名)文件
tree存储目录结构,指向 blob 和子 tree目录
commit指向一个 tree,并记录作者、时间、说明、父提交一次快照
tag给某个对象(通常是 commit)起永久名称标记

一次提交的内部结构:

commit a1b2c3d
├── tree 9f8e7d6            ← 项目根目录快照
│   ├── blob 1a2b3c  README.md
│   ├── blob 4d5e6f  main.py
│   └── tree 7a8b9c  src/
│       └── blob 0c1d2e  utils.py
├── parent 5f4e3d2          ← 上一个提交
├── author  张三 <z@x.com>
└── message "添加主程序"

可以亲自观察:

git cat-file -t HEAD        # 查看对象类型:commit
git cat-file -p HEAD        # 查看 commit 内容
git cat-file -p HEAD^{tree} # 查看对应的 tree
git ls-tree HEAD            # 列出根目录的树
git hash-object README.md   # 计算文件的哈希

3.5 提交形成有向无环图(DAG)

每个 commit 记录自己的父提交(合并提交有两个或更多父提交),这样历史构成一张图:

A ← B ← C ← D        main
         ↖
          E ← F      feature

3.6 分支、HEAD 与引用

  • 分支(branch):本质上只是一个指向某个 commit 的可移动指针,保存在 .git/refs/heads/ 下,文件内容就是一个 40 位哈希
  • HEAD:一个特殊指针,指向"你当前所在的分支"(或某个具体提交)
  • 标签(tag):指向某个 commit 的固定指针
            HEAD
              │
              ▼
            main
              │
              ▼
A ← B ← C ← D

创建分支只是新建一个 41 字节的文件,所以 Git 的分支极其廉价。

cat .git/HEAD
# ref: refs/heads/main

cat .git/refs/heads/main
# a1b2c3d4e5f6...(一个提交哈希)

分离头指针(detached HEAD):当 HEAD 直接指向某个提交而非分支时就会出现,此时新产生的提交没有分支引用,切走后容易丢失。

3.7 .git 目录结构

.git/
├── HEAD            当前分支指针
├── config          仓库级配置
├── index           暂存区(二进制文件)
├── objects/        所有对象(blob、tree、commit、tag)
│   ├── pack/       打包压缩后的对象
│   └── ab/cdef...  松散对象,目录名为哈希前两位
├── refs/
│   ├── heads/      本地分支
│   ├── remotes/    远程跟踪分支
│   └── tags/       标签
├── hooks/          钩子脚本
├── logs/           引用变更日志(reflog 的数据来源)
└── info/exclude    本仓库私有的忽略规则

永远不要手动修改 .git 目录中的文件,除非你清楚自己在做什么。

3.8 一次 git add + git commit 内部发生了什么

  1. git add file:为文件内容创建 blob 对象,并更新 index(暂存区)
  2. git commit:根据 index 生成 tree 对象,创建 commit 对象指向该 tree 和父提交,然后将当前分支指针移到新提交

3.9 远程仓库与远程跟踪分支

  • remote:远程仓库的别名,默认叫 origin
  • 远程跟踪分支:形如 origin/main,是本地对远程分支状态的只读缓存,仅在 fetch / pull / push 时更新
本地                          远程(origin)
main  ──► C                   main ──► D
origin/main ──► C   (fetch 后更新为 D)

4. 快速上手:第一个仓库

# 1. 创建目录并初始化
mkdir my-project && cd my-project
git init

# 2. 创建文件
echo "# My Project" > README.md

# 3. 查看状态
git status

# 4. 添加到暂存区
git add README.md

# 5. 提交
git commit -m "初始提交:添加 README"

# 6. 查看历史
git log --oneline

典型的日常循环:

修改文件 → git status → git add → git commit → git push

5. 基础命令详解

5.1 git init:初始化仓库

git init                    # 在当前目录初始化
git init my-repo            # 创建新目录并初始化
git init -b main            # 指定初始分支名
git init --bare server.git  # 创建裸仓库(无工作区,用作服务器共享仓库)

5.2 git clone:克隆远程仓库

git clone https://github.com/user/repo.git
git clone git@github.com:user/repo.git          # SSH 方式
git clone https://github.com/user/repo.git mydir  # 指定本地目录名
git clone -b dev https://github.com/user/repo.git # 克隆并检出指定分支
git clone --depth 1 https://github.com/user/repo.git  # 浅克隆,只取最新一次提交
git clone --recurse-submodules <url>            # 同时克隆子模块

5.3 git status:查看状态

git status          # 完整输出
git status -s       # 简洁输出
git status -sb      # 简洁 + 显示分支信息

简洁输出的含义:

 M file1.txt    工作区已修改,未暂存
M  file2.txt    已暂存
MM file3.txt    暂存后又被修改
A  file4.txt    新增并已暂存
D  file5.txt    已删除并暂存
?? file6.txt    未跟踪

5.4 git add:添加到暂存区

git add file.txt            # 添加指定文件
git add dir/                # 添加整个目录
git add .                   # 添加当前目录下所有变更
git add -A                  # 添加整个仓库所有变更(含删除)
git add *.js                # 通配符
git add -u                  # 只添加已跟踪文件的修改和删除,不含新文件
git add -p                  # 交互式按"块"选择要暂存的内容(非常有用)

5.5 git commit:提交

git commit -m "提交说明"
git commit -am "说明"          # 自动暂存所有已跟踪文件的修改并提交(不含新文件)
git commit                     # 打开编辑器编写详细说明
git commit --amend             # 修改最近一次提交(说明或内容)
git commit --amend --no-edit   # 追加变更到上次提交,保持说明不变
git commit --allow-empty -m "触发 CI"  # 允许空提交
git commit -S -m "签名提交"     # GPG 签名

提交信息规范(推荐 Conventional Commits)

<类型>(<范围>): <简短描述>

<详细说明,可选>

<脚注,可选>

常见类型:

类型含义
feat新功能
fix修复缺陷
docs文档变更
style代码格式(不影响逻辑)
refactor重构
perf性能优化
test测试相关
chore构建、工具、依赖等杂项

示例:

feat(auth): 添加邮箱验证码登录

- 新增发送验证码接口
- 登录页增加验证码输入框

Closes #123

5.6 git diff:查看差异

git diff                    # 工作区 vs 暂存区(未暂存的修改)
git diff --staged           # 暂存区 vs 最新提交(已暂存的修改),同 --cached
git diff HEAD               # 工作区 vs 最新提交
git diff A B                # 两个提交之间
git diff main..feature      # 两个分支之间
git diff --stat             # 只显示统计摘要
git diff --name-only        # 只显示变更的文件名
git diff -- path/file.txt   # 限定某个文件

5.7 git log:查看提交历史

git log                         # 完整历史
git log --oneline               # 每个提交一行
git log --graph --oneline --all # ASCII 图形化展示所有分支
git log -n 5                    # 最近 5 条
git log -p                      # 同时显示每次提交的差异
git log --stat                  # 显示每次提交的文件统计
git log --author="张三"          # 按作者过滤
git log --since="2 weeks ago"   # 按时间过滤
git log --until="2026-01-01"
git log --grep="修复"            # 按提交信息搜索
git log -S"functionName"        # 搜索内容变更中出现该字符串的提交(pickaxe)
git log -- path/file.txt        # 某个文件的历史
git log --follow file.txt       # 跟踪文件重命名
git log main..feature           # 在 feature 但不在 main 中的提交
git log --pretty=format:"%h %an %ad %s" --date=short

5.8 git show:查看对象详情

git show                 # 最新提交
git show a1b2c3d         # 指定提交
git show HEAD~2          # 前两个提交
git show v1.0            # 标签
git show a1b2c3d:path/file.txt   # 某提交中某文件的内容

5.9 git rm 与 git mv

git rm file.txt              # 删除文件并暂存删除
git rm --cached file.txt     # 仅从 Git 中移除,保留本地文件(常用于补加 .gitignore)
git rm -r dir/               # 递归删除目录
git mv old.txt new.txt       # 重命名/移动(等价于 mv + git add)

5.10 git restore:恢复文件(Git 2.23+)

git restore file.txt                  # 丢弃工作区修改(危险,不可恢复)
git restore --staged file.txt         # 取消暂存,保留工作区修改
git restore --source=HEAD~2 file.txt  # 从指定提交恢复文件
git restore .                         # 丢弃所有工作区修改

5.11 git blame:逐行追溯

git blame file.txt           # 每行最后一次修改的提交与作者
git blame -L 10,20 file.txt  # 只看 10~20 行

6. 分支管理

6.1 查看分支

git branch              # 本地分支,* 标记当前分支
git branch -v           # 附带最新提交信息
git branch -vv          # 附带上游分支与领先/落后情况
git branch -a           # 本地 + 远程跟踪分支
git branch -r           # 仅远程跟踪分支
git branch --merged     # 已合并到当前分支的分支
git branch --no-merged  # 尚未合并的分支

6.2 创建与切换

git branch feature-x             # 创建分支(不切换)
git switch feature-x             # 切换分支(Git 2.23+,推荐)
git switch -c feature-x          # 创建并切换
git switch -c fix origin/fix     # 基于远程分支创建并切换

# 旧写法,仍然通用
git checkout feature-x
git checkout -b feature-x

6.3 重命名与删除

git branch -m old new            # 重命名
git branch -m new                # 重命名当前分支
git branch -d feature-x          # 删除已合并的分支
git branch -D feature-x          # 强制删除(即使未合并)
git push origin --delete feature-x   # 删除远程分支

6.4 分支命名建议

前缀用途示例
feature/新功能feature/user-login
fix/ 或 bugfix/修复缺陷fix/null-pointer
hotfix/线上紧急修复hotfix/payment-crash
release/发布准备release/1.2.0
docs/文档docs/api-guide

7. 合并与变基

7.1 git merge:合并

把另一个分支的变更并入当前分支:

git switch main
git merge feature-x

快进合并(Fast-forward)

当前分支是目标分支的直接祖先时,Git 只需移动指针:

合并前:  A ← B ← C       main
                   ↖
                    D ← E   feature

合并后:  A ← B ← C ← D ← E   main, feature

三方合并(Three-way merge)

两个分支各自有新提交,会生成一个合并提交:

合并前:  A ← B ← C ← F     main
                ↖
                 D ← E      feature

合并后:  A ← B ← C ← F ← M   main
                ↖       ↗
                 D ← E        feature
git merge feature-x             # 默认:能快进则快进,否则生成合并提交
git merge --no-ff feature-x     # 始终生成合并提交(保留分支历史)
git merge --squash feature-x    # 把所有提交压成一个变更放入暂存区,需再手动 commit
git merge --abort               # 合并出现冲突时放弃合并

7.2 解决冲突

当两个分支修改了同一文件的同一区域,合并会停下并标记冲突:

<<<<<<< HEAD
当前分支的内容
=======
被合并分支的内容
>>>>>>> feature-x

处理步骤:

# 1. 查看冲突文件
git status

# 2. 手动编辑文件,保留需要的内容,删除 <<<<<<<、=======、>>>>>>> 标记

# 3. 标记为已解决
git add path/to/file

# 4. 完成合并
git commit

# 想放弃时
git merge --abort

可以使用合并工具:

git mergetool

7.3 git rebase:变基

把当前分支的提交"搬"到另一个分支的最新提交之后,使历史呈一条直线:

变基前:  A ← B ← C       main
                ↖
                 D ← E    feature

变基后:  A ← B ← C       main
                   ↖
                    D' ← E'   feature   (D'、E' 是新的提交,哈希不同)
git switch feature
git rebase main

# 冲突时
git add <文件>
git rebase --continue
git rebase --skip       # 跳过当前提交
git rebase --abort      # 放弃变基

交互式变基:整理提交历史

git rebase -i HEAD~4    # 整理最近 4 个提交

编辑器中会列出提交,可修改每行前的命令:

命令作用
pick保留该提交
reword保留提交,但修改提交说明
edit暂停,允许修改该提交内容
squash合并到上一个提交,并合并说明
fixup合并到上一个提交,丢弃本提交说明
drop删除该提交

也可以调整行顺序来重排提交。

黄金法则:不要对已经推送并被他人使用的公共分支执行变基,因为它会重写历史。

7.4 merge 与 rebase 如何选择

对比mergerebase
历史形态保留真实分支结构,有合并提交线性、整洁
是否改写历史否是(生成新提交)
适用场景合并公共分支、保留上下文整理本地私有分支、同步主干最新改动
风险低误用于公共分支会造成麻烦

7.5 git cherry-pick:摘取提交

把某个提交的变更应用到当前分支:

git cherry-pick a1b2c3d
git cherry-pick a1b2c3d b2c3d4e     # 多个提交
git cherry-pick A^..B               # 一段范围(含 A 与 B)
git cherry-pick -n a1b2c3d          # 只应用变更,不自动提交
git cherry-pick --continue / --abort

8. 远程仓库与协作

8.1 管理远程

git remote -v                               # 查看远程及其地址
git remote add origin git@github.com:user/repo.git
git remote add upstream https://github.com/original/repo.git   # fork 工作流常用
git remote rename origin github
git remote remove upstream
git remote set-url origin <新地址>
git remote show origin                      # 查看远程详情

8.2 git fetch:获取远程更新(不合并)

git fetch                  # 从默认远程获取
git fetch origin
git fetch --all            # 所有远程
git fetch --prune          # 同时清理远程已删除的跟踪分支
git fetch origin main:tmp  # 把远程 main 取到本地 tmp 分支

8.3 git pull:获取并合并

git pull 等价于 git fetch 加 git merge(或使用 --rebase 时为 fetch 加 rebase):

git pull                       # 获取并合并当前分支的上游
git pull origin main
git pull --rebase              # 用变基代替合并,历史更线性
git pull --ff-only             # 仅允许快进,否则报错(更安全)

8.4 git push:推送

git push origin main                    # 推送本地 main 到远程 main
git push -u origin main                 # 同时设置上游分支,之后可直接 git push
git push                                # 已设置上游时
git push origin feature-x               # 推送新分支
git push origin --delete feature-x      # 删除远程分支
git push --tags                         # 推送所有标签
git push origin v1.0                    # 推送单个标签
git push --force-with-lease             # 安全的强制推送(推荐)
git push --force                        # 强制推送(危险,慎用)

强制推送会覆盖远程历史,请优先使用 --force-with-lease:若远程在你上次拉取后有他人新提交,推送会被拒绝。

8.5 上游分支(upstream)

git branch -u origin/main               # 为当前分支设置上游
git branch --set-upstream-to=origin/main
git branch -vv                          # 查看上游与领先/落后
git switch -c feature origin/feature    # 基于远程分支创建本地分支

8.6 Fork + Pull Request 流程

# 1. 在 GitHub 上 Fork 原仓库,然后克隆你的 fork
git clone git@github.com:你的用户名/repo.git
cd repo

# 2. 添加原仓库为 upstream
git remote add upstream https://github.com/original/repo.git

# 3. 同步上游最新代码
git fetch upstream
git switch main
git merge upstream/main     # 或 git rebase upstream/main

# 4. 创建功能分支,开发并提交
git switch -c feature/my-change
# ...修改、提交...

# 5. 推送到你的 fork
git push -u origin feature/my-change

# 6. 在 GitHub 页面发起 Pull Request

9. 撤销与回退

撤销方式取决于变更处于哪个区域,以及是否已经推送。

9.1 决策速查

场景推荐命令
丢弃工作区某文件的修改git restore file
取消暂存git restore --staged file
修改上一次提交(未推送)git commit --amend
撤销最近提交,保留修改在暂存区git reset --soft HEAD~1
撤销最近提交,保留修改在工作区git reset --mixed HEAD~1
撤销最近提交,并丢弃所有修改git reset --hard HEAD~1
撤销已推送的提交(不改写历史)git revert <提交>
找回误删的提交/分支git reflog

9.2 git reset:移动分支指针

三种模式,影响范围依次增大:

模式移动 HEAD/分支重置暂存区重置工作区
--soft✅❌❌
--mixed(默认)✅✅❌
--hard✅✅✅
git reset --soft HEAD~1      # 回到上一个提交,变更仍在暂存区
git reset HEAD~1             # 回到上一个提交,变更在工作区(未暂存)
git reset --hard HEAD~1      # 回到上一个提交,丢弃所有变更
git reset --hard a1b2c3d     # 回到指定提交
git reset file.txt           # 取消暂存某文件(等同 restore --staged)
git reset --hard origin/main # 让本地分支与远程完全一致

--hard 会丢弃未提交的工作,且无法通过 Git 找回。执行前务必确认。

9.3 git revert:用新提交抵消旧提交

不改写历史,适用于已推送的提交:

git revert a1b2c3d             # 生成一个新提交,内容与 a1b2c3d 相反
git revert HEAD                # 撤销最近一次提交
git revert -n a1b2c3d          # 只应用反向变更,不自动提交
git revert -m 1 <合并提交>      # 撤销一个合并提交,-m 1 表示保留主线(第一个父提交)

9.4 git reflog:后悔药

reflog 记录 HEAD 与分支指针的每一次移动(仅本地,默认保留约 90 天),即使你 reset --hard 了也能找回:

git reflog
# a1b2c3d HEAD@{0}: reset: moving to HEAD~2
# e4f5a6b HEAD@{1}: commit: 添加登录功能
# ...

git reset --hard e4f5a6b       # 回到误操作之前
git switch -c rescue e4f5a6b   # 或者基于它创建分支

9.5 git clean:清理未跟踪文件

git clean -n         # 预演:显示将被删除的文件
git clean -f         # 删除未跟踪文件
git clean -fd        # 同时删除未跟踪目录
git clean -fdx       # 连同被 .gitignore 忽略的文件一起删除(慎用)

10. 暂存与清理

10.1 git stash:临时保存工作进度

当你需要临时切换分支,但当前修改还不想提交时:

git stash                        # 保存已跟踪文件的修改,并还原工作区
git stash push -m "说明"          # 附带说明
git stash -u                     # 同时保存未跟踪文件
git stash -a                     # 同时保存未跟踪与被忽略的文件
git stash list                   # 查看所有暂存记录
git stash show -p stash@{0}      # 查看某条暂存的差异
git stash pop                    # 恢复最近一条并从列表删除
git stash apply stash@{1}        # 恢复指定一条,保留在列表中
git stash drop stash@{0}         # 删除一条
git stash clear                  # 清空全部
git stash branch new-branch      # 基于暂存内容创建新分支

11. 标签

标签用来标记重要节点,如版本发布。

git tag                          # 列出标签
git tag -l "v1.*"                # 按模式过滤
git tag v1.0                     # 轻量标签
git tag -a v1.0 -m "正式发布 1.0" # 附注标签(推荐,含作者、日期、说明)
git tag -a v0.9 a1b2c3d          # 为历史提交打标签
git show v1.0                    # 查看标签详情
git push origin v1.0             # 推送单个标签
git push origin --tags           # 推送所有标签
git tag -d v1.0                  # 删除本地标签
git push origin --delete v1.0    # 删除远程标签
git switch --detach v1.0         # 检出标签(分离头指针)

推荐使用语义化版本:主版本.次版本.修订号,例如 v2.3.1。


12. 查看历史与比较差异

12.1 相对引用

写法含义
HEAD当前提交
HEAD~1 或 HEAD~第一父提交(上一个提交)
HEAD~3往上数第 3 代祖先(沿第一父提交)
HEAD^第一个父提交
HEAD^2合并提交的第二个父提交
main@{yesterday}main 昨天所指向的提交
a1b2c3d哈希前缀(至少 4 位,通常用 7 位)

12.2 区间语法

git log A..B     # 在 B 中但不在 A 中的提交
git log A...B    # 仅在 A 或仅在 B 中的提交(对称差)
git diff A...B   # B 相对于 A、B 共同祖先的变更(PR 的视角)

12.3 图形化历史的常用别名

git config --global alias.lg "log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(auto)%d%C(reset)' --all"

git lg

13. 高级命令

13.1 git bisect:二分查找引入缺陷的提交

git bisect start
git bisect bad                 # 当前版本有问题
git bisect good v1.0           # v1.0 是正常的
# Git 会自动检出中间提交,测试后告诉它结果:
git bisect good                # 或 git bisect bad
# 重复直到找到首个出错的提交
git bisect reset               # 结束,回到原分支

# 自动化:让脚本判断,返回 0 表示 good
git bisect run ./test.sh

13.2 git worktree:同一仓库多个工作目录

不用 stash 也能同时处理多个分支:

git worktree add ../hotfix hotfix-branch      # 在 ../hotfix 检出已有分支
git worktree add -b new-feat ../new-feat      # 新建分支并检出
git worktree list
git worktree remove ../hotfix

13.3 git submodule:子模块

在仓库中引用另一个仓库:

git submodule add https://github.com/user/lib.git libs/lib
git submodule update --init --recursive     # 克隆后初始化子模块
git submodule update --remote               # 更新到子模块远程最新
git clone --recurse-submodules <url>

13.4 git filter-repo:改写历史(如彻底删除误提交的密钥或大文件)

filter-repo 是独立工具,需额外安装(pip install git-filter-repo):

git filter-repo --path secrets.txt --invert-paths     # 从全部历史中删除某文件
git filter-repo --strip-blobs-bigger-than 10M          # 删除大于 10MB 的对象

改写历史后需强制推送,并要求所有协作者重新克隆。如果泄露了密钥,首先要做的是作废并更换密钥。

13.5 钩子(Hooks)

位于 .git/hooks/ 的脚本,在特定事件触发:

钩子触发时机典型用途
pre-commit提交前代码格式化、静态检查
commit-msg填写提交信息后校验提交信息规范
pre-push推送前运行测试
post-merge合并后自动安装依赖

示例:.git/hooks/pre-commit

#!/bin/sh
npm run lint || exit 1
chmod +x .git/hooks/pre-commit

团队共享钩子可使用 Husky、pre-commit 等工具。

13.6 其他实用命令

git shortlog -sn                  # 按作者统计提交数
git grep "keyword"                # 在已跟踪文件中搜索
git describe --tags               # 基于最近标签生成版本描述
git archive -o out.zip HEAD       # 导出当前提交为压缩包(不含 .git)
git gc                            # 垃圾回收,压缩对象库
git fsck                          # 检查仓库完整性
git count-objects -vH             # 查看仓库体积
git ls-files                      # 列出已跟踪文件
git rev-parse HEAD                # 输出当前提交完整哈希
git rev-parse --abbrev-ref HEAD   # 输出当前分支名

14. .gitignore 与 .gitattributes

14.1 .gitignore

告诉 Git 忽略哪些文件,放在仓库根目录(也可在子目录中)。

# 注释以 # 开头

# 忽略所有 .log 文件
*.log

# 忽略目录
node_modules/
dist/
build/

# 忽略特定文件
.env
.DS_Store

# 取反:不忽略 important.log
!important.log

# 仅忽略根目录下的 TODO 文件
/TODO

# 忽略 doc 目录下所有 .pdf(任意深度)
doc/**/*.pdf

规则要点:

模式含义
*匹配任意字符(不含 /)
**匹配多级目录
?匹配单个字符
[abc]匹配括号内任一字符
以 / 开头只匹配仓库根目录
以 / 结尾只匹配目录
以 ! 开头取反(重新包含)

文件已被跟踪时,加入 .gitignore 不会生效,需要先从索引中移除:

git rm --cached file.txt
git rm -r --cached dir/
git commit -m "停止跟踪 file.txt"

检查某文件为何被忽略:

git check-ignore -v path/to/file

全局忽略(对所有仓库生效,适合放编辑器/系统文件):

git config --global core.excludesfile ~/.gitignore_global

github/gitignore 提供了各语言的模板。

14.2 .gitattributes

控制路径级别的行为,例如统一换行符、指定二进制文件、配置 Git LFS:

* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png binary
*.psd filter=lfs diff=lfs merge=lfs -text

14.3 Git LFS:管理大文件

git lfs install
git lfs track "*.psd"
git add .gitattributes
git add design.psd
git commit -m "添加设计稿"

15. 常见工作流

15.1 集中式工作流

所有人直接在 main 上工作,适合很小的团队:

git pull --rebase
# 修改、提交
git push

15.2 功能分支工作流(Feature Branch)

最通用,配合 Pull Request / Merge Request 做代码审查:

git switch main
git pull
git switch -c feature/xxx
# 开发并提交若干次
git push -u origin feature/xxx
# 在平台上发起 PR,评审通过后合并
git switch main
git pull
git branch -d feature/xxx

15.3 Git Flow

使用长期分支与多种临时分支:

分支作用
main生产代码,每个提交都是一个发布
develop集成分支,开发的主线
feature/*从 develop 分出,完成后合回 develop
release/*发布准备,从 develop 分出,合回 main 与 develop
hotfix/*线上紧急修复,从 main 分出,合回 main 与 develop

适合有明确版本发布周期的项目。

15.4 GitHub Flow

main 始终可部署;任何改动都从 main 开分支,通过 PR 合并后立即部署。简单,适合持续交付。

15.5 Trunk-Based Development

所有人频繁(每天多次)向主干合并短生命周期的小分支,配合功能开关与自动化测试。适合成熟的 CI/CD 团队。

15.6 好的提交习惯

  • 每次提交只做一件事,保持原子性
  • 提交说明写清楚"做了什么和为什么"
  • 提交前用 git diff --staged 自检
  • 不要提交密钥、密码、大型二进制文件、构建产物
  • 频繁提交、频繁同步,减少大规模冲突
  • 在推送之前整理本地历史(rebase -i),推送之后不要改写

16. 常见问题与排错

16.1 提交到了错误的分支

# 假设在 main 上误提交了,想放到 feature 分支
git switch -c feature          # 在当前位置创建新分支(带上这个提交)
git switch main
git reset --hard HEAD~1        # 把 main 回退一个提交

16.2 修改最后一次提交的说明

git commit --amend -m "新的说明"

16.3 漏掉了文件,想追加到上一次提交

git add forgotten.txt
git commit --amend --no-edit

16.4 不小心 reset --hard 了

git reflog
git reset --hard <reflog 中的目标哈希>

16.5 推送被拒绝:non-fast-forward / rejected

原因:远程有你本地没有的新提交。

git pull --rebase
git push

仅当你确认要覆盖远程(例如刚变基过自己的私有分支):

git push --force-with-lease

16.6 fatal: refusing to merge unrelated histories

两个仓库没有共同祖先,例如把本地新仓库与已有内容的远程仓库对接:

git pull origin main --allow-unrelated-histories

16.7 处于分离头指针(detached HEAD)状态

# 如果在这个状态下做了想保留的提交
git switch -c my-new-branch

# 如果只是想回到分支
git switch main

16.8 误提交了敏感信息

  1. 立即作废并更换泄露的密钥/密码(这是最重要的一步)
  2. 使用 git filter-repo 从历史中清除
  3. 强制推送,并通知协作者重新克隆

16.9 中文文件名显示为乱码转义

git config --global core.quotepath false

16.10 HTTPS 每次都要输入密码

# 使用凭据助手缓存
git config --global credential.helper cache      # 内存缓存(默认 15 分钟)
git config --global credential.helper store      # 明文保存到磁盘(不推荐)
git config --global credential.helper manager    # Windows / macOS 系统凭据管理器

或改用 SSH,或使用个人访问令牌(Personal Access Token)。

16.11 克隆或拉取太慢

git clone --depth 1 <url>            # 浅克隆
git fetch --unshallow                # 之后补全历史
git config --global http.postBuffer 524288000   # 大仓库时调大缓冲区

16.12 大小写重命名在 Windows / macOS 上不生效

git mv --force File.txt file.txt
# 或
git config core.ignorecase false

16.13 撤销一次合并

# 合并尚未提交(有冲突时)
git merge --abort

# 合并已提交但尚未推送
git reset --hard ORIG_HEAD

# 合并已推送
git revert -m 1 <合并提交哈希>

17. 命令速查表

配置与初始化

命令作用
git config --global user.name "名字"设置用户名
git config --global user.email "邮箱"设置邮箱
git init初始化仓库
git clone <url>克隆仓库

日常操作

命令作用
git status查看状态
git add <文件> / git add .暂存
git commit -m "说明"提交
git diff / git diff --staged查看差异
git log --oneline --graph --all查看历史
git rm <文件> / git mv <旧> <新>删除 / 重命名

分支与合并

命令作用
git branch列出分支
git switch <分支>切换分支
git switch -c <分支>创建并切换
git branch -d <分支>删除分支
git merge <分支>合并
git rebase <分支>变基
git rebase -i HEAD~n交互式整理最近 n 个提交
git cherry-pick <提交>摘取提交

远程协作

命令作用
git remote -v查看远程
git fetch获取更新
git pull / git pull --rebase拉取并合并 / 变基
git push / git push -u origin <分支>推送
git push --force-with-lease安全强制推送

撤销与恢复

命令作用
git restore <文件>丢弃工作区修改
git restore --staged <文件>取消暂存
git commit --amend修改上次提交
git reset --soft/--mixed/--hard <提交>回退
git revert <提交>反向提交
git reflog查看指针移动历史,找回丢失提交
git stash / git stash pop暂存 / 恢复工作进度
git clean -fd删除未跟踪文件

标签与其他

命令作用
git tag -a v1.0 -m "说明"创建附注标签
git push origin --tags推送标签
git bisect二分定位缺陷
git blame <文件>逐行追溯
git worktree add <路径> <分支>多工作目录

延伸学习

学习建议:先掌握 add / commit / log / diff / branch / merge / push / pull 这条主线,再逐步学习 rebase、stash、reflog 等进阶命令。遇到问题时,先用 git status 看清现状,再决定下一步,并善用 git reflog 这张后悔药。