git add 把工作区里的改动写进暂存区——也就是「下一次提交要包含什么」的清单。它不生成提交、不传远端,只决定清单内容,因此是控制提交粒度最关键的一条命令。

本文完整列出 git add 支持的常用参数并逐个解说,重点讲清 -A、-u、-p 的区别,以及 git add . 与 git add -A 到底差在哪。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 5 / 28 篇,全部收录在 Git 栏目。参数表列的是日常高频项,并非穷举;想看某个命令的完整参数,用 git add -h 看精简列表、git help add 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架,再对照下一节的参数表。<占位> 表示必填值,实际输入时不要带尖括号;[...] 表示可选项,-- 用来分隔选项与路径。

bash语法
git add [<options>] [--] <pathspec>...

二、参数逐项详解

下表按用途列出 git add 的常用参数,每项都注明了「它到底改变了什么」。

参数作用
<pathspec>路径、通配符或目录,如 src/、*.js、:/(仓库根)
-A / --all把新增、修改、删除全部同步到暂存区;不带路径时作用于整个仓库
-u / --update只更新已跟踪文件的修改与删除,不包含新文件
-p / --patch交互式按 hunk 挑选改动,把一次大改拆成多个干净提交
-i / --interactive进入交互式暂存菜单
-e / --edit在编辑器里直接编辑将暂存的 diff
-f / --force强行加入被 .gitignore 忽略的文件
-n / --dry-run只演练、不真的暂存,用来验证忽略规则是否命中
-v / --verbose打印被加入的文件名
-N / --intent-to-add只登记「稍后会新增」,让 git diff 能看到这个新文件
--chmod=(+|-)x只改索引里的可执行位,不动磁盘文件
--renormalize改过 core.autocrlf / .gitattributes 后,按新规则重存所有已跟踪文件
--ignore-errors个别文件索引失败时继续处理其它文件(仍返回非零退出码)
--分隔选项与路径,文件名以 - 开头时必须用

三、常用示例

四种最常用的暂存方式

bash四种最常用的暂存方式
git add -A                       # 全量暂存(在项目根目录最省心)
git add -u                       # 只暂存已跟踪文件的改动
git add -p src/api/user.js       # 一个文件里只挑几段提交
git add -n .                     # 先看看哪些会被加进去

把一次大改拆成两个提交

bash把一次大改拆成两个提交
git add -p src/order.js          # 逐块 y / n 选择重构部分
git commit -m "refactor: 抽取订单校验函数"
git add -p src/order.js          # 再选新功能部分
git commit -m "feat: 支持批量导出"

特殊情况

bash特殊情况
git add -f config/local.php       # 强行加入被忽略的文件
git add --chmod=+x scripts/deploy.sh
git add --renormalize .          # 修正换行符后重建索引

四、注意事项

⚠️
git add . 不等于 git add -A
在仓库根目录执行时两者效果一样,但在子目录里 . 只代表「当前目录及子目录」,-A 不带路径时作用于整个仓库。想避免路径依赖,统一用 git add -A 或 git add -A :/。
提交前再确认一眼: git add 之后跑 git diff --cached,看到的就是下一次提交的全部内容;配合 git add -p 可以让每个提交只做一件事,代码评审和日后 revert 都会轻松很多。

五、小结

把三个参数分清楚就够用了:-A 管「全部」、-u 管「已跟踪」、-p 管「自己挑」。再加上 -n 预演、-f 破例、-N 占位,git add 的全部常用能力就齐了。

本系列共 28 篇,一个命令一篇,完整目录见 Git 栏目。下一篇:git commit 命令参数详解。