Setup and Config

• git
• config
• help
• bugreport
• Credential helpers

Getting and Creating Projects

• init
• clone

Basic Snapshotting

• add
• status
• diff
• commit
• notes
• restore
• reset
• rm
• mv

Branching and Merging

• branch
• checkout
• switch
• merge
• mergetool
• log
• stash
• tag
• worktree

Sharing and Updating Projects

• fetch
• pull
• push
• remote
• submodule

Inspection and Comparison

• show
• log
• diff
• difftool
• range-diff
• shortlog
• describe

Patching

• apply
• cherry-pick
• diff
• rebase
• revert

Debugging

• bisect
• blame
• grep

Email

• am
• apply
• imap-send
• format-patch
• send-email
• request-pull

External Systems

• svn
• fast-import

Server Admin

• daemon
• update-server-info

Guides

• gitattributes
• Command-line interface conventions
• Everyday Git
• Frequently Asked Questions (FAQ)
• Glossary
• Hooks
• gitignore
• gitmodules
• Revisions
• Submodules
• Tutorial
• Workflows
• All guides...

Administration

• clean
• gc
• fsck
• reflog
• filter-branch
• instaweb
• archive
• bundle

Plumbing Commands

• cat-file
• check-ignore
• checkout-index
• commit-tree
• count-objects
• diff-index
• for-each-ref
• hash-object
• ls-files
• ls-tree
• merge-base
• read-tree
• rev-list
• rev-parse
• show-ref
• symbolic-ref
• update-index
• update-ref
• verify-pack
• write-tree

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] [--always]
		 [--cover-from-description=<mode>]
		 [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
		 [(--reroll-count|-v) <n>]
		 [--to=<email>] [--cc=<email>]
		 [--[no-]cover-letter] [--quiet]
		 [--[no-]encode-email-headers]
		 [--no-notes | --notes[=<ref>]]
		 [--interdiff=<previous>]
		 [--range-diff=<previous> [--creation-factor=<percent>]]
		 [--filename-max-length=<n>]
		 [--progress]
		 [<common-diff-options>]
		 [ <since> | <revision-range> ]

将每个非合并提交及其 "补丁" 准备在每个提交的一个 "消息" 中,格式类似于 UNIX 邮箱。 这条命令的输出便于提交电子邮件或与 "git am" 一起使用。

命令产生的 "信息" 由三部分组成:

• 一个简短的元数据头,以 "From <提交>" 开始,带有固定的 "Mon Sep 17 00:00:00 2001" 的日期,以帮助 "file(1)" 等程序识别该文件是该命令的输出,记录作者身份、作者日期和修改标题的字段(取自提交日志信息的第一段)。

• 提交日志信息的第二段和后续段落。

• "补丁",也就是该提交和其父辈之间的 "diff -p --stat" 输出(见 git-diff[1])。

日志信息和补丁之间用三条虚线隔开。

有两种方法可以指定要对哪些提交进行操作。

1. 单一的提交,<从>,指定导致当前分支顶端的提交不在导致 <从> 的历史中,要被输出。

2. 通用的 <修订范围> 表达式(见 gitrevisions[7]中的 "指定修订" 一节)表示指定范围内的提交。

在只有一个 <提交> 的情况下,第一条规则具有优先权。 要应用第二条规则,即格式化从历史开始到 <提交> 为止的所有内容,使用 --root 选项:git format-patch --root <提交>。 如果你只想格式化 <提交> 本身,你可以用`git format-patch -1 <提交>`来做。

默认情况下,每个输出文件从 1 开始依次编号,并使用提交信息的第一行(为保证路径名的安全而进行了调整)作为文件名。使用 --numbered-files 选项,输出文件名将只有数字,而没有附加提交信息的第一行。 除非指定 --stdout 选项,否则输出文件的名称将被打印到标准输出。

如果指定了 -o,输出文件将在<目录>创建。 否则,它们将在当前工作目录下创建。默认路径可以通过 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 头供参考。

-<n>

从最上面的 <n> 个提交中准备补丁。

-o <目录>

--output-directory <目录>

使用 <目录> 来存储结果文件,而不是当前工作目录。

-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] 中的 signoff 选项。

--stdout

以 mbox 格式将所有的提交打印到标准输出,而不是为每个提交创建一个文件。

--attach[=<边界>]

创建多部分/混合附件,第一部分是提交信息,第二部分是补丁本身,Content-Disposition: attachment。

--no-attach

禁用附件的创建,覆盖配置设置。

--inline[=<边界>]

创建 multipart/mixed 附件,第一部分是提交信息,第二部分是补丁本身,使用 Content-Disposition: inline。

--thread[=<样式>]

--no-thread

控制添加 In-Reply-To 和 References 标头,使第二封及以后的邮件显示为对第一封邮件的回复。 还控制生成 Message-ID 头,以便参考。

