[PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

Introduce the X-Change-ID header to emails prepared by git (i.e. via
format-patch, send-email). This allows tools which work with those
emails (e.g. patchwork, sourcehut) to meaningfully integrate with tools
that assign change IDs to commits.

With some follow-up work, this is also the first step towards ensuring
that those change IDs are preserved through from git-send-email to
git-am as a change moves through its review lifecycle.

Signed-off-by: Drew DeVault <drew@ddevault.org>
---
v2 is unchanged from v1.

One remark that occurs to me upon spinning v2 is that I'm not sure how
to test this behavior. There is no obvious way to cause git upstream to
produce a commit with a change-id -- presently these are only ever added
by third-party tools.

 pretty.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/pretty.c b/pretty.c
index 0bc8ad8a9a..70fba7b023 100644
--- a/pretty.c
+++ b/pretty.c
@@ -2045,7 +2045,7 @@ static void pp_header(struct pretty_print_context *pp,
 	int parents_shown = 0;
 
 	for (;;) {
-		const char *name, *line = *msg_p;
+		const char *name, *change_id, *line = *msg_p;
 		int linelen = get_one_line(*msg_p);
 
 		if (!linelen)
@@ -2089,6 +2089,11 @@ static void pp_header(struct pretty_print_context *pp,
 			strbuf_grow(sb, linelen + 80);
 			pp_user_info(pp, "Commit", sb, name, encoding);
 		}
+		if (skip_prefix(line, "change-id ", &change_id) &&
+		    cmit_fmt_is_mail(pp->fmt)) {
+			strbuf_addf(sb, "X-Change-ID: %.*s\n",
+				    linelen - 11, change_id);
+		}
 	}
 }
 
-- 
2.50.0

[PATCH v2 2/2] am: import X-Change-ID from email headers

[Drew DeVault]

When parsing emails formatted by git-send-email which include a
change-id commit header, the change-id is written as X-Change-ID to the
mail headers. This change causes git-am to grab the X-Change-ID email
header and write it to the commit header as change-id.

This completes the loop to ensure that sending and receiving patches via
email preserves the change-id header, if present.

Signed-off-by: Drew DeVault <drew@ddevault.org>
---
I'm pretty sure I got all of the lifecycle details including --resume
correct, but I would appreciate a second set of eyes.

Also not sure how to test this one, though this time it's less because
of any fundamental limitations and has more to do with me not really
understanding the test suite design. Perfectly acceptable for reviewers
to insist on a v3 which adds the necessary tests but I will wait to
endure that headache until some more discussion lands on this proposal
in general.

 builtin/am.c | 46 ++++++++++++++++++++++++++++++++++++++++++----
 mailinfo.c   |  4 +++-
 2 files changed, 45 insertions(+), 5 deletions(-)

diff --git a/builtin/am.c b/builtin/am.c
index a800003340..04cc9ef581 100644
--- a/builtin/am.c
+++ b/builtin/am.c
@@ -119,6 +119,7 @@ struct am_state {
 	char *author_name;
 	char *author_email;
 	char *author_date;
+	char *change_id;
 	char *msg;
 	size_t msg_len;
 
@@ -186,6 +187,7 @@ static void am_state_release(struct am_state *state)
 	free(state->author_name);
 	free(state->author_email);
 	free(state->author_date);
+	free(state->change_id);
 	free(state->msg);
 	strvec_clear(&state->git_apply_opts);
 }
@@ -408,6 +410,11 @@ static void am_load(struct am_state *state)
 
 	read_commit_msg(state);
 
+	if (read_state_file(&sb, state, "change-id", 1) != -1) {
+		assert(!state->change_id);
+		state->change_id = strbuf_detach(&sb, NULL);
+	}
+
 	if (read_state_file(&sb, state, "original-commit", 1) < 0)
 		oidclr(&state->orig_commit, the_repository->hash_algo);
 	else if (get_oid_hex(sb.buf, &state->orig_commit) < 0)
@@ -1119,11 +1126,13 @@ static void am_next(struct am_state *state)
 	FREE_AND_NULL(state->author_name);
 	FREE_AND_NULL(state->author_email);
 	FREE_AND_NULL(state->author_date);
+	FREE_AND_NULL(state->change_id);
 	FREE_AND_NULL(state->msg);
 	state->msg_len = 0;
 
 	unlink(am_path(state, "author-script"));
 	unlink(am_path(state, "final-commit"));
+	unlink(am_path(state, "change-id"));
 
 	oidclr(&state->orig_commit, the_repository->hash_algo);
 	unlink(am_path(state, "original-commit"));
@@ -1210,6 +1219,7 @@ static int parse_mail(struct am_state *state, const char *mail)
 	struct strbuf author_name = STRBUF_INIT;
 	struct strbuf author_date = STRBUF_INIT;
 	struct strbuf author_email = STRBUF_INIT;
+	struct strbuf change_id = STRBUF_INIT;
 	int ret = 0;
 	struct mailinfo mi;
 
@@ -1288,6 +1298,8 @@ static int parse_mail(struct am_state *state, const char *mail)
 			strbuf_addstr(&author_email, x);
 		else if (skip_prefix(sb.buf, "Date: ", &x))
 			strbuf_addstr(&author_date, x);
+		else if (skip_prefix(sb.buf, "X-Change-ID: ", &x))
+			strbuf_addstr(&change_id, x);
 	}
 	fclose(fp);
 
