临时改几行、只传给熟悉的人、目标机不跑git审计流程，用git diff；要留作者信息、走代码审查、后续可能合并进主干，必须用git format-patch。
git diff 和 git format-patch 到底该用哪个
直接说结论：临时改几行、只传给熟悉的人、目标机不跑 Git 审计流程，用 git diff；要留作者信息、走代码审查、后续可能合并进主干，必须用 git format-patch。
git diff 输出的是裸 diff，没 From 行、没 Subject、没日期，git apply 能打上，但 git am 会报错 “missing header”，也查不到是谁、什么时候、为什么改的。而 git format-patch -1 HEAD 生成的文件开头一定是 From: + Subject: + 空行 + 提交信息 + diff --git，这才是可追溯、可审计的标准补丁。
- 新建文件没出现在
git diff里？先git add -N，再git diff --cached -
git format-patch报 “no upstream configured”？运行git branch --set-upstream-to=origin/main（把 main 换成你实际的远程分支名） - 补丁含二进制文件（比如图片、字体）？加
--binary参数，否则git am直接拒绝
VSCode 里生成 patch 最稳的方式
别装“Patch Export”类插件——多数已停更，遇到换行符不一致、路径含空格、中文文件名就导出乱码或漏文件。直接用 VSCode 底部集成终端（Ctrl+`）执行命令，当前工作区路径自动对齐，Git 识别零误差。
确认终端里 git --version 有输出，再执行：
- 导出所有未提交改动：
git diff > fix-login-20260615.patch - 只导出已暂存内容：
git diff --cached > staged-only.patch - 导出最近一次提交（含元信息）：
git format-patch -1 HEAD --stdout > 0001-fix-login.patch
生成后立刻检查：head -n 3 fix-login-20260615.patch，看到 diff --git a/... 才算成功；如果是空文件或 HTML 内容，说明当前目录不是 Git 仓库根目录。
目标机器上 git apply 失败的常见原因
git apply 报错 “patch failed” 不等于补丁本身有问题，大概率是上下文不匹配。它默认严格校验变更前后的行号偏移，哪怕目标代码比源代码多删了一行空行，也会失败。
- 先用
git apply --check my.patch验证是否能干净打上，返回 0 才继续 - 失败时加
--reject，它会把冲突部分写进.rej文件，人工对比两头代码就能定位差异点 - 补丁里有新建文件，但目标机对应父目录不存在？
git apply不自动建目录，得提前mkdir -p src/utils - 换行符不一致（Windows 生成的 patch 传到 Linux）？加
--ignore-space-change或统一用 LF
补丁命名和传输的细节陷阱
补丁文件名看着无所谓，实际影响协作效率。用 fix-login-20260615.patch 比 patch1.patch 强十倍——日期锁定版本基线，描述直指修改范围，避免多人传多个同名 patch 后搞混。
U 盘拷贝时注意两点：
- 不要双击打开 patch 文件看内容，某些系统会用文本编辑器加载并悄悄转码（比如 GBK → UTF-8），导致
git apply校验失败 - 传完立刻在目标机运行
sha256sum my.patch，和源机结果比对，确认一字未变
真正容易被忽略的是路径一致性：补丁里的 diff --git a/src/api/login.js b/src/api/login.js 要求目标机也得在仓库根目录下执行 git apply，cd 错一层就会提示 “file not found”。
