git format-patch --cover-letter: Usage, Options & Common CI Errors

git format-patch --cover-letter prepends a 0000 summary patch that introduces the whole series.

When sending more than one patch, a cover letter (0000-cover-letter.patch) gives reviewers the high-level story before the individual commits. It is the standard for multi-patch submissions.

What it does

git format-patch --cover-letter generates the usual numbered patch files plus an extra 0000 cover letter containing the series shortlog and diffstat, ready for editing and sending.

Common usage

Terminal

git format-patch --cover-letter -3 -o out/
git format-patch --cover-letter origin/main
git format-patch --cover-letter --subject-prefix="PATCH v2" main..feature
# then edit out/0000-cover-letter.patch before sending

Options

Flag	What it does
--cover-letter	Emit a 0000 summary patch
-o <dir>	Write patches to a directory
--subject-prefix=<text>	Override the [PATCH] prefix
-v <n> / --reroll-count	Mark the series as version n
--thread	Add threading headers

Common errors in CI

A frequent slip is sending the cover letter with its placeholder subject still set to "* SUBJECT HERE *" - edit it before send-email. An empty or reversed range (e.g. feature..main) produces no patches; verify the range yields commits with git rev-list --count first.

Related guides

git format-patch: Usage, Options & Common CI Errorsgit format-patch turns commits into mailbox patch files for review or git am. Reference for -N, --stdout, --c… git send-email: Usage, Options & Common CI Errorsgit send-email mails patch files to reviewers over SMTP. Reference for --to, --cc, --smtp-server, and the aut… git request-pull: Usage, Options & Common CI Errorsgit request-pull generates a summary asking a maintainer to pull your changes. Reference for the start/url/en… git am: Usage, Options & Common CI Errorsgit am applies a mailbox of patches as commits, the receiving end of format-patch. Reference for --3way, --co…