可选的 <风格> 参数可以是 shallow 或 deep。 ‘浅’ 线程使每封邮件都是对该系列的头的回复,其中头是从封面信、--in-reply-to 和第一个补丁邮件中选择的,按这个顺序。 ‘深’ 线程使每封邮件都是对前一封的回复。

默认是 --no-thread,除非设置了 format.thread 配置。 没有参数的 --thread 等同于 --thread=shallow。

请注意,git send-email 的默认设置是对邮件本身进行线程处理。 如果你想让 git format-patch 负责线程,你要确保 git send-email 的线程被禁用。

--in-reply-to=<消息 ID>

使第一封邮件(或所有带有 --no-thread 的邮件)作为给定的 <消息 id> 的回复出现,这可以避免破坏线程以提供一个新的补丁系列。

--ignore-if-in-upstream

不包括与 <until>…​<since> 中的提交相匹配的补丁。 这将检查所有可从 <since> 到达但不在 <until> 的补丁,并将它们与正在生成的补丁进行比较,任何匹配的补丁都将被忽略。

--always

包括那些没有引入任何变化的提交的补丁,这些补丁默认是省略的。

--cover-from-description=<模式>

控制求职信的哪些部分将使用分支机构的描述自动填充。

如果 <模式> 是 message 或 default,求职信的主题将被填充为占位符文本。信函的正文将被填入分支的描述。这是没有指定配置或命令行选项时的默认模式。

如果 <模式> 是 subject,分支描述的第一段将填入求职信的主题。描述的其余部分将填充到求职信的正文中。

如果 <模式> 是 auto,如果分支描述的第一段大于100字节,那么模式将是 message,否则将使用 subject。

如果 <模式> 为 none,求职信的主题和正文都将被填充为占位符文本。

--description-file=<文件>

使用 <文件> 的内容而不是分支说明来生成求职信。

--subject-prefix=<主题前缀>

在主题行中不要使用标准的 [PATCH] 前缀,而应使用 [<主题前缀>]。这可用于命名补丁系列,并可与 --numbered 选项结合使用。

配置变量 format.subjectPrefix 也可用于配置主题前缀,以适用于指定仓库的所有补丁。这在接收多个仓库补丁的邮件列表中通常很有用,可用于消除补丁的歧义(例如值为 "PATCH my-project")。

--filename-max-length=<n>

代替标准的 64 字节,将生成的输出文件名压缩到 <n> 字节左右(太短的值会被默默提升到合理的长度)。 默认为 format.filenameMaxLength 配置变量的值,如果没有配置,则为 64。

--rfc[=<rfc>]

在主题前缀前面加上字符串 <rfc>(默认为 "RFC")。由于主题前缀默认为 "PATCH",默认情况下您将得到 "RFC PATCH"。

RFC 意味着"请求评论"(Request For Comments);在发送一个用于讨论而非应用的实验性补丁时使用这个。使用 "--rfc=WIP" 也可能是一个有用的方式来表明一个补丁尚未完成("WIP" 代表 "Work In Progress")。

If the convention of the receiving community for a particular extra string is to have it after the subject prefix, the string <rfc> can be prefixed with a dash ("-") to signal that the rest of the <rfc> string should be appended to the subject prefix instead, e.g., --rfc='-(WIP) results in "PATCH (WIP)".

-v <n>

--reroll-count=<n>

将该系列标记为该主题的第 <n> 次迭代。输出的文件名有 v<n>,主题前缀(默认为 "PATCH",但可通过 --subject-prefix 选项配置)有 v<n> 附加在上面。 例如,--reroll-count=4 可能产生 v4-0001-add-makefile.patch 文件,其中有 "Subject: [PATCH v4 1/20] Add makefile"。 <n> 不一定是整数(例如,"--reroll-count=4.4",或 "--reroll-count=4rev2 "都可以),但使用这种 reroll-count 的缺点是,与前一版本的 range-diff/interdiff 并没有准确说明新的 interation 是与哪个版本比较。

--to=<e-mail>

在邮件标题中增加一个 To: ` 头。这是在任何配置的头信息之外的,可以多次使用。 否定的形式 `--no-to 会丢弃到目前为止添加的所有 To: 头信息(来自配置或命令行)。

--cc=<email>

在邮件标题中添加 Cc: ` 标头。这是在任何配置的头信息之外的,可以多次使用。 否定的形式 `--no-cc 会丢弃到目前为止添加的所有 Cc: 头信息(来自配置或命令行)。

--from

--from=<身份>

在每封提交邮件的`From:` 标头中使用 ident。如果提交的作者身份与所提供的 ident 在文字上不一致,则在邮件正文中放置一个 From: ` 头,注明原作者。如果没有给出 `ident,则使用提交者的身份。