@@ -1310,6 +1322,11 @@ static int parse_mail(struct am_state *state, const char *mail)
 	assert(!state->author_date);
 	state->author_date = strbuf_detach(&author_date, NULL);
 
+	if (change_id.len) {
+		assert(!state->change_id);
+		state->change_id = strbuf_detach(&change_id, NULL);
+	}
+
 	assert(!state->msg);
 	state->msg = strbuf_detach(&msg, &state->msg_len);
 
@@ -1318,6 +1335,7 @@ static int parse_mail(struct am_state *state, const char *mail)
 	strbuf_release(&author_date);
 	strbuf_release(&author_email);
 	strbuf_release(&author_name);
+	strbuf_release(&change_id);
 	strbuf_release(&sb);
 	clear_mailinfo(&mi);
 	return ret;
@@ -1345,13 +1363,14 @@ static int get_mail_commit_oid(struct object_id *commit_id, const char *mail)
 }
 
 /**
- * Sets state->msg, state->author_name, state->author_email, state->author_date
- * to the commit's respective info.
+ * Sets state->msg, state->author_name, state->author_email, state->author_date,
+ * and state->change_id to the commit's respective info.
  */
 static void get_commit_info(struct am_state *state, struct commit *commit)
 {
-	const char *buffer, *ident_line, *msg;
+	const char *buffer, *ident_line, *change_id, *msg;
 	size_t ident_len;
+	size_t change_id_len;
 	struct ident_split id;
 
 	buffer = repo_logmsg_reencode(the_repository, commit, NULL,
@@ -1381,6 +1400,12 @@ static void get_commit_info(struct am_state *state, struct commit *commit)
 	assert(!state->author_date);
 	state->author_date = xstrdup(show_ident_date(&id, DATE_MODE(NORMAL)));
 
+	change_id = find_commit_header(buffer, "change-id", &change_id_len);
+	if (change_id && change_id_len) {
+		assert(!state->change_id);
+		state->change_id = xmemdupz(change_id, change_id_len);
+	}
+
 	assert(!state->msg);
 	msg = strstr(buffer, "\n\n");
 	if (!msg)
@@ -1668,6 +1693,8 @@ static void do_commit(const struct am_state *state)
 	struct commit_list *parents = NULL;
 	const char *reflog_msg, *author, *committer = NULL;
 	struct strbuf sb = STRBUF_INIT;
+	struct commit_extra_header change_id_hdr = {0};
+	struct commit_extra_header *extra = NULL;
 
 	if (!state->no_verify && run_hooks(the_repository, "pre-applypatch"))
 		exit(1);
@@ -1699,9 +1726,16 @@ static void do_commit(const struct am_state *state)
 							 : state->author_date,
 				      IDENT_STRICT);
 
+	if (state->change_id && strlen(state->change_id) != 0) {
+		change_id_hdr.key = "change-id";
+		change_id_hdr.value = state->change_id;
+		change_id_hdr.len = strlen(state->change_id);
+		extra = &change_id_hdr;
+	}
+
 	if (commit_tree_extended(state->msg, state->msg_len, &tree, parents,
 				 &commit, author, committer, state->sign_commit,
-				 NULL))
+				 extra))
 		die(_("failed to write commit object"));
 
 	reflog_msg = getenv("GIT_REFLOG_ACTION");
@@ -1853,6 +1887,10 @@ static void am_run(struct am_state *state, int resume)
 
 			write_author_script(state);
 			write_commit_msg(state);
