git-format-patch
名称
git-format-patch - 准备电子邮件提交补丁
概要
git format-patch [-k] [(-o|--output-directory) <dir> | --stdout] [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [--signature=<signature> | --no-signature] [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--rfc] [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]] [--progress] [<common diff options>] [ <since> | <revision range> ]
描述
每次提交时，将每个提交的补丁准备在一个文件中，格式化为类似于 UNIX 邮箱格式。此命令的输出便于电子邮件提交或与 git am 一起使用。
有两种方法可以指定要操作的提交。
- 单个提交< since>，指定通往当前分支的提示的提交，这些提交不在历史记录中，导致< since>要输出。
- 通用<修订范围>表达式（参见 gitrevisions [7] 中的“指定修订”部分）表示指定范围内的提交。
在单个< commit>的情况下，第一个规则优先。要应用第二个规则，即从历史开始直到< commit>格式化所有内容，请使用--root选项：git format-patch --root 。如果您只想格式化< commit>本身，您可以使用git format-patch -1 执行此操作。
默认情况下，每个输出文件从 1 开始按顺序编号，并使用提交消息的第一行（为路径名安全性进行按摩）作为文件名。使用--numbered-files选项，输出文件名将只是数字，而不会附加提交的第一行。除非指定了--stdout选项，否则输出文件的名称将打印到标准输出。
如果指定了-o，则输出文件将在< dir>中创建。否则，它们将在当前工作目录中创建。可以使用format.outputDirectory配置选项设置默认路径。 -o选项优先于format.outputDirectory。要将补丁存储在当前工作目录中，即使format.outputDirectory指向其他位置，也请使用-o .。
默认情况下，单个补丁的主题是“[PATCH]”，后跟从提交消息到第一个空行的串联（参见 git-commit [1] 的讨论部分） 。
当输出多个补丁时，主题前缀将改为“[PATCH n / m]”。要强制为单个补丁添加 1/1，请使用-n。要忽略主题中的色块编号，请使用-N。
如果给出--thread，git-format-patch将生成In-Reply-To和References标题，以使第二个和后续的补丁邮件显示为对第一个邮件的回复;这也会生成一个Message-Id标题来引用。
OPTIONS
-p
--no-stat
生成没有任何 diffstats 的普通补丁。
-U<n>
--unified=<n>
用< n>生成差异。上下文而不是通常的三行。
--indent-heuristic
启用改变差异块边界的启发式以使补丁更易于阅读。这是默认值。
--no-indent-heuristic
禁用缩进启发式。
--minimal
花些额外的时间来确保产生尽可能小的差异。
--patience
使用“耐心差异”算法生成差异。
--histogram
使用“histogram diff”算法生成 diff。
--anchored=<text>
使用“锚定差异”算法生成差异。
可以多次指定此选项。
如果源和目标中都存在一行，只存在一次，并以此文本开头，则此算法会尝试阻止它在输出中显示为删除或添加。它在内部使用“耐心差异”算法。
--diff-algorithm={patience|minimal|histogram|myers}
选择差异算法。变体如下：
default, myers
基本的贪心差异算法。目前，这是默认值。
minimal
花些额外的时间来确保产生尽可能小的差异。
patience
生成补丁时使用“耐心差异”算法。
histogram
该算法将耐心算法扩展为“支持低发生的共同元素”。
例如，如果将diff.algorithm变量配置为非默认值并想要使用默认值，则必须使用--diff-algorithm=default选项。
--stat[=<width>[,<name-width>[,<count>]]]
生成 diffstat。默认情况下，文件名部分将使用必要的空间，图形部分的其余部分将使用。最大宽度默认为终端宽度，如果未连接到终端，则为 80 列，并且可以被覆盖。可以通过在逗号后面给出另一个宽度来限制文件名部分的宽度。可以使用--stat-graph-width=（影响生成统计图的所有命令）或设置diff.statGraphWidth=（不影响git format-patch）来限制图形部分的宽度。通过给出第三个参数，可以将输出限制为第一个行，如果有更多，则可以将...限制为...。
也可以使用--stat-width=，--stat-name-width=和--stat-count=单独设置这些参数。
--compact-summary
输出扩展标题信息的精简摘要，例如文件创建或删除（“新”或“消失”，如果是符号链接，则可选“+ l”）和模式更改（“+ x”或“-x”用于添加或删除 diffstat 中的可执行位）。信息放在文件名部分和图形部分之间。意味着--stat。
--numstat
与--stat类似，但显示十进制表示法中添加和删除的行数以及没有缩写的路径名，以使其更加机器友好。对于二进制文件，输出两个-而不是0 0。
--shortstat
仅输出--stat格式的最后一行，其中包含已修改文件的总数，以及已添加和已删除行的数量。
--dirstat[=<param1,param2,…>]
输出每个子目录的相对更改量的分布。 --dirstat的行为可以通过以逗号分隔的参数列表传递来定制。默认值由diff.dirstat配置变量控制（参见 git-config [1] ）。可以使用以下参数：
changes
通过计算已从源中删除或添加到目标的行来计算 dirstat 数。这忽略了文件中纯代码移动的数量。换句话说，重新排列文件中的行不会像其他更改那样计算。这是没有给出参数时的默认行为。
lines
通过执行常规的基于行的差异分析来计算 dirstat 数字，并对移除/添加的行数进行求和。 （对于二进制文件，计算 64 字节块，因为二进制文件没有自然的线条概念）。这是比changes行为更昂贵的--dirstat行为，但它确实计算文件中重新排列的行与其他更改一样多。结果输出与您从其他--*stat选项获得的输出一致。
files
通过计算更改的文件数来计算 dirstat 数。在 dirstat 分析中，每个更改的文件都相同。这是计算上最便宜的--dirstat行为，因为它根本不需要查看文件内容。
cumulative
计算父目录的子目录中的更改。请注意，使用cumulative时，报告的百分比总和可能超过 100％。可以使用noncumulative参数指定默认（非累积）行为。
<limit>
整数参数指定截止百分比（默认为 3％）。贡献低于此百分比变化的目录不会显示在输出中。
示例：以下将计算已更改的文件，同时忽略少于已更改文件总量的 10％的目录，并在父目录中累计子目录计数：--dirstat=files,10,cumulative。
--summary
输出扩展标题信息的精简摘要，例如创建，重命名和模式更改。
--no-renames
关闭重命名检测，即使配置文件提供默认值也是如此。
--full-index
在生成补丁格式输出时，在“索引”行上显示完整的前映像和后映像 blob 对象名称，而不是第一个字符。
--binary
除--full-index外，还可输出可用git-apply应用的二进制差异。
--abbrev[=<n>]
而不是在 diff-raw 格式输出和 diff-tree 标题行中显示完整的 40 字节十六进制对象名称，而是仅显示部分前缀。这与上面的--full-index选项无关，后者控制 diff-patch 输出格式。可以使用--abbrev=指定非默认位数。
-B[<n>][/<m>]
--break-rewrites[=[<n>][/<m>]]
将完整的重写更改分为删除和创建对。这有两个目的：
它影响了一个更改的方式，相当于一个文件的完全重写，而不是一系列的删除和插入混合在一起，只有几行恰好与文本作为上下文匹配，而是作为单个删除所有旧的后跟一个单个插入所有新内容，数字m控制-B 选项的这一方面（默认为 60％）。 -B/70%指定少于 30％的原始文本应保留在结果中，以便 Git 将其视为完全重写（即，否则生成的修补程序将是一系列删除和插入与上下文行混合在一起）。
当与-M 一起使用时，完全重写的文件也被视为重命名的源（通常-M 只考虑作为重命名源消失的文件），并且数字n控制 - 的这方面 - B 选项（默认为 50％）。 -B20%指定添加和删除的更改与文件大小的 20％或更多相比，有资格被选为可能的重命名源到另一个文件。
-M[<n>]
--find-renames[=<n>]
检测重命名。如果指定了n，则它是相似性指数的阈值（即与文件大小相比的添加/删除量）。例如，-M90%表示如果超过 90％的文件未更改，Git 应将删除/添加对视为重命名。如果没有%符号，则该数字将作为分数读取，并在其前面加上小数点。即，-M5变为 0.5，因此与-M50%相同。同样，-M05与-M5%相同。要将检测限制为精确重命名，请使用-M100%。默认相似性指数为 50％。
-C[<n>]
--find-copies[=<n>]
检测副本以及重命名。另见--find-copies-harder。如果指定了n，则其含义与-M的含义相同。
--find-copies-harder
出于性能原因，默认情况下，仅当在同一变更集中修改了副本的原始文件时，-C选项才会查找副本。此标志使命令检查未修改的文件作为副本源的候选者。对于大型项目来说，这是一项非常昂贵的操作，因此请谨慎使用。提供多个-C选项具有相同的效果。
-D
--irreversible-delete
省略删除的原像，即只打印标题而不打印原像和/dev/null之间的差异。得到的贴片不适用于patch或git apply;这仅适用于那些希望在更改后专注于审阅文本的人。此外，输出显然缺乏足够的信息来反向应用这样的补丁，甚至手动，因此选项的名称。
与-B一起使用时，也省略删除/创建对的删除部分中的原像。
-l<num>
-M和-C选项需要 O（n ^ 2）处理时间，其中 n 是潜在的重命名/复制目标的数量。如果重命名/复制目标的数量超过指定的数量，此选项可防止重命名/复制检测运行。
-O<orderfile>
控制文件在输出中的显示顺序。这会覆盖diff.orderFile配置变量（参见 git-config [1] ）。要取消diff.orderFile，请使用-O/dev/null。
输出顺序由< orderfile>中的 glob 模式的顺序决定。首先输出所有与第一个模式匹配的路径名的文件，然后输出所有与第二个模式（但不是第一个模式）匹配的路径名的文件，依此类推。路径名与任何模式都不匹配的所有文件都是最后输出的，就好像文件末尾有一个隐式匹配所有模式一样。如果多个路径名具有相同的等级（它们匹配相同的模式但没有早期模式），则它们相对于彼此的输出顺序是正常顺序。
< orderfile>解析如下：
- 空行被忽略，因此可以将它们用作分隔符以提高可读性。
- 以哈希（“
#”）开头的行将被忽略，因此它们可用于注释。如果以散列开头，则将反斜杠（“\”）添加到模式的开头。 - 每个其他行包含一个模式。
模式与没有 FNM_PATHNAME 标志的 fnmatch（3）使用的模式具有相同的语法和语义，但如果删除任意数量的最终路径名组件与模式匹配，则路径名也匹配模式。例如，模式“foo*bar”匹配“fooasdfbar”和“foo/bar/baz/asdf”而不匹配“foobarx”。
-a
--text
将所有文件视为文本。
--ignore-cr-at-eol
进行比较时，忽略行尾的回车。
--ignore-space-at-eol
忽略 EOL 中的空白更改。
-b
--ignore-space-change
忽略空格量的变化。这会忽略行尾的空格，并将一个或多个空白字符的所有其他序列视为等效。
-w
--ignore-all-space
比较线条时忽略空格。即使一行有空格而另一行没有空格，这也会忽略差异。
--ignore-blank-lines
忽略其行全部为空的更改。
--inter-hunk-context=<lines>
显示差异之间的上下文，直到指定的行数，从而融合彼此接近的帅哥。如果未设置配置选项，则默认为diff.interHunkContext或 0。
-W
--function-context
显示整个周围的变化功能。
--ext-diff
允许执行外部 diff 助手。如果使用 gitattributes [5] 设置外部差异驱动程序，则需要将此选项与 git-log [1] 和朋友一起使用。
--no-ext-diff
禁止外部差异驱动程序。
--textconv
--no-textconv
在比较二进制文件时允许（或禁止）外部文本转换过滤器运行。有关详细信息，请参阅 gitattributes [5] 。由于 textconv 过滤器通常是单向转换，因此生成的差异适合人类使用，但无法应用。因此，默认情况下，textconv 过滤器仅针对 git-diff [1] 和 git-log [1] 启用，但不适用于 git-format-patch [ 1] 或差异管道命令。
--ignore-submodules[=<when>]
忽略差异生成中子模块的更改。 <当>可以是“none”，“untracked”，“dirty”或“all”，这是默认值。使用“none”时，如果子模块包含未跟踪或修改的文件，或者其 HEAD 与超级项目中记录的提交不同，则可以使用“无”来修改子模块，并可用于覆盖中 ignore 选项的任何设置 git-config [1] 或 gitmodules [5] 。当使用“未跟踪”时，如果子模块仅包含未跟踪的内容（但仍会扫描修改的内容），则子模块不会被视为脏。使用“脏”忽略对子模块工作树的所有更改，仅显示存储在超级项目中的提交的更改（这是 1.7.0 之前的行为）。使用“all”隐藏子模块的所有更改。
--src-prefix=<prefix>
显示给定的源前缀而不是“a /”。
--dst-prefix=<prefix>
显示给定的目标前缀而不是“b /”。
--no-prefix
不显示任何源或目标前缀。
--line-prefix=<prefix>
为每行输出预先附加前缀。
--ita-invisible-in-index
默认情况下，“git add -N”添加的条目在“git diff”中显示为现有空文件，在“git diff --cached”中显示为新文件。此选项使条目在“git diff”中显示为新文件，在“git diff --cached”中不存在。可以使用--ita-visible-in-index恢复此选项。这两个选项都是实验性的，将来可以删除。
有关这些常用选项的更详细说明，另请参阅 gitdiffcore [7] 。
-<n>
从最顶层< n>准备补丁。提交。
-o <dir>
--output-directory <dir>
使用< dir>存储生成的文件，而不是当前的工作目录。
-n
--numbered
名称输出为 [PATCH n / m] 格式，即使只有一个补丁。
-N
--no-numbered
以 [PATCH] 格式输出名称。
--start-number <n>
开始在< n>处对补丁进行编号。而不是 1。
--numbered-files
输出文件名将是一个简单的数字序列，不附加提交的默认第一行。
-k
--keep-subject
不要从提交日志消息的第一行剥离/添加 [PATCH] 。
-s
--signoff
使用您自己的提交者标识将Signed-off-by:行添加到提交消息中。有关详细信息，请参阅 git-commit [1] 中的签收选项。
--stdout
以 mbox 格式将所有提交打印到标准输出，而不是为每个提交创建文件。
--attach[=<boundary>]
Git 中文参考（六）（2）https://developer.aliyun.com/article/1565803