注意,这个选项只有在你实际发送邮件时才有用,并且想把你自己确定为发件人,但保留原作者(git am 会正确接收正文头)。还要注意的是,git send-email 已经为你处理了这种转换,如果你将结果反馈给 git send-email,就不应该使用这个选项。

--[no-]force-in-body-from

对于通过 --from 选项指定的电子邮件发件人,默认情况下,如果发件人与作者不同,会在提交日志信息的顶部添加一个内文 "From:",以确定提交的真正作者。 有了这个选项,即使发件人和作者的名字和地址相同,也会在正文中加入 "From:",这在邮件列表软件混淆发件人身份时可能会有帮助。 默认为 format.forceInBodyFrom 配置变量的值。

--add-header=<头部>

在邮件头中添加一个任意的头。 这是在任何配置的头文件之外的,并且可以多次使用。 例如,--add-header="Organization: git-foo"。 否定的形式 --no-add-header 会丢弃 所有(To:, Cc:, 和自定义)从配置或命令行添加的头信息。

--[no-]cover-letter

除了补丁之外,还要生成一个包含分支描述、短日志和整体差异状态的封面文件。 你可以在发送之前在文件中填写描述。

--encode-email-headers

--no-encode-email-headers

用 "Q-encoding"(在RFC 2047中描述)对有非 ASCII 字符的邮件头进行编码,而不是逐字输出邮件头。默认为 format.encodeEmailHeaders 配置变量的值。

--interdiff=<以前>

作为审查员的帮助,在封面信中插入一个 interdiff,或者作为1个补丁系列中唯一一个补丁的注释,显示补丁系列的前一个版本与当前被格式化的系列之间的差异。previous 是一个单一的修订,命名了与被格式化的系列有共同基础的前一个系列的提示(例如 git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2)。

--range-diff=<以前>

作为审查员的辅助工具,在封面信中插入一个 range-diff(见 git-range-diff[1]),或者作为1个补丁系列中唯一一个补丁的注释,显示该补丁系列的前一个版本与当前被格式化的系列之间的差异。 previous 可以是一个单一的修订版,如果它与被格式化的系列有共同的基础,则命名为前一个系列的提示(例如 git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2),如果两个系列的版本不相干,则是一个修订范围(例如 git format-patch --cover-letter --range-diff=feature/v1~3.feature/v1 -3 feature/v2)。

请注意,传递给命令的差异选项会影响 format-patch 的主要产品如何生成,它们不会传递给用于生成封面材料的基础 `range-diff ` 机器(这在将来可能会改变)。

--creation-factor=<百分比>

与 --range-diff 一起使用,通过调整创建/删除成本的模糊系数,来调整匹配上一个和当前系列补丁之间提交的启发式方法。详情见 git-range-diff[1])。

默认值为 999(git-range-diff[1] 使用 60),因为使用场景是显示与同一主题的旧版本的比较,并且该工具应在两套补丁之间找到更多的对应关系。

--notes[=<引用>]

--no-notes

在三折线之后添加该提交的注释(见 git-notes[1])。

预期的用例是为提交编写不属于提交日志信息本身的支持性解释,并将其包含在补丁提交中。虽然我们可以在 format-patch 运行后但在发送前简单地写下这些解释,但将其保留为 Git 笔记,可以在补丁系列的不同版本之间进行维护(但要使用这种工作流程,请参考 git-notes[1] 中关于`notes.rewrite` 配置选项的讨论)。

默认为`--no-notes`,除非设置了 format.notes 配置。

--[no-]signature=<签名>

给每个产生的信息添加一个签名。根据 RFC 3676,签名与正文之间用一行 -- 分隔。如果签名选项被省略,则签名默认为 Git 版本号。

--signature-file=<文件>

工作原理与 --signature 相同,只是签名是从文件中读取的。

--suffix=.<后缀>

不使用 .patch 作为生成文件名的后缀,而使用指定的后缀。 一个常见的选择是 --suffix=.txt。 将此留空将删除 .patch 后缀。

请注意,前导字符不一定是点;例如,你可以使用 --suffix=-patch 来获得 0001-description-of-my-change-patch。

-q

--quiet

不要将生成的文件名打印到标准输出。

--no-binary

不输出二进制文件中的变化内容,而是显示这些文件变化的通知。 使用该选项生成的补丁不能被正确应用,但它们对代码审查仍然有用。

--zero-commit

在每个补丁的 From 头中输出一个全零的哈希值,而不是提交的哈希值。

--[no-]base[=<提交>]

记录基树信息,以确定该补丁系列所适用的状态。 详见下面的基树信息部分。如果 <提交> 是 "auto",就会自动选择一个基数提交。--no-base 选项会覆盖 format.useAutoBase 配置。

--root