+
+			if (state->change_id)
+				write_state_text(state, "change-id",
+						 state->change_id);
 		}
 
 		if (state->interactive && do_interactive(state))
diff --git a/mailinfo.c b/mailinfo.c
index b4e815b2d8..46d68a03d6 100644
--- a/mailinfo.c
+++ b/mailinfo.c
@@ -351,7 +351,7 @@ static void cleanup_subject(struct mailinfo *mi, struct strbuf *subject)
 }
 
 static const char * const header[] = {
-	"From", "Subject", "Date",
+	"From", "Subject", "Date", "X-Change-ID",
 };
 
 static inline int skip_header(const struct strbuf *line, const char *hdr,
@@ -1183,6 +1183,8 @@ static void handle_info(struct mailinfo *mi)
 			handle_from(mi, hdr);
 			fprintf(mi->output, "Author: %s\n", mi->name.buf);
 			fprintf(mi->output, "Email: %s\n", mi->email.buf);
+		} else if (!strcmp(header[i], "X-Change-ID")) {
+			output_header_lines(mi->output, "X-Change-ID", hdr);
 		} else {
 			cleanup_space(hdr);
 			fprintf(mi->output, "%s: %s\n", header[i], hdr->buf);
-- 
2.50.0

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Jeff King]

On Thu, Jul 03, 2025 at 01:29:51PM +0200, Drew DeVault wrote:

> One remark that occurs to me upon spinning v2 is that I'm not sure how
> to test this behavior. There is no obvious way to cause git upstream to
> produce a commit with a change-id -- presently these are only ever added
> by third-party tools.

I don't have any opinion on the feature itself, but the plumbing way to
do it would perhaps be:

  # make some vanilla commit...
  git commit -m foo &&

  # make a new variant with the change id
  commit=$(
    git cat-file commit HEAD |
    perl -lpe 'print "change-id foo" unless length' |
    git hash-object -w --stdin -t commit
  ) &&

  # replace the old one
  git update-ref HEAD $commit

which would be enough for Git's test suite. If this is something that
other third-party tools are going to start adding, it might be worth
adding some tests to Git's suite anyway to make sure it is handled
correctly. (I didn't follow the discussion on whether a new commit
header was something the Git project wanted to endorse, versus sticking
it in a trailer line, so don't take this as either a positive or
negative on the approach).

-Peff

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 597 bytes --]

On Sun Jul 6, 2025 at 5:37 AM CEST, Jeff King wrote:
> I don't have any opinion on the feature itself, but the plumbing way to
> do it would perhaps be:
>
>   # make some vanilla commit...
>   git commit -m foo &&
>
>   # make a new variant with the change id
>   commit=$(
>     git cat-file commit HEAD |
>     perl -lpe 'print "change-id foo" unless length' |
>     git hash-object -w --stdin -t commit
>   ) &&
>
>   # replace the old one
>   git update-ref HEAD $commit

Thanks! I'll incorporate this into the tests in the next patch version
after some further discussion.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Aditya Garg]

On 03-07-2025 04:59 pm, Drew DeVault wrote:
> Introduce the X-Change-ID header to emails prepared by git (i.e. via
> format-patch, send-email). This allows tools which work with those
> emails (e.g. patchwork, sourcehut) to meaningfully integrate with tools
> that assign change IDs to commits.
> 
> With some follow-up work, this is also the first step towards ensuring
> that those change IDs are preserved through from git-send-email to
> git-am as a change moves through its review lifecycle.
> 
> Signed-off-by: Drew DeVault <drew@ddevault.org>
> ---
> v2 is unchanged from v1.
> 
> One remark that occurs to me upon spinning v2 is that I'm not sure how
> to test this behavior. There is no obvious way to cause git upstream to
> produce a commit with a change-id -- presently these are only ever added
> by third-party tools.

I don't think we should add it to email headers. There are many email providers
which do not allow custom headers in the emails. For example if you are using
protonmail bridge or any third party protonmail client, the headers are not
preserved. Similarly, if you are using MS Graph to send emails, headers are
again not preserved. We should also consider cases when people use Thunderbird,
Mutt or something similar to send emails, rather than git send-email.

The headers IMO should include the standard ones like From, Subject etc.
Custom headers should be a part of body, just like we do Signed-off-by, Link etc.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 1742 bytes --]

