(most of this is from the main commit with some elaboration in parts)
Teach git-format-patch(1) `--header-cmd` (with negation) and the
accompanying config variable `format.headerCmd` which allows the user to
add extra headers per-patch.
§ Motivation
format-patch knows `--add-header`. However, that seems most useful for
series-wide headers; you cannot really control what the header is like
per patch or specifically for the cover letter. To that end, teach
format-patch a new option which runs a command that has access to the
hash of the current commit (if it is a code patch) and the patch count
which is used for the patch files that this command outputs. Also
include an environment variable which tells the version of this API so
that the command can detect and error out in case the API changes.
This is inspired by `--header-cmd` of git-send-email(1).
§ Discussion
One may already get the commit hash from the commit by looking at the message id created by format-patch:
Message-ID: <48c517ffb3dce2188aba5f0a2c1f4f9dc8df59f0.1709840255.git.code@xxxxxxxxxxxxxxx>
However that does not seem to be documented behavior, and relying on the
message id from various tools seems to have backfired before.[1]
It’s also more convenient to not have to parse any output from
format-patch.
One may also be interested in finding some information based on the
commit hash, not just simply to output the hash itself.
🔗 1: https://lore.kernel.org/git/20231106153214.s5abourejkuiwk64@xxxxxxxxxxxxxx/
For example, the command could output a header for the current commit as
well as another header for the previously-published commits:
X-Commit-Hash: 97b53c04894578b23d0c650f69885f734699afc7
X-Previous-Commits:
4ad5d4190649dcb5f26c73a6f15ab731891b9dfd
d275d1d179b90592ddd7b5da2ae4573b3f7a37b7
402b7937951073466bf4527caffd38175391c7da
One can imagine that (1) these previous commit hashes were stored on every
commit rewrite and (2) the commits that had been published previously
were also stored. Then the command just needed the current commit hash
in order to look up this information.
Now interested parties can use this information to track where the
patches come from.
This information could of course be given between the
three-dash/three-hyphen line and the patch proper. However, the
hypoethetical project in question might prefer to use this part for
extra patch information written by the author and leave the above
information for tooling; this way the extra information does not need to
disturb the reader.
§ Demonstration
The above current/previous hash example is taken from:
https://lore.kernel.org/git/97b53c04894578b23d0c650f69885f734699afc7.1709670287.git.code@xxxxxxxxxxxxxxx/
§ CC
For patch “log-tree: take ownership of pointer”:
Cc: Jeff King <peff@xxxxxxxx>
For the git-send-email(1) `--header-cmd` topic:[1]
Cc: Maxim Cournoyer <maxim.cournoyer@xxxxxxxxx>
🔗 1: https://lore.kernel.org/git/20230423122744.4865-1-maxim.cournoyer@xxxxxxxxx/
Kristoffer Haugsbakk (3):
log-tree: take ownership of pointer
format-patch: teach `--header-cmd`
format-patch: check if header output looks valid
Documentation/config/format.txt | 5 ++
Documentation/git-format-patch.txt | 26 ++++++++++
builtin/log.c | 76 ++++++++++++++++++++++++++++++
log-tree.c | 18 ++++++-
revision.h | 2 +
t/t4014-format-patch.sh | 55 +++++++++++++++++++++
6 files changed, 180 insertions(+), 2 deletions(-)
--
2.44.0.169.gd259cac85a8