将修订版参数视为 <revision range>,即使它只是一个单一的提交(通常会被视为 <since>)。 注意,包含在指定范围内的根提交总是被格式化为创建补丁,与此标志无关。

--progress

在生成补丁时在标准错误流上显示进度报告。

你可以指定额外的邮件标题行添加到每封邮件中,主题前缀和文件后缀的默认值,在输出多个补丁时对补丁进行编号,添加 "To: " 或 "Cc: " 标题,配置附件,更改补丁输出目录,以及用配置变量签署补丁。

由 git format-patch 产生的补丁是 UNIX 邮箱格式,有一个固定的 "magic" 时间戳,以表明该文件是由 format-patch 输出的,而不是一个真正的邮箱,像这样:

通常情况下,它会被放在 MUA 的 drafts 文件夹中,被编辑以添加及时的评论,这些评论不应该被放在 changelog 中的三个破折号之后,然后以消息的形式发送,在我们的例子中,其正文以 "arch/arm config files were…​" 开始。 在接收端,读者可以将有趣的补丁保存在 UNIX 邮箱中,并通过 git-am[1] 应用它们。

当一个补丁是正在进行的讨论的一部分时,由 git format-patch 生成的补丁可以进行调整,以利用 git am --scissors 功能。 在你对讨论的回应之后,有一行只由 "-- >8 --"(剪刀和打孔)组成,后面是去除不必要的头域的补丁:

当用这种方式发送补丁时,大多数情况下是发送你自己的补丁,所以除了 "From $SHA1 $magic_timestamp" 标记外,你应该从补丁文件中省略 `From: ` 和 `Date: ` 行。 补丁的标题很可能与补丁所回应的讨论主题不同,所以很可能要保留 Subject: 这一行,就像上面的例子一样。

检查补丁是否损坏

这里有一些关于如何使用各种邮件工具成功地在线提交补丁的提示。

GMail

Thunderbird

	mail.html_compose => false
	mail.identity.default.compose_html => false
	mail.identity.id?.compose_html => false

KMail

基准树信息块用于维护者或第三方测试人员了解补丁系列所适用的确切状态。它由 ‘基本提交’ 和零个或多个 ‘前提补丁’ 组成,前者是众所周知的提交,是项目历史中稳定部分的一部分,而后者是正在运行的知名补丁,还不是 ‘基本提交’ 的一部分,在应用这些补丁之前需要在 ‘基本提交’ 之上按拓扑顺序应用。

‘基本提交’ 显示为 "base-commit: ",后面是提交对象名称的 40-hex。 ‘先决补丁’ 显示为 "prerequisite-patch-id: ",后面是 40-hex 的 "补丁ID",这个 ID 可以通过 git patch-id --stable 命令来获得。

想象一下,在公开提交的 P 之上,你应用了别人的知名补丁 X、Y 和 Z,然后建立了你的三套补丁系列 A、B、C,历史会是这样:

使用 git format-patch --base=P -3 C(或其变体,例如使用 --cover-letter 或使用 Z...C 代替 -3 C 来指定范围),基础树信息块会显示在命令输出的第一个信息(第一个补丁,或封面信)的末尾,像这样:

对于非线性拓扑结构,如

你也可以使用 git format-patch --base=P -3 C 来生成 A、B 和 C 的补丁,P、X、Y、Z 的标识符被附加在第一条信息的末尾。

如果在 cmdline 中设置 --base=auto,它将自动计算基础提交,作为远程跟踪分支和 cmdline 中指定的修订范围的提示提交的合并基础。 对于本地分支,在使用此选项之前,需要通过 git branch --set-upstream-to 使其跟踪远程分支。

• 提取 R1 和 R2 修订版之间的提交,并用 "git am" 将其应用于当前分支之上,以拣选它们:

  $ git format-patch -k --stdout R1..R2 | git am -3 -k

• 提取所有在当前分支但不在原生分支中的提交:

  $ git format-patch origin

  每次提交都会在当前目录下创建一个单独的文件。

• 提取自项目开始以来所有导致 origin 的提交:

  $ git format-patch --root origin

• 与前者相同:

  $ git format-patch -M -B origin

  此外,它还能智能地检测和处理重命名和完全重写,以产生重命名补丁。 重命名补丁减少了文本输出的数量,一般来说,它更容易审查。 注意,非 Git 的 "补丁" 程序不会理解重命名补丁,所以只有当你知道收件人使用 Git 来应用你的补丁时才会使用它。

• 从当前分支中提取三个最重要的提交,并将其格式化为可发送电子邮件的补丁:

  $ git format-patch -3

请注意,format-patch 将从输出中省略合并提交,即使它们是请求范围的一部分。一个简单的 "补丁" 并不包括足够的信息让接收端重现同一个合并提交。

git-am[1], git-send-email[1]

属于 git[1] 文档