On Sun Jul 6, 2025 at 8:20 AM CEST, Aditya Garg wrote:
> I don't think we should add it to email headers. There are many email providers
> which do not allow custom headers in the emails. For example if you are using
> protonmail bridge or any third party protonmail client, the headers are not
> preserved. Similarly, if you are using MS Graph to send emails, headers are
> again not preserved. We should also consider cases when people use Thunderbird,
> Mutt or something similar to send emails, rather than git send-email.

As far as I can tell, this isn't actually true. I looked into it and
protonmail and MS Graph both seem to support custom headers. I have also
verified that mutt will preserve the header when you edit the email
normally with mutt -H. If you're sending an email with Thunderbird, none
of these things are preserved (including From, Subject, etc), and the
best you can hope for is attaching the patch, in which case X-Change-ID
will be preserved unmolested.

Moreover, if the change-id header is lost, it's not the end of the
world, it just degrades to the present-day state of affairs, in which
you cannot use it to associate patches with prior versions.

> The headers IMO should include the standard ones like From, Subject etc.
> Custom headers should be a part of body, just like we do Signed-off-by, Link etc.

Trailers and headers are different. The main point of the change-id
discussion earlier on this list was to avoid adding trailers.

I also suspect that if we added this as an "inbody header" that older
git implementations would ingest the X-Change-ID header into the commit
message, which is not a desirable behavior.

IMO the right way forward is to use a mail header.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Junio C Hamano]

"Drew DeVault" <drew@ddevault.org> writes:

> Trailers and headers are different. The main point of the change-id
> discussion earlier on this list was to avoid adding trailers.

It sounds like this "avoiding trailers" is the root cause of the
problem.  If change-id is something not precious as you earlier
said, having various operations lose it by design or by accident
may not hurt a lot, but then doesn't it make it harder to notice
by hiding it in a non-standard commit header field?  There is no
easy way to tell "git log --format" to show such a custom header,
you'd need to tell amend, rebase, cherry-pick, etc. to carry the
custom header forward (or not---have all the change-id loving
communities agreed on when to propagate and when not to?).

Keeping it as one of the trailer fields will always make it
available [*], propagate existing one by default with any existing
tool, and because it is in the same place as log message, the user
can easily remove it if it is not appropriate to keep it.

    Side note: [*] Unless you are doing "log --oneline", that is,
    but I'd say at that point you are hiding it deliberately.

> I also suspect that if we added this as an "inbody header" that older
> git implementations would ingest the X-Change-ID header into the commit
> message, which is not a desirable behavior.

Of course not.  If the thing is a trailer, you do not even have to
worry about such sillyness caused by adding it as a new in-body
header.

> IMO the right way forward is to use a mail header.

No.  In the change-id case, trailer is the right way to go.

Having said all that, you may sense that I am not all that impressed
by the previous rounds of dicsussions arguing for recording
change-id as an extra non-standard commit header.  We should think
twice or more before making anything that structurally does not
cause Git to behave differently taking advantage of the information
recorded there an extra commit header field.

But after thinking thrice, we may find a set of good pieces of
information that should be added as new commit header that are
structurally more meaningful, and there will be times when we need
to convey them over e-mailed workflow to allow patch recipient not
to lose such information.

In such a case, I fully agree that embedding in an e-mail header
would be the way to go.

I would suggest a lot more generic implementation to solve it once
and for all.  How about doing it more like this:

   "git format-patch --extra-headers" grabs all extra headers
   (i.e. those that are not the bog-standard "tree", "parent",
   "author", "committer") and emit these

    X-git-extra-commit-header: encoding=iso8859-1
    X-git-extra-commit-header: frotz=nitfol

   next to "Subject:", etc.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> IMO the right way forward is to use a mail header.
>
> No.  In the change-id case, trailer is the right way to go.
> ...
> But after thinking thrice, we may find a set of good pieces of
> information that should be added as new commit header ...
> ... and there will be times when we need
> to convey them over e-mailed workflow to allow patch recipient not
> to lose such information.

Or a third-party software may add a new commit header without
gauging and waiting for the community consensus anyway, which may or
may not have much structural meaning, and then we may want to extract
that piece of information hidden in the commit header out, because
it was not written as trailer (in which case there wouldn't have
needed any extra effort to extract it in the first place).

This part can use a bit of clarification.

My endorsement below to use an extra e-mail header applies when some
commit objects ended up with extra non-standard headers holding
pieces of information that we want to send as part of a patch,
whether it is a good idea or a bad idea to place that particular
kind of information in a commit header.  And the question is "Now,
what is the best way to transfer it over a patched e-mail?"

