git/Documentation/git-am.adoc, branch jch

Merge branch 'kh/doc-am-xref'

2026-04-13T20:54:57Z

Doc update. * kh/doc-am-xref: doc: am: correct to full --no-message-id doc: am: revert Message-ID trailer claim

doc: am: correct to full --no-message-id

2026-04-13T15:26:54Z

Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: am: revert Message-ID trailer claim

2026-04-13T15:26:43Z

I claimed in 3c18135b (doc: am: say that --message-id adds a trailer, 2026-02-09) that `git am --message-id` adds a Git trailer. But that isn’t the case; for the case of a commit message with a subject, body, and no trailer block: It just appends the line right after `paragraph`: Message-ID: It does work for two other cases though, namely subject-only and with an existing trailer block. This is at best an inconsistency and arguably a bug, but we’re at the trailing end of the release cycle now. So reverting the doc is safer than making msg-id act as a trailer, for now. Revert this hunk from commit 3c18135b except the only useful change (“Also use inline-verbatim for `Message-ID`”). Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

Merge branch 'kh/doc-am-xref'

2026-03-03T01:06:52Z

Doc update. * kh/doc-am-xref: doc: am: fill out hook discussion doc: am: add missing config am.messageId doc: am: say that --message-id adds a trailer doc: am: normalize git(1) command links

doc: add caveat about round-tripping format-patch

2026-02-12T22:37:56Z

git-format-patch(1) and git-am(1) deal with formatting commits as patches and applying them, respectively. Naturally they use a few delimiters to mark where the commit message ends. This can lead to surprising behavior when these delimiters are used in the commit message itself. git-format-patch(1) will accept any commit message and not warn or error about these delimiters being used.[1] Especially problematic is the presence of unindented diffs in the commit message; the patch machinery will naturally (since the commit message has ended) try to apply that diff and everything after it.[2] It is unclear whether any commands in this chain will learn to warn about this. One concern could be that users have learned to rely on the three-dash line rule to conveniently add extra-commit message information in the commit message, knowing that git-am(1) will ignore it.[4] All of this is covered already, technically. However, we should spell out the implications. † 1: There is also git-commit(1) to consider. However, making that command warn or error out over such delimiters would be disruptive to all Git users who never use email in their workflow. † 2: Recently patch(1) caused this issue for a project, but it was noted that git-am(1) has the same behavior[3] † 3: https://github.com/i3/i3/pull/6564#issuecomment-3858381425 † 4: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/ https://lore.kernel.org/git/V3_format-patch_caveats.354@msgid.xyz/ Reported-by: Matthias Beyer Reported-by: Christoph Anton Mitterer Reported-by: Matheus Tavares Reported-by: Chris Packham Helped-by: Jakob Haufe Helped-by: Phillip Wood Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: am: fill out hook discussion

2026-02-09T18:34:05Z

Document `--verify` and rephrase the `--[no-]verify` section to lead with the default, in imperative mood.[1] Historically it makes sense that only the negated forms are documented; they are all run by default and thus you only need to use hook options if you want to turn some of them off. But, beyond just desiring uniform documentation,[2] it’s very much possible to have, say, a Git alias with `--no-verify` that you might sometimes want to turn back on with the *positive* form. Also mention the options in the “Hooks” section and mention that `post-applypatch` cannot be skipped. † 1: See e.g. acffc5e9 (doc: convert git-remote to synopsis style, 2025-12-20) † 2: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/ Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: am: say that --message-id adds a trailer

2026-02-09T18:34:04Z

The option `--message-id` was added in a078f732 (git-am: add --message-id/--no-message-id, 2014-11-25) back when git-interpret- trailers(1) was relatively new. Let’s spell out that it is a trailer and link to the dedicated trailer command. Also use inline-verbatim for `Message-ID`. Also link to git-interpret-trailers(1) on `--signoff`. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: am: normalize git(1) command links

2026-02-09T18:34:04Z

There are many mentions of commands using inline-verbatim or emphasis ('). We just mention the command themselves, not specific invocations like `git am `. Let’s link to them instead. There are also many such mentions which then link to the command right afterwards. Simplify to just using a link. Also remove “see ” phrases where they have now already been mentioned. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

Merge branch 'kh/doc-committer-date-is-author-date'

2025-12-05T05:49:57Z

The "--committer-date-is-author-date" option of "git am/rebase" is a misguided one. The documentation is updated to discourage its use. * kh/doc-committer-date-is-author-date: doc: warn against --committer-date-is-author-date

doc: warn against --committer-date-is-author-date

2025-11-20T18:03:31Z

This option could create a commit history which violates the assumption that commits have non-decreasing commit timestamps. Warn against that in both git-am(1) and git-rebase(1). The genesis of this option is from git-am(1) and was added in 3f01ad66 (am: Add --committer-date-is-author-date option, 2009-01-22). The commit message doesn’t give us an example of a use case, but the thread starter does:[1] I've a big set of patches in a mbox file: there's sufficient info inside for git-am to work. Yet, each time I do import these, my sha1sums are changing because of different commit dates. I'd like to force the commit date to match the info/date from the time I received the email (and therefore always get back the right sha1sums). [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/ So the motivation was to treat git-am(1) as an import command that creates the same commit IDs. Putting aside the question of whether you should be using git-am(1) for importing commits, this approach is problematic: • you still need to apply the commits to the same base if you want the same hashes; and • you need the same committer. And if you expect the same committer, why is this person applying the same patches multiple times with the goal of making *identical* commits? That was all for git-am(1). It was added to git-rebase(1) in 570ccad3 (rebase: add options passed to git-am, 2009-03-18)[2] in order to plug options that could not be sent on to git-am(1). At this point the utility of the option graduated to making no sense; a use case for `git rebase --committer-date-is-author- date` is still yet to be found. Just warn against using this option on both commands and remind the user to consider whether they really need it. † 2: See also 7573cec5 (rebase -i: support --committer-date-is-author-date, 2020-08-17) for the commit for the merge backend Suggested-by: Johannes Sixt Signed-off-by: Kristoffer Haugsbakk Acked-by: Johannes Sixt Signed-off-by: Junio C Hamano