版本控制与协作 / 知识点
Git 命令速查手册
手册条目
git --version
git version确认当前环境安装的 Git 版本及命令是否可用。
查看 Git 版本
安装、升级 Git 后先用这一条确认当前终端实际调用的 Git 版本;如果版本与预期不一致,再继续定位命中的可执行文件。
基本用法
git --version预期输出:
git version <VERSION><VERSION> 由当前安装版本决定。能正常返回 git version 和版本号,说明 Git 命令已可执行。
确认可执行文件
在 macOS、Linux 或 Git Bash 中查看当前 PATH 首先命中的 Git:
command -v git预期输出:
<PATH>/git实际路径可能是系统目录、Homebrew 目录或 Git for Windows 的安装目录。PowerShell 可使用 Get-Command git 查询同类信息。
排查多个 Git
升级后仍显示旧版本时,列出 Shell 能找到的全部同名命令:
type -a git预期输出示例:
git is <PATH_1>/git
git is <PATH_2>/git多条结果说明机器上存在多个 Git,Shell 会按 PATH 顺序选择。优先调整 PATH,不要直接删除系统自带 Git。
风险与兼容性
git --version 是只读检查,可在常见 Git 环境中安全执行。command -v 和 type -a 属于类 Unix Shell 命令,不适用于 Windows 命令提示符;跨平台脚本应分别处理 Shell 差异。
git help <command>
git <command> -h查询指定 Git 命令的参数、语法和使用说明。
查看命令帮助
使用 git help 或命令的 -h 参数查询语法、选项和使用说明。忘记参数时优先查看本机帮助,因为内容与当前安装的 Git 版本一致。
基本语法
git help <command>
git <command> -hgit help <command> 提供完整手册,通常通过分页器打开;git <command> -h 直接在终端显示精简语法,适合快速查参数。
查看精简帮助
以下命令快速查看 commit 的用法和常用选项:
git commit -h预期输出节选:
usage: git commit [<options>] [--] <pathspec>...
or: git commit [<options>] [--] <pathspec-from-file>...
-q, --quiet suppress summary after successful commit
-v, --verbose show diff in commit message template
-m, --message <message>
commit message不同 Git 版本的选项顺序和文字可能略有差异。读取时先看 usage 确认参数位置,再按选项名称查说明。
查看完整手册
git help commit预期结果:
打开 git-commit 的完整帮助文档;终端环境通常进入 less 分页器。在 less 中按 / 后输入关键词搜索,例如 /--amend;按 n 查找下一处,按 q 退出。如果系统配置了图形化或网页帮助,显示方式可能不同。
查询所有 Git 命令
git help -a预期输出节选:
Main Porcelain Commands
add Add file contents to the index
branch List, create, or delete branches
commit Record changes to the repository
status Show the working tree status该输出适合确认命令名称。若只知道功能关键词,可结合终端搜索,例如 git help -a | grep branch。
风险与边界
不要直接复制不理解的危险选项,例如 reset --hard、clean -fd 或强制推送参数。这些选项可能覆盖提交、删除未跟踪文件或改写远程历史。执行前先用 -h 查看边界,并优先使用 git status、git diff 或不修改数据的预览参数确认影响范围。
排障清单
执行 git help <command> 后提示没有手册查看器时,通常是系统缺少 man 或分页器。可改用精简帮助:
git <command> -h预期结果:
终端直接显示该命令的 usage 和选项列表,不依赖 man 手册查看器。<command> 必须替换为真实命令,例如 clone、log 或 rebase,尖括号本身不要输入。
git config [--global] user.name "<用户名>"
git config [--global] user.email "<邮箱>"设置提交记录使用的用户名和邮箱地址。
配置 Git 提交身份
设置 user.name 和 user.email,让后续提交写入正确的作者与提交者信息。个人电脑通常配置全局身份;同一台电脑同时处理公司与个人仓库时,应在仓库内覆盖。
命令定位
git config 用于读取和写入 Git 配置。身份相关键为 user.name 与 user.email,它们会进入新提交的元数据,不负责登录远程仓库,也不会修改已经存在的提交。
高频用法
为当前操作系统用户设置默认身份,并立即读取验证:
git config --global user.name "Alice Chen"
git config --global user.email "alice@example.com"
git config --global --get user.name
git config --global --get user.email预期输出
Alice Chen
alice@example.com只为当前仓库设置另一套身份。先进入目标仓库;不写 --global 时,默认写入该仓库的 .git/config:
cd <PATH>
git config user.name "Alice Work"
git config user.email "alice@company.example"
git config --get-regexp '^user\.(name|email)$'预期输出
user.name Alice Work
user.email alice@company.example<PATH> 替换为仓库目录。仓库级配置优先于全局配置,因此不会影响其他仓库。
作用范围
| 范围 | 写法 | 典型位置 | 适用场景 |
|---|---|---|---|
| 系统级 | --system |
系统 Git 配置文件 | 管理员统一设置整台机器 |
| 全局级 | --global |
用户主目录下的 Git 配置 | 当前用户的默认身份 |
| 仓库级 | --local 或省略范围 |
.git/config |
单个仓库覆盖默认身份 |
生效优先级通常是仓库级高于全局级,全局级高于系统级。
风险与边界
邮箱会保存在提交对象中,推送到公开仓库后可能被长期公开。触发条件是使用真实邮箱创建并推送提交;后果是邮箱暴露。安全替代方案是使用代码托管平台提供的隐私邮箱,并在提交前核对最新提交的作者与提交者信息。
修改配置只影响之后创建的提交,不会自动修正历史记录。若错误身份已经推送,重写历史可能改变提交哈希并影响协作者;优先保留历史,确需修正时先与团队确认。
不要使用 sudo git config --global ...。这会把配置写入 root 用户环境,普通用户仍读不到,还可能造成文件属主异常。
排障清单
身份仍不正确时,查看最终生效值及其来源:
git config --show-origin --get-regexp '^user\.(name|email)$'预期输出
file:<PATH>/.gitconfig user.name Alice Chen
file:.git/config user.email alice@company.example实际路径可能不同。若同时出现多层配置,以仓库级结果为准;若没有输出,说明对应键尚未配置。
git config --list --show-origin --show-scope
git config [--system|--global|--local] --get <配置项>检查系统级、全局或仓库级 Git 配置及来源。
查看 Git 配置
检查 Git 当前读取了哪些配置、配置来自哪个文件,以及系统级、全局级和仓库级设置谁最终生效。排查代理、换行符、默认分支或用户身份异常时优先使用。
查看全部配置及来源
在目标仓库中执行:
git config --list --show-origin --show-scope预期输出
global file:<PATH>/.gitconfig user.name=Alice Chen
global file:<PATH>/.gitconfig user.email=alice@example.com
local file:.git/config core.repositoryformatversion=0
local file:.git/config remote.origin.url=https://example.com/team/repo.git<PATH> 和仓库地址会因环境而异。每行依次显示作用域、来源文件和 键=值;同一个键出现多次时,层级更高或读取顺序更后的值可能覆盖前值。
查看单个键
读取当前上下文最终生效的邮箱:
git config --get user.email预期输出
alice@example.com只检查某一层时显式指定范围:
git config --global --get user.email
git config --local --get remote.origin.url预期输出
alice@example.com
https://example.com/team/repo.git某层未配置该键时,命令通常不输出内容并返回退出码 1,不代表 Git 程序损坏。
按模式筛选
一次查看一组相关配置,适合检查用户身份、代理或远程仓库设置:
git config --show-origin --get-regexp '^(user\.|http\.proxy$|remote\.)'预期输出
file:<PATH>/.gitconfig user.name Alice Chen
file:<PATH>/.gitconfig user.email alice@example.com
file:.git/config remote.origin.url https://example.com/team/repo.git
file:.git/config remote.origin.fetch +refs/heads/*:refs/remotes/origin/*正则没有匹配项时同样可能无输出并返回退出码 1。
输出字段说明
--list 列出当前可见配置;--show-origin 增加来源文件;--show-scope 增加 system、global、local、worktree 或 command 等作用域。命令行通过 git -c key=value ... 临时传入的配置通常显示为 command,只对该次 Git 调用生效。
风险与边界
配置输出可能包含代理账号、带凭据的远程 URL、签名配置或内部地址。触发条件是直接复制完整输出到工单或公开聊天;后果是凭据和网络信息泄露。安全替代方案是只查询目标键,或在分享前遮盖用户名、令牌、主机名和路径。
不要通过手工删除重复行来猜测最终值。先用 --show-origin --show-scope 定位来源,再编辑对应层;错误修改系统级配置可能影响整台机器上的所有用户和仓库。
排障清单
若结果与预期不一致,依次确认当前目录是否位于目标仓库、是否存在仓库级覆盖、环境变量是否指定了其他配置文件,以及命令是否带有临时 -c 参数。可先检查仓库根目录:
git rev-parse --show-toplevel预期输出
<PATH>若提示 fatal: not a git repository,先进入正确仓库再检查本地配置。较旧版本 Git 可能不支持 --show-scope,可去掉该选项后重新查看来源。
git config [--local|--global] alias.<别名> '<原命令>'为常用 Git 命令配置简短且易记的别名。
设置 Git 命令别名
为高频 Git 子命令配置短名称,适合减少重复输入。别名由 git config 管理,可只对当前仓库生效,也可对当前用户的所有仓库生效。
基本语法
git config [--local|--global] alias.<别名> '<原命令>'--local 是默认范围,配置写入当前仓库的 .git/config;--global 写入用户级配置,通常位于 ~/.gitconfig。
高频用法
配置两个用户级别名,并立即读取确认:
git config --global alias.st status
git config --global alias.last 'log -1 --oneline'
git config --global --get alias.st
git config --global --get alias.last预期输出
status
log -1 --oneline之后可直接执行 git st 查看状态,或执行 git last 查看最近一次提交。
查看全部已配置别名:
git config --global --get-regexp '^alias\.'预期输出示例
alias.st status
alias.last log -1 --oneline实际输出还会包含已有别名,顺序可能不同。
修改与删除
重复设置同名别名会覆盖原值。删除不再使用的别名:
git config --global --unset alias.st
git config --global --get alias.st预期结果
第二条命令无输出,并返回非 0 状态码。风险与边界
设置同名别名时,旧定义会被直接替换,可能导致团队脚本或个人习惯失效。修改前先执行 git config --global --get alias.<别名> 检查;共享脚本中优先使用完整 Git 命令,不依赖个人别名。
以 ! 开头的别名会交给 Shell 执行,错误的变量引用或删除命令可能影响工作区文件。仅在确认命令内容后使用,并先在测试仓库运行。
速查:常用别名放在 --global,项目专用别名使用 --local。
git init [目录]
git init -b <初始分支名> [目录]在当前目录创建一个新的本地 Git 仓库。
初始化 Git 仓库
在现有目录或新目录中创建 .git 元数据目录,使该目录可以开始跟踪文件、提交版本和配置远程仓库。初始化不会自动提交现有文件。
基本语法
git init [目录]
git init -b <初始分支名> [目录]不指定目录时初始化当前目录;指定目录时,Git 会创建目录并在其中初始化仓库。
高频用法
创建新目录并以 main 作为初始分支:
mkdir demo-repo
cd demo-repo
git init -b main
git status --short --branch预期输出
Initialized empty Git repository in <PATH>/demo-repo/.git/
## No commits yet on main<PATH> 会随当前工作目录变化。No commits yet 表示仓库已创建,但尚未生成首个提交。
在已有项目目录中初始化并完成首个提交:
cd <PATH>
git init -b main
git add .
git commit -m 'Initial commit'预期结果
[main (root-commit) <ID>] Initial commit
<N> files changed, <N> insertions(+)<ID>、文件数和插入行数由实际内容决定。提交前必须已配置 user.name 和 user.email。
验证仓库
git rev-parse --is-inside-work-tree
git rev-parse --show-toplevel预期输出
true
<PATH>第一行确认当前目录位于工作树中,第二行显示仓库根目录。
风险与边界
在错误目录执行 git init 会把上层项目、临时文件或敏感文件纳入待跟踪范围。执行前先用 pwd 和 ls 确认位置;初始化后先编写 .gitignore,再运行 git add .。
对已存在的仓库再次执行 git init 通常只会重新初始化,不会删除提交,但可能更新模板或配置。不要通过手工删除 .git 来“重置仓库”,否则会永久丢失本地历史;需要清理工作区时优先备份或使用新的目录。
兼容性
Git 2.28 及以上支持 git init -b main。旧版本可执行 git init,再用 git symbolic-ref HEAD refs/heads/main 设置未提交分支名。
git clone <仓库地址> [本地目录]将远程仓库及其提交历史下载到本地。
克隆远程仓库
用于首次获取远程项目。执行后会下载仓库提交历史、检出默认分支,并自动将远程仓库配置为 origin。
基本语法
git clone <仓库地址> [本地目录]
省略本地目录时,Git 默认使用仓库名称创建目录。仓库地址可以是 HTTPS、SSH 或本地文件路径。
高频用法
下面将公开仓库克隆到 hello-world,随后验证工作区和远程地址:
git clone https://github.com/octocat/Hello-World.git hello-world
git -C hello-world rev-parse --is-inside-work-tree
git -C hello-world remote get-url origin预期输出(实际克隆进度行可能更多):
Cloning into 'hello-world'...
true
https://github.com/octocat/Hello-World.gittrue 表示目录是有效 Git 工作区;最后一行确认 origin 指向预期仓库。
常用参数
| 参数 | 适用场景 |
|---|---|
--depth 1 |
只下载最新一层历史,适合构建、临时检查和大型仓库 |
--recurse-submodules |
克隆主仓库后继续初始化并下载子模块 |
--no-checkout |
只下载对象和引用,暂不生成工作区文件 |
--filter=blob:none |
延迟下载文件内容,适合支持部分克隆的超大型仓库 |
风险与边界
- 目标目录已经存在且非空时,克隆会失败。不要直接删除目录,先确认其中没有未备份文件,或改用新的目录名。
- 普通克隆会下载可达的完整历史,大型仓库可能占用大量时间和磁盘。只需最新代码时优先使用
--depth 1。 - 不要把访问令牌直接写入 HTTPS URL,否则可能进入终端历史、日志或进程参数。应使用 SSH 密钥或 Git Credential Helper。
git clone默认不会递归下载子模块;项目依赖子模块时应增加--recurse-submodules。
排障清单
- 出现
Repository not found:检查仓库地址、大小写和当前账号权限。 - 出现认证失败:确认 SSH 公钥已添加,或重新配置 HTTPS 凭据。
- 下载中断:删除未完成的目标目录后重试,避免在残缺目录中直接执行
git pull。 - 连接超时:检查代理、DNS、防火墙以及到 Git 服务端的 22 或 443 端口。
兼容性
--depth 和 --recurse-submodules 可用于常见 Git 2.x 环境;--filter=blob:none 需要客户端与服务端共同支持部分克隆。
速查提示:先确认仓库地址和目标目录,再根据历史、子模块和磁盘需求选择克隆参数。
git clone --branch <分支名> --single-branch <仓库地址> [本地目录]只检出远程仓库中的指定分支。
克隆指定分支
用于首次下载仓库时直接检出目标分支。需要限制只获取该分支时,应同时使用 --branch 和 --single-branch。
基本语法
git clone --branch <分支名> --single-branch <仓库地址> [本地目录]
--branch 可简写为 -b。只使用 --branch 会改变初始检出分支,但通常仍会获取其他远程分支的引用。
高频用法
下面只克隆 master 分支,并通过 --depth 1 仅保留最新一层历史:
git clone --branch master --single-branch --depth 1 https://github.com/git/git.git git-master
git -C git-master branch --show-current
git -C git-master config --get-all remote.origin.fetch预期输出(实际克隆进度行可能更多):
Cloning into 'git-master'...
master
+refs/heads/master:refs/remotes/origin/master第二行表示当前检出的是 master;最后一行的 fetch 规则只包含该分支,说明没有配置获取其他远程分支。
常用组合
| 目标 | 参数组合 |
|---|---|
| 只获取一个分支的完整历史 | --branch <分支名> --single-branch |
| 只获取一个分支的最新提交 | --branch <分支名> --single-branch --depth 1 |
| 下载后暂不检出文件 | --branch <分支名> --single-branch --no-checkout |
| 克隆前确认分支存在 | git ls-remote --exit-code --heads <仓库地址> <分支名> |
风险与边界
- 省略
--single-branch时,只是工作区检出指定分支,并不等于只下载该分支。仓库较大时会产生额外网络和磁盘开销。 - 浅克隆缺少早期提交,
git log、git blame、合并基线和版本计算可能不完整。需要完整历史时执行git fetch --unshallow。 --branch也接受标签名;克隆标签后通常处于 detached HEAD。需要继续开发时应新建分支,而不是直接在游离提交上工作。- 分支名称区分大小写。写错名称会导致克隆终止,不会自动选择相似分支。
排障清单
- 出现
Remote branch <分支名> not found:使用git ls-remote --heads <仓库地址>查看真实分支名称。 - 克隆成功但发现其他远程分支:检查是否遗漏
--single-branch,并查看remote.origin.fetch配置。 - 浅克隆无法切换到旧提交:执行
git fetch --deepen <数量>扩展历史,或使用git fetch --unshallow获取完整历史。 - 目标目录已存在且非空:更换目录名,或在确认数据可丢弃后清理目录再重试。
兼容性
常见 Git 2.x 版本均支持 --branch、--single-branch 和 --depth。--depth 通常会隐含单分支获取,但显式写出 --single-branch 更便于审查命令意图。
速查提示:只指定初始分支用 --branch;同时限制下载范围时再加 --single-branch。
git clone --depth <深度> <仓库地址> [本地目录]仅下载有限深度的提交历史以减少传输量。
浅克隆仓库
只需要最新代码、临时构建或快速检查时,用 git clone --depth 限制下载的提交历史。这样能减少网络传输和磁盘占用,但仓库不会包含完整祖先记录。
基本语法
git clone --depth <深度> <仓库地址> [本地目录]预期结果
Cloning into '<本地目录>'...
remote: Enumerating objects: <COUNT>, done.
Receiving objects: 100% (<COUNT>/<COUNT>), done.--depth 1 只保留目标分支最近一次提交;指定更大的深度可保留更多提交。--depth 默认同时限制为单分支历史,确需多个远程分支时增加 --no-single-branch。
高频用法
仅获取默认分支最新提交:
git clone --depth 1 https://github.com/git/git.git git-src预期输出
Cloning into 'git-src'...
remote: Enumerating objects: <COUNT>, done.
Receiving objects: 100% (<COUNT>/<COUNT>), done.验证仓库是否为浅克隆,并查看当前可见历史:
cd git-src
git rev-parse --is-shallow-repository
git log --oneline -3预期输出
true
<COMMIT> <LATEST_COMMIT_MESSAGE>需要更多历史时,按 50 个提交逐步加深:
git fetch --deepen 50
git log --oneline -3预期结果
<COMMIT_1> <LATEST_COMMIT_MESSAGE>
<COMMIT_2> <OLDER_COMMIT_MESSAGE>
<COMMIT_3> <OLDER_COMMIT_MESSAGE>需要恢复完整历史时执行:
git fetch --unshallow
git rev-parse --is-shallow-repository预期输出
false常用参数
--branch <名称>:克隆指定分支或标签。--single-branch:只下载目标分支历史;使用--depth时通常已隐含生效。--no-single-branch:浅克隆所有远程分支在指定深度内的历史。--recurse-submodules --shallow-submodules:同时浅克隆子模块。
风险与边界
浅克隆缺少较早提交,执行 git blame、跨历史比较、基于完整标签计算版本号或查找合并基础时可能得到不完整结果,部分发布脚本也会直接失败。需要这些操作时,先用 git fetch --deepen <N> 补充历史;仍无法确定所需深度时,使用 git fetch --unshallow 转为完整仓库。
在 CI 中只构建当前提交通常适合 --depth 1;若流水线需要标签、变更范围或多分支比较,不要盲目使用最小深度。
git status
git status --short --branch检查工作区、暂存区及未跟踪文件的当前状态。
查看仓库状态
在提交、切换分支或排查“文件为什么没有进入提交”时,使用 git status 同时检查工作区、暂存区、未跟踪文件以及本地分支与上游分支的关系。
基本语法
git status
git status --short --branch预期输出
## main...origin/main
M src/app.py
M README.md
?? debug.log实际分支名和文件名会不同。普通格式适合人工阅读;--short --branch 适合快速扫描,第一行显示分支关系,其余行显示文件状态。
输出字段说明
短格式每行前两列为 XY 状态码:X 表示暂存区相对上次提交的变化,Y 表示工作区相对暂存区的变化。
| 状态 | 含义 |
|---|---|
M file |
工作区已修改,尚未暂存 |
M file |
修改已暂存 |
MM file |
已暂存后又继续修改 |
A file |
新文件已暂存 |
?? file |
未跟踪文件 |
D、R、UU |
删除、重命名、合并冲突 |
高频用法
查看完整状态和 Git 给出的下一步提示:
git status预期输出
On branch main
Changes not staged for commit:
modified: src/app.py
Untracked files:
debug.log提交前快速确认暂存区与工作区:
git status --short --branch预期输出
## main...origin/main [ahead 1]
M README.md
M src/app.py
?? debug.log脚本中获取稳定、易解析的状态输出:
git status --porcelain=v1预期输出
M README.md
M src/app.py
?? debug.log--porcelain=v1 不使用面向用户的本地化描述,适合脚本判断;命令无输出表示工作区和暂存区均干净。
风险与边界
git status 本身不会修改文件,但在超大仓库或包含大量未跟踪文件时,扫描可能较慢。git status -uno 可以跳过未跟踪文件以加快检查,但会隐藏尚未纳入版本控制的新文件,提交前应再执行一次不带 -uno 的完整检查。
状态显示“干净”只代表已跟踪内容没有待提交变化,不代表本地分支已经推送。检查 ## 行中的 ahead、behind,或执行 git status --branch 确认与上游分支的差异。
排障清单
- 文件未出现:检查是否被
.gitignore、全局忽略文件或.git/info/exclude排除。 - 修改已暂存但仍显示变化:出现
MM时,说明暂存后又编辑过文件,需要重新git add。 - 出现
UU:合并冲突尚未解决;编辑冲突文件后执行git add <文件>标记已解决。 - 不在仓库中:出现
fatal: not a git repository时,先切换到包含.git的目录。
git log [<选项>] [<提交范围>] [--] [<路径>]按时间查看仓库已有的提交记录。
查看提交历史
用于按时间倒序检查当前分支可达的提交,快速确认提交顺序、作者、时间、说明以及某个文件的修改轨迹。git log 只读取仓库对象,不会改动工作区或提交记录。
基本语法
git log [<选项>] [<提交范围>] [--] [<路径>]提交范围用于限定起点和终点;-- 用来明确分隔提交参数与文件路径,路径可能与分支名同名时尤其重要。
高频用法
查看最近 10 条提交,并显示分支、标签和 HEAD:
git log --oneline --decorate -n 10预期输出:
<COMMIT_A> (HEAD -> main, tag: v1.4.0) fix: 修复支付回调重复处理
<COMMIT_B> feat: 增加退款状态查询
<COMMIT_C> refactor: 拆分订单服务每行开头是缩写提交哈希;括号内是指向该提交的分支、标签或 HEAD;其后是提交说明。实际哈希和引用名称会不同。
查看某个文件的历史,并尝试跨重命名继续追踪:
git log --oneline --follow -- src/main/java/com/example/OrderService.java预期输出:
<COMMIT_D> refactor: 重命名订单服务
<COMMIT_E> fix: 修复订单状态更新
<COMMIT_F> feat: 新增订单服务--follow 仅适合单个路径,且重命名判断依赖内容相似度;复杂拆分或合并文件时可能无法完整追踪。
查看两个版本之间新增的提交:
git log --oneline v1.3.0..v1.4.0预期输出:
<COMMIT_G> fix: 修复签名校验
<COMMIT_H> feat: 支持新支付方式A..B 表示“能从 B 到达、但不能从 A 到达”的提交,不是简单按时间截取。
常用参数
--oneline:每个提交压缩为一行,适合快速浏览。--decorate:显示分支、标签和HEAD指向。-n <数量>:限制输出条数,避免大仓库刷屏。--author=<关键字>:按作者姓名或邮箱过滤。--since="2026-08-01"、--until="2026-08-02":按提交时间过滤。-p:展开补丁内容,适合审查具体改动,但输出可能很大。--stat:只显示各文件增删统计,比-p更适合概览。
输出读取
默认完整输出包含 commit、Author、Date 和提交说明。提交哈希可继续用于 git show <COMMIT>、git diff <A>..<B> 或回退定位;日期默认受本机时区和 Git 配置影响,跨环境核对时可加 --date=iso-strict。
风险与边界
git log 本身无写入风险,但在大型仓库执行 git log -p --all 会读取大量对象,可能导致终端长时间占用。先用 -n、路径或提交范围缩小结果,再按需增加 -p。
当前本地没有远程分支最新引用时,--all 也看不到尚未抓取的提交。安全做法是先执行 git fetch --all --prune,确认只更新远程引用后再查询。
排障清单
- 输出进入分页器后按
q退出;临时禁用分页可用git --no-pager log ...。 - 提示“ambiguous argument”时,检查分支、标签或路径是否存在;路径参数前加
--。 - 看不到远程最新提交时,先执行
git fetch --all --prune。 - 仓库没有提交时会提示当前分支尚无提交,此时先用
git status确认仓库状态。
git log --graph [<选项>] [<提交范围>] [--] [<路径>...]以分支拓扑图形式查看提交、合并和标签关系。
图形化查看 Git 历史
需要同时看提交节点、分支分叉、合并线、标签和 HEAD 指向时使用 git log --graph。它只改变日志展示,不会修改提交、分支或工作区。
基本语法
git log --graph [<选项>] [<提交范围>] [--] [<路径>...]关键选项只保留会明显改变阅读结果的几项:
| 选项 | 作用 |
|---|---|
--oneline |
每个提交压缩为一行 |
--decorate |
显示分支、标签和 HEAD |
--all |
遍历更多本地与远程跟踪引用 |
--date-order |
兼顾时间顺序,并避免父提交出现在子提交之前 |
--topo-order |
更强调分支拓扑连续性 |
--first-parent |
只沿合并提交的第一父提交查看主线 |
高频用法
查看仓库中主要引用的整体拓扑:
git log --graph --oneline --decorate --all --date-order预期输出:
* <COMMIT_A> (HEAD -> main) merge: 合并 feature/login
|\
| * <COMMIT_B> (feature/login) feat: 增加登录校验
* | <COMMIT_C> fix: 修复首页异常
|/
* <COMMIT_D> (tag: v1.0.0) feat: 初始版本<COMMIT_A> 等位置会显示真实的缩写提交哈希。

读取拓扑
* 表示提交节点,| 表示历史链继续,/ 与 \ 表示分叉或汇合。(HEAD -> main) 表示当前检出分支,(tag: v1.0.0) 表示标签指向该提交。
图中连线表达的是提交父子关系,不等同于“代码部署流向”,也不能证明某个提交已经发布到生产环境;部署状态仍要结合 CI/CD 或发布记录判断。
缩小查看范围
历史太多时,不要一开始就展开全部引用。先限制条数或明确指定分支:
git log --graph --oneline --decorate -n 20预期输出:
* <COMMIT_E> (HEAD -> main) fix: 修复配置加载
* <COMMIT_F> feat: 增加健康检查
* <COMMIT_G> chore: 初始化项目只看两个分支可用 git log --graph --oneline --decorate main feature/login;只看主线合并可增加 --first-parent main;复杂历史中想让拓扑更连续可把 --date-order 换成 --topo-order。
风险与排障
git log --graph 是只读命令,但 --all 在大型仓库中可能产生很宽、很长的输出。优先通过 -n <数量>、提交范围或指定分支缩小遍历范围。
远程新分支未出现时,先执行 git fetch --all --prune 更新远程跟踪引用;如果终端字符错位,使用等宽字体并可增加 --no-color 排除颜色控制字符影响。
git show <COMMIT>查看某次提交修改的文件、内容及元数据。
查看提交详情
用于检查某次提交的作者、时间、提交说明、变更文件和补丁内容。默认使用 git show,它不会修改仓库。
基本语法
git show <COMMIT>预期输出:
commit <COMMIT>
Author: <AUTHOR>
Date: <TIME>
<COMMIT_MESSAGE>
diff --git a/<PATH> b/<PATH>
index <OLD>..<NEW> <MODE>
--- a/<PATH>
+++ b/<PATH>
@@ -<OLD_RANGE> +<NEW_RANGE> @@
-<OLD_LINE>
+<NEW_LINE><COMMIT> 可使用完整哈希、短哈希、标签、分支名或 HEAD~1。实际作者、时间、路径和补丁内容随提交变化。
常用参数
--stat:只看各文件增删行统计。--name-only:只列出变更文件路径。--name-status:列出路径及状态,常见状态为A、M、D、R。--no-patch:只显示提交元数据,不显示补丁。--format=fuller:同时显示作者与提交者信息。-- <PATH>:只查看指定文件或目录在该提交中的变化。
高频用法
快速查看最新提交及文件统计:
git show --stat --oneline HEAD预期输出:
<SHORT_COMMIT> <COMMIT_MESSAGE>
<PATH_1> | <N> +++++---
<PATH_2> | <N> ++
<N> files changed, <N> insertions(+), <N> deletions(-)只查看某个文件在指定提交中的补丁:
git show <COMMIT> -- <PATH>预期输出:
commit <COMMIT>
Author: <AUTHOR>
Date: <TIME>
<COMMIT_MESSAGE>
diff --git a/<PATH> b/<PATH>
...只核对提交元数据,不展开代码差异:
git show --no-patch --format=fuller <COMMIT>预期输出:
commit <COMMIT>
Author: <AUTHOR>
AuthorDate: <TIME>
Commit: <COMMITTER>
CommitDate: <TIME>
<COMMIT_MESSAGE>输出读取
commit 是提交对象 ID;Author 表示原始作者;Date 是作者时间。补丁中以 - 开头的是删除行,以 + 开头的是新增行,@@ 标记变更所在的旧、新行号范围。
风险与排障
git show 是只读命令,但大型提交或二进制文件可能产生大量输出。先用 --stat、--name-only 或路径限制缩小范围,避免终端卡顿。
出现 fatal: ambiguous argument 时,提交引用不存在或与路径重名。先执行以下命令确认引用,再用 -- 分隔提交和路径:
git rev-parse --verify <COMMIT>
git show <COMMIT> -- <PATH>预期结果:
<FULL_COMMIT_HASH>
commit <COMMIT>
Author: <AUTHOR>
Date: <TIME>
<COMMIT_MESSAGE>
diff --git a/<PATH> b/<PATH>
...若第一条命令报错,先执行 git log --oneline --all 查找正确提交;远程提交尚未拉取时先执行 git fetch。
git diff比较工作区内容与暂存区之间的变化。
查看未暂存差异
用于比较工作区与暂存区,确认已修改但尚未执行 git add 的内容。git diff 是只读命令,不会改动文件。
基本语法
git diff预期输出:
diff --git a/<PATH> b/<PATH>
index <OLD>..<NEW> <MODE>
--- a/<PATH>
+++ b/<PATH>
@@ -<OLD_RANGE> +<NEW_RANGE> @@
-<OLD_LINE>
+<NEW_LINE>没有输出通常表示不存在未暂存差异;也可能只有已暂存修改或未跟踪文件。
常用参数
--stat:显示文件级增删统计,不展开补丁。--name-only:只输出发生变化的文件路径。--name-status:输出文件状态和路径。--word-diff:按单词显示文本变化,适合文档或长行配置。--check:检查尾随空格等空白错误。-- <PATH>:只比较指定文件或目录。
高频用法
查看全部未暂存补丁:
git diff预期输出:
diff --git a/<PATH> b/<PATH>
...
-<OLD_LINE>
+<NEW_LINE>只检查某个文件:
git diff -- <PATH>预期输出:
diff --git a/<PATH> b/<PATH>
...快速确认改动范围:
git diff --stat预期输出:
<PATH_1> | <N> +++++---
<PATH_2> | <N> ++
<N> files changed, <N> insertions(+), <N> deletions(-)提交前检查空白问题:
git diff --check预期结果:
无输出表示未发现空白错误;若存在问题,会显示 <PATH>:<LINE>: trailing whitespace. 等位置。
输出读取
--- 表示修改前内容,+++ 表示工作区内容。以 - 开头的是暂存区中存在、工作区中删除或替换的行;以 + 开头的是工作区新增行。@@ 后的两组范围分别对应修改前和修改后位置。
风险与边界
git diff 默认不显示已执行 git add 的修改,也不显示未跟踪文件内容。查看已暂存差异使用 git diff --cached;查看未跟踪文件先用 git status --short,确认后再决定是否加入版本控制。
大型生成文件会使补丁过长。优先使用 --stat、--name-only 或路径限制;不要用输出为空直接判断工作区完全干净。
排障清单
当 git diff 无输出但 git status 仍显示变化时,执行:
git status --short
git diff --cached
git ls-files --others --exclude-standard预期输出:
M <STAGED_PATH>
?? <UNTRACKED_PATH>首列状态表示已暂存修改,?? 表示未跟踪文件。实际可能只出现其中一种;若三条命令均无输出,工作区通常已干净。
git diff --cached [--stat] [--] [<路径>]比较暂存区内容与最近一次提交之间的变化。
查看已暂存差异
提交前使用 git diff --cached 检查暂存区与最近一次提交之间的差异,确认下一次提交实际包含哪些修改。--staged 是 --cached 的同义选项。
基本用法
在 Git 仓库中执行:
git diff --cached预期输出会因仓库内容而不同,例如:
diff --git a/app.conf b/app.conf
index <OLD_BLOB>..<NEW_BLOB> 100644
--- a/app.conf
+++ b/app.conf
@@ -1,2 +1,2 @@
-port=8080
+port=9090
mode=prod以 - 开头的是暂存区删除的内容,以 + 开头的是准备加入提交的内容;@@ 行表示变更所在的旧、新文件行号范围。<OLD_BLOB> 和 <NEW_BLOB> 实际会显示为对象哈希缩写。
常用参数
| 参数 | 用途 |
|---|---|
--stat |
只查看各文件的增删行数统计 |
--name-only |
只输出发生变化的文件路径 |
--name-status |
输出文件路径及 A、M、D 等状态 |
--check |
检查行尾空格等空白字符错误 |
-- <路径> |
只检查指定文件或目录 |
常用组合包括 git diff --cached --stat 查看提交规模、git diff --cached --check 做提交前空白检查,以及 git diff --cached -- src/ 只检查 src 目录。路径前的 -- 可以避免文件名被误识别为选项或版本名。
风险与边界
该命令只显示已经通过 git add 放入暂存区的内容,不包含工作区中的未暂存修改,也不显示未跟踪文件。若只检查该输出就提交,可能遗漏仍留在工作区的代码;安全做法是同时执行 git status --short 和 git diff。
二进制文件通常只显示文件发生变化,无法展示逐行差异。大文件产生的补丁过长时,先用 --stat 或 --name-status 确认范围,再针对单个路径查看详细内容。
排障清单
- 没有任何输出:通常表示暂存区与
HEAD相同,执行git status --short确认文件是否尚未git add。 - 输出内容不是预期版本:分别运行
git diff和git diff --cached,区分未暂存修改与已暂存修改。 - 输出停留在分页器:按
q退出,或临时使用git --no-pager diff --cached。 - 只想撤回暂存而保留文件修改:使用
git restore --staged <文件>,不要使用会丢弃工作区内容的恢复命令。
git diff <旧版本> <新版本> [--] [<路径>]
git diff <基准分支>...<目标分支>比较两个提交、分支或标签之间的内容差异。
比较两个版本
使用 git diff <旧版本> <新版本> 比较两个提交、分支或标签指向的文件快照。左侧版本作为基准,输出描述将其变为右侧版本所需的内容变化。
基本用法
仓库至少有两个提交时,可比较最近两次提交并只显示文件状态:
git diff HEAD~1 HEAD --name-status预期输出示例:
M src/config.yml
A src/health-check.sh
D docs/legacy.mdM 表示修改,A 表示新增,D 表示删除;启用重命名检测后还可能出现 R。删除 --name-status 即可查看逐行补丁。
高频用法
| 目标 | 命令 |
|---|---|
| 比较最近两次提交 | git diff HEAD~1 HEAD |
| 比较两个分支当前内容 | git diff main feature/login |
| 查看功能分支从分叉点以来的变化 | git diff main...feature/login |
| 比较两个标签 | git diff v1.2.0 v1.3.0 |
| 只比较指定目录 | git diff v1.2.0 v1.3.0 -- src/ |
版本参数可以是完整提交哈希、哈希缩写、分支名、标签名或 HEAD~N 等相对引用。比较远程分支时通常使用 origin/main 这类远程跟踪引用,并先执行 git fetch 更新本地记录。
双点与三点
在 git diff 中,git diff A..B 与 git diff A B 都是直接比较 A、B 两个版本的文件快照。双点写法在这里不表示提交集合筛选。
git diff A...B 则先寻找 A 与 B 的共同祖先,再将共同祖先与 B 比较,适合查看功能分支相对于分叉位置新增的改动。三点比较具有方向性,交换 A、B 会改变结果。
常用参数
| 参数 | 用途 |
|---|---|
--stat |
查看文件和增删行数汇总 |
--name-only |
只列出发生变化的路径 |
--name-status |
同时显示新增、修改、删除状态 |
--word-diff |
按单词而不是整行显示文本变化 |
-M |
尝试识别文件重命名 |
-- <路径> |
将后续参数明确解释为文件路径 |
风险与边界
交换两个版本的位置会反转新增和删除标记,可能导致评审时误判修改方向。发布前比较应固定使用“旧版本在左、新版本在右”,例如 git diff v1.2.0 v1.3.0。
同时指定两个版本时,命令比较的是版本库中的快照,不包含当前工作区和暂存区的未提交修改。需要检查本地修改时,应另外执行 git diff 和 git diff --cached。
git diff 展示文件内容差异,不展示两个版本之间包含哪些提交。需要查看提交记录时使用 git log A..B --oneline,不要把内容差异与提交列表混为一谈。
排障清单
- 出现
unknown revision:检查分支、标签或哈希是否存在;远程引用缺失时先执行git fetch --all --prune。 - 版本名与文件名冲突:在路径前添加
--,例如git diff HEAD~1 HEAD -- config。 - 结果为空:两个引用可能指向相同文件快照,可用
git rev-parse <版本>检查它们解析到的提交。 - 重命名被显示为删除加新增:添加
-M,但应注意重命名识别基于内容相似度,并非文件系统记录。
git add src/payment/OrderService.java
git status --short将指定文件的当前修改加入暂存区。
暂存文件修改
使用 git add <路径> 将指定文件或目录的当前内容加入暂存区。适合只提交本次确认过的文件,避免把无关修改混入同一个提交。
基本语法
<路径> 可以是单个文件、多个文件或目录,路径相对于当前工作目录解析。命令成功时通常没有终端输出,需要通过 git status 或 git diff --cached 验证。
git add src/payment/OrderService.java
git status --short预期输出:
M src/payment/OrderService.javaM 位于第一列,表示该文件的修改已进入暂存区。实际文件路径可能不同;若命令没有任何输出且退出码为 0,通常表示暂存成功。
高频用法
- 暂存多个指定文件:
git add README.md pom.xml。 - 暂存某个目录下的修改:
git add src/payment/。 - 逐块选择同一文件中的修改:
git add -p src/payment/OrderService.java,适合一个文件同时包含多个逻辑变更。 - 暂存以短横线开头的文件名:
git add -- -example.txt,其中--表示后续内容按路径处理。
检查暂存内容
提交前使用以下命令查看已经加入暂存区的实际差异:
git diff --cached -- src/payment/OrderService.java预期输出:
diff --git a/src/payment/OrderService.java b/src/payment/OrderService.java
index <ID>..<ID> 100644
--- a/src/payment/OrderService.java
+++ b/src/payment/OrderService.java
@@ <RANGE> @@
-<OLD_CONTENT>
+<NEW_CONTENT>以 + 开头的是准备提交的新增内容,以 - 开头的是准备提交的删除内容;<ID>、<RANGE> 和具体代码会随实际修改变化。
风险与边界
git add 保存的是执行命令时的文件快照。暂存后继续编辑文件,新修改不会自动进入暂存区,git status --short 可能显示 MM。提交前应重新执行 git add <路径>,或确认只提交第一次暂存的版本。
路径指定过宽时,例如对大型目录执行 git add src/,可能同时暂存生成文件、调试代码或本地配置。安全做法是先运行 git status --short,再按文件暂存;发现误暂存时使用 git restore --staged <路径>,该操作只移出暂存区,不删除工作区修改。
排障清单
- 出现
pathspec ... did not match any files:检查路径拼写和当前目录,可先执行git status --short确认 Git 识别到的路径。 - 文件没有被暂存:检查是否被
.gitignore排除;只有确认必须纳入版本库时才使用git add -f <路径>。 - 只想提交部分代码:使用
git add -p <路径>,逐块选择y、n或s,不要先暂存整个文件再直接提交。
git add -A
git status --short将新增、修改和删除的文件统一加入暂存区。
暂存全部修改
使用 git add -A 将当前仓库中的新增、修改和删除统一加入暂存区。适合已完成一次完整检查、准备集中提交当前工作树全部变化的场景。
基本语法
-A 与 --all 等价。在现代 Git 中,不论从仓库根目录还是子目录执行,都会处理整个工作树中未被忽略的变化。
git add -A
git status --short预期输出:
M README.md
A src/payment/NewValidator.java
D docs/old-api.md第一列表示暂存区状态:M 是已暂存修改,A 是已暂存新增,D 是已暂存删除。实际路径和条目数量取决于仓库当前状态;git add -A 本身成功时通常不输出内容。
高频用法
- 暂存整个仓库:
git add -A,推荐用于明确要收集全部变化的场景。 - 使用完整参数名:
git add --all,行为与git add -A相同。 - 暂存后检查概要:
git status --short,快速识别新增、修改、删除和未暂存内容。 - 取消全部暂存:
git restore --staged .,保留工作区文件和修改,仅清空暂存区。
提交前验证
使用暂存差异统计确认涉及的文件数量和改动规模:
git diff --cached --stat预期输出:
README.md | 2 +-
src/payment/NewValidator.java | 8 ++++++++
docs/old-api.md | 6 ------
3 files changed, 9 insertions(+), 7 deletions(-)最后一行汇总文件数、增加行数和删除行数。实际数值会随仓库内容变化;若输出为空,表示暂存区当前没有可提交差异。
风险与边界
在包含本地配置、密钥、日志或构建产物的仓库中执行 git add -A,可能把不应提交的文件一起暂存,造成敏感信息泄露或污染仓库。执行前应先查看 git status --short,并通过 .gitignore 排除长期不应跟踪的文件;不要用 git add -f 绕过忽略规则,除非已经确认文件内容安全。
该命令还会暂存删除操作。如果文件只是被误删,直接提交会把删除同步到远程仓库。应先检查状态;需要恢复文件时使用 git restore <路径>,需要保留删除但暂不提交时使用 git restore --staged <路径>。
排障清单
- 暂存后仍出现第二列
M:文件在暂存后又被修改,应检查新差异并重新执行git add -A。 - 某个新增文件没有出现:检查
.gitignore、仓库内部的嵌套.gitignore以及全局忽略规则。 - 误暂存大量文件:先执行
git restore --staged .,确认工作区修改仍在,再按文件或目录重新暂存。 - 旧版 Git 不支持
git restore:使用git reset HEAD -- .取消全部暂存,同样不会删除工作区修改。
兼容性
Git 2.0 及以后,git add -A 默认覆盖整个仓库;较老版本从子目录执行时可能只处理当前目录范围。生产脚本应先确认 git --version,或固定在仓库根目录执行以避免旧版本的范围差异。
git add -p
git add -p -- <PATH>按代码片段选择需要加入暂存区的修改。
交互式暂存修改
当一个文件同时包含功能代码、调试日志或尚未完成的改动时,用 git add -p 按代码片段选择进入暂存区的内容,最终只提交本次需要的修改。
命令定位
git add -p 比按文件执行 git add 更细:它比较工作区与暂存区,将差异拆成多个 hunk,并逐段询问是否暂存。操作只修改暂存区,不会删除工作区内容。
基本语法
git add -p
git add -p -- <PATH>省略路径时检查整个仓库;指定 <PATH> 可限制到单个文件或目录。路径前的 -- 用于避免文件名被误判为选项。
高频用法
先查看差异,再交互式暂存指定文件:
git diff -- app.js
git add -p -- app.js预期输出:
diff --git a/app.js b/app.js
index <OLD>..<NEW> 100644
--- a/app.js
+++ b/app.js
@@ <RANGE> @@
-const debug = true;
+const debug = false;
Stage this hunk [y,n,q,a,d,s,e,?]?输入 y 暂存当前片段,n 跳过,q 立即退出,a 暂存当前及后续片段,d 跳过当前及后续片段。一个片段混有多类修改时输入 s 尝试继续拆分;需要逐行调整时输入 e 编辑补丁。
验证结果
git status --short -- app.js
git diff --cached -- app.js
git diff -- app.js预期输出:
MM app.jsMM 表示该文件既有已暂存修改,也有未暂存修改。git diff --cached 查看将进入下次提交的内容;git diff 查看仍留在工作区的内容。实际补丁行号和哈希会不同。
风险与边界
使用 e 时若误删补丁中的上下文或标记,可能导致补丁无法应用或暂存范围错误;不确定时用 n 跳过,再修改文件后重新执行。git add -p 通常不会直接显示全新未跟踪文件的分段内容,可先执行 git add -N -- <PATH> 将其标记为意向添加,再运行交互式暂存。
发现选错片段时不要重置工作区,可用 git restore --staged -p -- <PATH> 交互式撤销暂存,工作区修改仍会保留。
排障清单
- 没有出现交互提示:先运行
git diff -- <PATH>,确认工作区相对暂存区确有差异。 s无法继续拆分:当前 hunk 的修改距离过近,使用e精确编辑,或先在工作区把改动拆开。- 验证内容不符:分别检查
git diff --cached与git diff,确认已暂存和未暂存两部分后再提交。
git restore --staged -- <PATH>将文件从暂存区移出并保留工作区修改。
取消暂存文件
文件误执行 git add 后,用 git restore --staged 将修改从暂存区移出,同时完整保留工作区内容,适合提交前重新整理文件或代码片段。
命令定位
该命令只调整暂存区,不会把文件恢复成仓库版本。取消后,修改会重新显示为“未暂存”,可继续编辑或稍后再次加入暂存区。
基本语法
git restore --staged -- <PATH><PATH> 可以是文件或目录;路径前加 -- 可明确结束选项解析,处理以短横线开头的文件名时尤其重要。
高频用法
取消暂存单个文件并立即验证:
git restore --staged -- config.yml
git status --short -- config.yml预期输出:
M config.yml状态码第一列代表暂存区,第二列代表工作区。前导空格加 M 表示暂存区已恢复,而工作区修改仍然存在;命令成功时通常没有单独提示。
取消暂存当前目录下的全部改动:
git restore --staged .
git status --short预期结果:
M config.yml
M src/app.js实际文件名和数量取决于仓库状态。确认第一列为空后,再按提交范围重新执行 git add 或 git add -p。
精确撤销片段
只撤销文件中的部分已暂存内容时使用交互模式:
git restore --staged -p -- app.js预期输出:
diff --git a/app.js b/app.js
index <OLD>..<NEW> 100644
@@ <RANGE> @@
-const debug = true;
+const debug = false;
Unstage this hunk [y,n,q,a,d,s,e,?]?输入 y 撤销当前片段的暂存,输入 n 保留其暂存状态。实际哈希和行号会不同。
风险与边界
不要把 git restore --staged 与不带 --staged 的 git restore <PATH> 混用:后者会覆盖工作区修改,可能造成未提交内容丢失。执行前可先用 git diff --cached -- <PATH> 确认即将移出的内容。
首次提交尚不存在 HEAD 时,部分 Git 版本可能无法按默认来源恢复暂存区。对于刚加入且此前未被跟踪的新文件,可用 git rm --cached -- <PATH> 移出暂存区并保留本地文件;不要对普通已跟踪文件随意使用该命令,否则会把整份文件记录为删除。
兼容性
Git 2.23 及以上优先使用 git restore --staged。旧版本可使用:
git reset HEAD -- <PATH>预期结果:
Unstaged changes after reset:
M config.yml不同版本的提示文本可能略有差异,但工作区修改应继续保留。