If it were a good idea to place that particular kind of information
in a header, that is of course an effort worth investing in.

If it were a horrible idea to place it in a header, it still is
worth investing in an effort to give ourselves a way to salvage such
information out of the header, even though we wouldn't have needed
such extra tool if they didn't hide it in the header.

But once a generic mechanism is written, then Git does not have to
behave differently if an extra commit header is something a more
recent versions of Git tools started using after the idea gained
community consensus, or a third-party software unilaterally added
without gauging or waiting for community consensus.  The same single
mechanism can be used to extract the information and carry it in
e-mails, and mailinfo can be told to extract it out.  It can be left
up to the consumer after mailinfo disects the pieces of information
out of the e-mail.

> In such a case, I fully agree that embedding in an e-mail header
> would be the way to go.
>
> I would suggest a lot more generic implementation to solve it once
> and for all.  How about doing it more like this:
>
>    "git format-patch --extra-headers" grabs all extra headers
>    (i.e. those that are not the bog-standard "tree", "parent",
>    "author", "committer") and emit these
>
>     X-git-extra-commit-header: encoding=iso8859-1
>     X-git-extra-commit-header: frotz=nitfol
>
>    next to "Subject:", etc.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Martin von Zweigbergk]

On Sun, 6 Jul 2025 at 22:53, Junio C Hamano <gitster@pobox.com> wrote:
>
> Junio C Hamano <gitster@pobox.com> writes:
>
> >> IMO the right way forward is to use a mail header.
> >
> > No.  In the change-id case, trailer is the right way to go.
> > ...
> > But after thinking thrice, we may find a set of good pieces of
> > information that should be added as new commit header ...
> > ... and there will be times when we need
> > to convey them over e-mailed workflow to allow patch recipient not
> > to lose such information.
>
> Or a third-party software may add a new commit header without
> gauging and waiting for the community consensus anyway, which may or
> may not have much structural meaning, and then we may want to extract
> that piece of information hidden in the commit header out, because
> it was not written as trailer (in which case there wouldn't have
> needed any extra effort to extract it in the first place).
>
> This part can use a bit of clarification.
>
> My endorsement below to use an extra e-mail header applies when some
> commit objects ended up with extra non-standard headers holding
> pieces of information that we want to send as part of a patch,
> whether it is a good idea or a bad idea to place that particular
> kind of information in a commit header.  And the question is "Now,
> what is the best way to transfer it over a patched e-mail?"
>
> If it were a good idea to place that particular kind of information
> in a header, that is of course an effort worth investing in.
>
> If it were a horrible idea to place it in a header, it still is
> worth investing in an effort to give ourselves a way to salvage such
> information out of the header, even though we wouldn't have needed
> such extra tool if they didn't hide it in the header.

+1

Does this also apply to commit signatures? I just created a signed
commit and checked what `git format-patch` produces. I was a bit
surprised to see that it doesn't seem to show up anywhere. Is it not
supported or did I miss some flag or config?

>
> But once a generic mechanism is written, then Git does not have to
> behave differently if an extra commit header is something a more
> recent versions of Git tools started using after the idea gained
> community consensus, or a third-party software unilaterally added
> without gauging or waiting for community consensus.  The same single
> mechanism can be used to extract the information and carry it in
> e-mails, and mailinfo can be told to extract it out.  It can be left
> up to the consumer after mailinfo disects the pieces of information
> out of the e-mail.
>
> > In such a case, I fully agree that embedding in an e-mail header
> > would be the way to go.


Is it another option to put it somewhere in the body? Could we fit
additional headers (e.g. signatures and third-party ones) somewhere
between the `---` line and the additional diff? Or how about after the
final `--` line? I haven't checked the specification. I just saw these
lines in the `git format-patch` output.

> >
> > I would suggest a lot more generic implementation to solve it once
> > and for all.  How about doing it more like this:
> >
> >    "git format-patch --extra-headers" grabs all extra headers
> >    (i.e. those that are not the bog-standard "tree", "parent",
> >    "author", "committer") and emit these
> >
> >     X-git-extra-commit-header: encoding=iso8859-1
> >     X-git-extra-commit-header: frotz=nitfol
> >
> >    next to "Subject:", etc.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Martin von Zweigbergk]

