Git: Add a patch to an existing patch series

Question

Say I have a patch series that looks as follows:

0000-cover-letter.patch
0001-Patch1.patch
0002-Patch2.patch

Now I would like to add 0003-Patch3.patch to be part of that series.

I could do the following:

git format-patch HEAD~1 --start-number 3

However that won't work because the cover-letter patch will not be updated.

Is there a way to do one of the following, which kind of achieve the same goal:

• Add a patch to an existing series and have the cover-letter updated automatically
• Generate a cover letter on an existing list of patches without changing them though

P.S: Re-generating the entire series(HEAD~3) is not option here because when the first patches were generated I edited them with a description of the patch that would be erased if I re-generate from scratch.

Answer 1

Your desire to manually add new patches to a series suggests to me that you should improve your patch series workflow.

Ideally, creating a new set of patches should be so streamlined that you won’t want to fiddle with more things than you need.

Storing the cover letter

The cover letter should be stored somewhere. Two options out of an infinity:

• Store it as the first commit on your branch in an “empty” (no tree changes) commit
  • So it’s stored in the commit message
• Store it in a git-notes(1) message somewhere (the first commit?)

Storing free-form comments

You can store comments on patches, i.e. text that will neither be part of the commit message nor the patch proper. They go between the --- separator and the beginning of the diff.

Say someone on a previous review asked you to do X on that commit (err, patch). So you want to note that like this:

---
Note: I was asked by Timothy to do X in <link>

You can do that by creating a note on that commit:

git notes edit

With a message like the above. Which will be stored as:

---
Notes:
    I was asked by Timothy to do X in <link>

Minimal changes to the output of git patch-format

It seems that you (ideally) want to limit your post-patch format invocation work to editing the subject and body of your cover letter. And if you store that somewhere then it’s mostly just a question of copy–paste.

Answer 2

With Git 2.43 (Q4 2023), "git format-patch"^(man) learns a way to feed cover letter description, that (1) can be used on detached HEAD where there is no branch description available, and (2) also can override the branch description if there is one.

See commit 67f4b36 (21 Aug 2023) by Oswald Buddenhagen (ossilator).
^{(Merged by Junio C Hamano -- gitster -- in commit 3b4e395, 01 Sep 2023)}

format-patch: add --description-file option

^{Signed-off-by: Oswald Buddenhagen}

This patch makes it possible to directly feed a branch description to derive the cover letter from.
The use case is formatting dynamically created temporary commits which are not referenced anywhere.

The most obvious alternative would be creating a temporary branch and setting a description on it, but that doesn't seem particularly elegant.

git format-patch now includes in its man page:

--description-file=<file>

Use the contents of instead of the branch's description for generating the cover letter.

That means you now have an alternative to update the cover-letter: create a file with the content of 0000-cover-letter.patch, that you update to include the third patch.

Then a git format-patch --description-file=<file> would update your description of the patch with the right content.