git-format-patch

Create an auto-named .patch file for all the unpushed commits

$ git format-patch [origin]

$ git format-patch [revision_1]..[revision_2]

$ git format-patch -[n]

git format-patch [<options>] [<revision-range> | <commit>]

-o <dir> / --output-directory=<dir>
    Specifies the directory where the generated patch files should be stored. If not provided, patches are created in the current directory.

-<n>
    Formats the last <n> commits on the current branch as patches. For example, git format-patch -3 will create patches for the last three commits.

--stdout
    Prints the generated patches to standard output instead of creating individual files. This is useful for piping the output to other commands.

--subject-prefix=<prefix>
    Sets the prefix for the subject line of the patches (default is PATCH). For instance, --subject-prefix="RFC PATCH".

--cover-letter
    Generates an additional file (named 0000-*) serving as a cover letter for the entire patch series. This file contains the project's shortlog and can be edited to include an introduction or motivation for the series.

--attach
    Formats the patch as a base64 encoded attachment suitable for email clients. This is an alternative to the default inline patch format.

--numbered
    Ensures the patches are numbered sequentially (e.g., 0001-*, 0002-*). This is often the default behavior when generating multiple patches.

--start-number=<n>
    Specifies the starting number for the patch filenames. Useful when splitting a large series or resubmitting parts of it.

--thread
    Adds In-Reply-To and References headers to the emails, aiding in email client threading. This groups related patches in email clients.

--signature=<sig>
    Appends a Signed-off-by: line to the commit message with the specified signature. If <sig> is omitted, it defaults to the committer's name and email.

--ignore-submodules
    Ignores changes to submodules when generating patches. Useful if submodule changes are handled separately or irrelevant to the patch series.

git format-patch is a core Git command used to prepare patches from a specified range of Git commits. These patches are specifically formatted to be suitable for email submission, commonly to a mailing list, adhering to conventions that allow tools like git am to apply them cleanly. Each commit in the specified range is typically output as a separate, sequentially numbered file (e.g., 0001-Subject.patch, 0002-Another-Subject.patch).

The generated patch files include not only the diff of changes introduced by the commit but also essential metadata such as the commit message, author details, and commit date, all structured with appropriate email headers. This makes git format-patch an indispensable tool for projects, like the Linux kernel, that rely on a mailing list-centric development workflow. It offers extensive options to customize output filenames, subject prefixes, numbering, and to generate ancillary files like cover letters, ensuring flexibility for various submission requirements.

git format-patch is optimized for generating patches for email-based workflows, particularly for consumption by git am. While it generates standard diffs, its primary strength lies in adding necessary email headers and formatting to ensure smooth application by the recipient's Git tools. For applying patches locally, git apply or the general patch(1) command might be more direct, but git am is specifically designed to handle patches generated by format-patch.

Users should also be mindful of character encoding when dealing with non-ASCII commit messages or author names, and may need to use options like --encode-email-headers to ensure patches are correctly parsed by recipients across different systems.

Understanding common <revision-range> arguments is key to effectively using git format-patch:

1. Generate patches for the last N commits:
git format-patch -N
This creates N patch files for the N most recent commits on your current branch. For example, git format-patch -1 generates a patch for only the very last commit.

2. Generate patches between two points:
git format-patch <start-commit>..<end-commit>
This generates patches for all commits *after* <start-commit> *up to and including* <end-commit>. A common use case is git format-patch main..HEAD, which generates patches for all commits on your current branch that are not present on the main branch.

3. Generate patches for all commits on a specific branch not on another:
git format-patch <base-branch> <topic-branch>
This generates patches for all commits on <topic-branch> that are not reachable from <base-branch>.

4. Output to a specific directory:
git format-patch -o patches/ my_feature_branch..
This directs all generated patch files into the patches/ subdirectory, which is useful for organizing multiple patch series or preparing them for sending.

git format-patch has been a core component of Git since its early days, reflecting Git's origins in Linux kernel development, which heavily relies on email-based patch submissions for distributed collaboration. It provides the essential bridge between local Git repositories and development via mailing lists. Its evolution has focused on improving header formatting, supporting email threading (e.g., with --thread), and handling various edge cases related to large patch series and character encodings. It remains a stable, mature, and frequently used command in projects with email-centric workflows.

git-am(1), git-apply(1), git-diff(1), git-send-email(1), git-request-pull(1), patch(1)