On Sun, 6 Jul 2025 at 23:57, Martin von Zweigbergk
<martinvonz@google.com> wrote:
>
> On Sun, 6 Jul 2025 at 22:53, Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Junio C Hamano <gitster@pobox.com> writes:
> >
> > >> IMO the right way forward is to use a mail header.
> > >
> > > No.  In the change-id case, trailer is the right way to go.
> > > ...
> > > But after thinking thrice, we may find a set of good pieces of
> > > information that should be added as new commit header ...
> > > ... and there will be times when we need
> > > to convey them over e-mailed workflow to allow patch recipient not
> > > to lose such information.
> >
> > Or a third-party software may add a new commit header without
> > gauging and waiting for the community consensus anyway, which may or
> > may not have much structural meaning, and then we may want to extract
> > that piece of information hidden in the commit header out, because
> > it was not written as trailer (in which case there wouldn't have
> > needed any extra effort to extract it in the first place).
> >
> > This part can use a bit of clarification.
> >
> > My endorsement below to use an extra e-mail header applies when some
> > commit objects ended up with extra non-standard headers holding
> > pieces of information that we want to send as part of a patch,
> > whether it is a good idea or a bad idea to place that particular
> > kind of information in a commit header.  And the question is "Now,
> > what is the best way to transfer it over a patched e-mail?"
> >
> > If it were a good idea to place that particular kind of information
> > in a header, that is of course an effort worth investing in.
> >
> > If it were a horrible idea to place it in a header, it still is
> > worth investing in an effort to give ourselves a way to salvage such
> > information out of the header, even though we wouldn't have needed
> > such extra tool if they didn't hide it in the header.
>
> +1
>
> Does this also apply to commit signatures? I just created a signed
> commit and checked what `git format-patch` produces. I was a bit
> surprised to see that it doesn't seem to show up anywhere. Is it not
> supported or did I miss some flag or config?

Oh, perhaps they're deliberately not included because the commit
timestamp is not included in the patch so the signatures would be
invalid even if the patch was applied to the right parent?

>
> >
> > But once a generic mechanism is written, then Git does not have to
> > behave differently if an extra commit header is something a more
> > recent versions of Git tools started using after the idea gained
> > community consensus, or a third-party software unilaterally added
> > without gauging or waiting for community consensus.  The same single
> > mechanism can be used to extract the information and carry it in
> > e-mails, and mailinfo can be told to extract it out.  It can be left
> > up to the consumer after mailinfo disects the pieces of information
> > out of the e-mail.
> >
> > > In such a case, I fully agree that embedding in an e-mail header
> > > would be the way to go.
>
>
> Is it another option to put it somewhere in the body? Could we fit
> additional headers (e.g. signatures and third-party ones) somewhere
> between the `---` line and the additional diff? Or how about after the
> final `--` line? I haven't checked the specification. I just saw these
> lines in the `git format-patch` output.
>
> > >
> > > I would suggest a lot more generic implementation to solve it once
> > > and for all.  How about doing it more like this:
> > >
> > >    "git format-patch --extra-headers" grabs all extra headers
> > >    (i.e. those that are not the bog-standard "tree", "parent",
> > >    "author", "committer") and emit these
> > >
> > >     X-git-extra-commit-header: encoding=iso8859-1
> > >     X-git-extra-commit-header: frotz=nitfol
> > >
> > >    next to "Subject:", etc.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Junio C Hamano]

Martin von Zweigbergk <martinvonz@google.com> writes:

>> Does this also apply to commit signatures? I just created a signed
>> commit and checked what `git format-patch` produces. I was a bit
>> surprised to see that it doesn't seem to show up anywhere. Is it not
>> supported or did I miss some flag or config?
>
> Oh, perhaps they're deliberately not included because the commit
> timestamp is not included in the patch so the signatures would be
> invalid even if the patch was applied to the right parent?

An excellent observation.

Yes, it was a deliberate design decision to omit cryptographic
signature(s) on the commit object itself, based on the assumption
that the primary motivation behind e-mailed patch workflow is to
convey the essense of the change in a readable form, while allowing
minor modifications to both proposed log message and the diff
while/before applying it, and on top of a state that is slightly
different from the state the patch was taken from.  It was out of
scope to reproduce the history bit-for-bit identically.  Besides the
author timestamp, the committer timestamp and identity (the
recipient of an e-mailed patch is likely to be different from the
sender), "git am -s --whitespace=fix" would be a common thing a
recipient would want to clean up the patch sent over the e-mail
anyway.

But with many past design decisions, the underlying assumptions are
worth reevaluating from time to time.  They may have become
outdated, or new use cases may have emerged that the tools are good
fit to support them with enhancements.

Instead of only limiting to convey the essense in a readable form,
we could also aim to support the exact bit-for-bit reproducibility
under certain conditions, e.g., the recipient has exact objects
named by the "tree" and "parent" headers in the original commit
object.  Think of it as an e-mailable bundle file whose contents can
be inspected before unbundling.

And for such a "inspectable and e-mailable bundle that can be used
to fully reproduce the state bit-for-bit", ...

>> Is it another option to put it somewhere in the body? Could we fit
>> additional headers (e.g. signatures and third-party ones) somewhere
>> between the `---` line and the additional diff? Or how about after the
>> final `--` line? I haven't checked the specification. I just saw these
>> lines in the `git format-patch` output.

... I think a far simpler and more robust approach is to dump the
whole "git cat-file commit" output somewhere in the e-mail, not
limiting ourselves to "extra" headers, in some "less susceptible to
corruption" form (e.g. base85).  The standard headers like "tree"
and "parent" are good thing to have if a new requirement is to allow
exact reproducibility when the objects the patch was based on exist,
and the raw commit message with trailing whitespaces would be needed
in a protected form as well, since e-mailed patches can lose them
during transit.

And below the three-dash line as you suggested is one good place to
keep such an extra piece of information.

Or the "cat-file commit" dump can be on an extra e-mail header.

Some e-mail environments will deliberately hide anything after the
final "-- " (signature) line, and saving a message may even lose it,
so it is not a good place to store anything that is worth feeding
"git am" with.

Thanks.

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 1372 bytes --]

On Mon Jul 7, 2025 at 8:57 AM CEST, Martin von Zweigbergk wrote:
> +1
>
> Does this also apply to commit signatures? I just created a signed
> commit and checked what `git format-patch` produces. I was a bit
> surprised to see that it doesn't seem to show up anywhere. Is it not
> supported or did I miss some flag or config?

There is, to the best of my understanding, no serious effort being made
towards causing commit signatures to survive the git-format-patch/git-am
process. There's also some confusion that often occurs here because
commit signatures are unrelated to PGP signatures and it is not possible
to make either system meaningfully aware of the other.

>> > In such a case, I fully agree that embedding in an e-mail header
>> > would be the way to go.
>
> Is it another option to put it somewhere in the body? Could we fit
> additional headers (e.g. signatures and third-party ones) somewhere
> between the `---` line and the additional diff? Or how about after the
> final `--` line? I haven't checked the specification. I just saw these
> lines in the `git format-patch` output.

I really think that it would be much wiser of us to put it in the email
headers, which already exist as a well-defined structured data format
for this purpose, rather than introduce something like commit trailers
to the timely commentary section.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 1530 bytes --]

On Mon Jul 7, 2025 at 3:30 AM CEST, Junio C Hamano wrote:
> I would suggest a lot more generic implementation to solve it once
> and for all.  How about doing it more like this:
>
>    "git format-patch --extra-headers" grabs all extra headers
>    (i.e. those that are not the bog-standard "tree", "parent",
>    "author", "committer") and emit these
>
>     X-git-extra-commit-header: encoding=iso8859-1
>     X-git-extra-commit-header: frotz=nitfol
>
>    next to "Subject:", etc.

+1. I particularly like how this approach throws out a bunch of arguing
over the utility of the specific use-case -- clever :)

Do you think there's any reason not to throw all extra headers into
X-git-extra-commit-header (or whatever) unconditionally? Does it need to
be behind a flag or config option? If some tool added the extra commit
headers, they presumably have a good reason for doing so and we ought to
encode that information so we can reproduce the commit properly, same as
we would with the rest of the commit headers.

I suppose there is a scenario where this breaks something because
someone has a poorly thought-out string munging parser for git
format-patch output that will barf upon encountering the unexpected, or
some mail provider rejects emails rather than silently dropping headers
it doesn't like, but both possibilities seem remote -- especially when
considering that these hypothetical edge cases have to be combined with
a use-case which deploys extra commit headers in the first place.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Remo Senekowitsch]

On Thu Jul 3, 2025 at 1:29 PM CEST, Drew DeVault wrote:
> Introduce the X-Change-ID header to emails prepared by git (i.e. via
> format-patch, send-email). This allows tools which work with those
> emails (e.g. patchwork, sourcehut) to meaningfully integrate with tools
> that assign change IDs to commits.
>
> With some follow-up work, this is also the first step towards ensuring
> that those change IDs are preserved through from git-send-email to
> git-am as a change moves through its review lifecycle.

Hi Drew,

Do you intend to keep working on this by any chance? I'm writing a code
review tool that relies on Jujutsu's change-id header for its "killer
feature". It will also support different code review platforms as
backends, including GitHub, mailing lists and more. As long as mailing
lists do not preserve the change-id header though, users of them will
fundamentally have a degraded experience.

That is to say, your efforts here are much appreciated. :-)

Best,
Remo

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 133 bytes --]

Hey Remo! I haven't gotten much actionable feedback on this patch yet,
so there's not much to do here but wait for more reviewers.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Junio C Hamano]

"Drew DeVault" <drew@ddevault.org> writes:

> I haven't gotten much actionable feedback on this patch yet,
> so there's not much to do here but wait for more reviewers.

For a topic that is older than 6 weeks, I am afraid that is a losing
strategy.  People who might have cared about the topic said all they
wanted to say, new people are less likely to discover the topic than
it was fresh, and unless you make an action (e.g., posting the "next
patch version" you mentioned in [*1*]), it is highly unlikely for
anything to happen while you are passive.  Even a small update that
addresses all the little feedback would serve as a "ping" to reignite
interests.

You seem to have liked the approach to generalize and encode all the
commit object headers (except for of course the object name and
author and committer ident, which already have place to be in the
format-patch output) on an e-mail header in [*2*].  That should be
sufficient for a small update that tries to reignite interests.


[References]

*1* https://lore.kernel.org/git/DB4WU136IYR2.3ELSGQUDD6QI8@ddevault.org/
*2* https://lore.kernel.org/git/DB5MUUDPF6C0.3OR02N6JQB8H8@ddevault.org/

Re: [PATCH v2 1/2] pretty: add X-Change-ID to mail formats

[Drew DeVault]

[-- Attachment #1.1.1: Type: text/plain, Size: 1192 bytes --]

On Thu Aug 21, 2025 at 2:50 AM CEST, Junio C Hamano wrote:
> For a topic that is older than 6 weeks, I am afraid that is a losing
> strategy.  People who might have cared about the topic said all they
> wanted to say, new people are less likely to discover the topic than
> it was fresh, and unless you make an action (e.g., posting the "next
> patch version" you mentioned in [*1*]), it is highly unlikely for
> anything to happen while you are passive.  Even a small update that
> addresses all the little feedback would serve as a "ping" to reignite
> interests.
>
> You seem to have liked the approach to generalize and encode all the
> commit object headers (except for of course the object name and
> author and committer ident, which already have place to be in the
> format-patch output) on an e-mail header in [*2*].  That should be
> sufficient for a small update that tries to reignite interests.

Oh, of course. For some reason I had had the notion that I had already
written a v3 based on this feedback and it was awaiting further
comments. But in fact I have done no such thing. I'll put this back on
my todo list and get a v3 out in the foreseeable future.

[-- Attachment #1.2: 42F3F1862E3CC4B8.asc --]
[-- Type: application/pgp-keys, Size: 644 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

mDMEZ7Y9kxYJKwYBBAHaRw8BAQdA/pPy6X+nNL5T2QaJKEM08xN/Kz7wFTAZoH5Y
riV9x1m0IERyZXcgRGVWYXVsdCA8ZHJld0BkZGV2YXVsdC5vcmc+iJMEExYKADsC
GwMFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AWIQSftec33CWynY7sRpFC8/GG
LjzEuAUCZ7Y9wwAKCRBC8/GGLjzEuMEEAP9DH+1LgvTqZDLZ8babB5Cdp5y0ZW+Q
Tx78mh1L8jJd6gEAssmgsImcrZv4adP2UW5RU5BHCe9KUdx0DyV83QwlFAS4OARn
tj2TEgorBgEEAZdVAQUBAQdAGAH9dlaCONoXpmQgHoQgYI2tS+VM3mzU8I2PyVYQ
1GUDAQgHiHgEGBYKACACGwwWIQSftec33CWynY7sRpFC8/GGLjzEuAUCZ7Y91gAK
CRBC8/GGLjzEuHcnAP4yjOiM0yqkST6yXzDUWze7B9Im24F8HVx+wNqcDaDtcAD/
fKQhz0SCPiblO6lc7MFUvlaOz2v87UpUYRhzPdgQqwk=
=emrb
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]