Breaking change footer together with other footers #137

New Issue

GiteaMirror · 2026-02-17T11:48:58-06:00

GiteaMirror commented

2026-02-17 11:48:58 -06:00

Originally created by @mainrs on GitHub (Dec 10, 2021).

The git trailer specification says that each pair of git trailers is separated by a newline only. Does that imply that, if a commit contains a breaking change, the footers have to come directly after it, without an empty newline after it?

This would be wrong:

fix!: parser number handling

BREAKING CHANGE: The parser now treats floats as ints

Signed-off-by: me

This is correct:

fix!: parser number handling

BREAKING CHANGE: The parser now treats floats as ints
Signed-off-by: me

Originally created by @mainrs on GitHub (Dec 10, 2021). The git trailer specification says that each pair of git trailers is separated by a newline only. Does that imply that, if a commit contains a breaking change, the footers have to come directly after it, without an empty newline after it? This would be wrong: ``` fix!: parser number handling BREAKING CHANGE: The parser now treats floats as ints Signed-off-by: me ``` This is correct: ``` fix!: parser number handling BREAKING CHANGE: The parser now treats floats as ints Signed-off-by: me ```

GiteaMirror added the question label 2026-02-17 11:48:58 -06:00

GiteaMirror commented

2026-02-17 11:49:00 -06:00

@bcoe commented on GitHub (Dec 21, 2021):

I was picturing that this would work, but the BREAKING CHANGE would actually be parsed out of the body rather than from the footers.

@bcoe commented on GitHub (Dec 21, 2021): I was picturing that this would work, but the `BREAKING CHANGE` would actually be parsed out of the body rather than from the footers.

GiteaMirror commented

2026-02-17 11:49:01 -06:00

@mainrs commented on GitHub (Dec 22, 2021):

I was picturing that this would work, but the BREAKING CHANGE would actually be parsed out of the body rather than from the footers.

Strictly speaking, yes. A lot of repositories that follow CC do use the first notation. Probably to make it more obvious. But it does require more lenient parsing to parse correctly.

@mainrs commented on GitHub (Dec 22, 2021): > I was picturing that this would work, but the `BREAKING CHANGE` would actually be parsed out of the body rather than from the footers. Strictly speaking, yes. A lot of repositories that follow CC do use the first notation. Probably to make it more obvious. But it does require more lenient parsing to parse correctly.

GiteaMirror commented

2026-02-17 11:49:02 -06:00

@Conaclos commented on GitHub (Aug 3, 2022):

In my opinion BREAKING CHANGE should not be treated as a trailer. Git does not by default recognize a spaced key as a git trailer. Moreover BREAKING CHANGE sometimes spans on multiple lines. Multi-line git trailers are allowed, but they require a blank character at the beginning of every line and are generally discouraged : git interpret-trailer one-line them.

I personally use the following format:

<type>[scope][!]: <desc>

[body]

BREAKING CHANGE: <desc>

[breaking change body]

[trailers]

If you really want to use a git trailer I could advice you to use "BREAKING-CHANGE" and a single line of description.

<type>[scope][!]: <desc>

[body]

BREAKING-CHANGE: <desc>
[more trailers]

@Conaclos commented on GitHub (Aug 3, 2022): In my opinion `BREAKING CHANGE` should not be treated as a trailer. Git does not by default recognize a spaced key as a git trailer. Moreover `BREAKING CHANGE` sometimes spans on multiple lines. Multi-line git trailers are allowed, but they require a blank character at the beginning of every line and are generally discouraged : `git interpret-trailer` one-line them. I personally use the following format: ``` <type>[scope][!]: <desc> [body] BREAKING CHANGE: <desc> [breaking change body] [trailers] ``` If you really want to use a git trailer I could advice you to use "BREAKING-CHANGE" and a single line of description. ``` <type>[scope][!]: <desc> [body] BREAKING-CHANGE: <desc> [more trailers] ```

GiteaMirror commented

2026-02-17 11:49:03 -06:00

@chbi commented on GitHub (Sep 1, 2022):

I faced the same issue: "BREAKING CHANGE" does not meet the git trailer convention and breaks our tooling (validation of commit messages using jgit). Our devs interpret "footer" (as used in CC) as "trailer" (as used in Git documentation) and use it that way.

As a workaround, I wrote "our own CC definition", that only allows "BREAKING-CHANGE" as the token in Git trailers.

I suggest one or both of the following:

clarify in CC, that "BREAKING CHANGE" is not a git trailer
deprecate "BREAKING CHANGE" and replace it with "BREAKING-CHANGE".

Concerning Git-Trailers: There is also a discussion on the Git mailing list: https://lore.kernel.org/git/xmqq4jy18q7h.fsf@gitster.g/. Git trailer documentation currently allows whitespace in the token part of trailers, while no major Git implementation does. It appears that git documentation will be fixed and will no longer allow whitespace in git trailers.

@chbi commented on GitHub (Sep 1, 2022): I faced the same issue: "BREAKING CHANGE" does not meet the git trailer convention and breaks our tooling (validation of commit messages using jgit). Our devs interpret "footer" (as used in CC) as "trailer" (as used in Git documentation) and use it that way. As a workaround, I wrote "our own CC definition", that only allows "BREAKING-CHANGE" as the token in Git trailers. I suggest one or both of the following: * clarify in CC, that "BREAKING CHANGE" is not a git trailer * deprecate "BREAKING CHANGE" and replace it with "BREAKING-CHANGE". Concerning Git-Trailers: There is also a discussion on the Git mailing list: https://lore.kernel.org/git/xmqq4jy18q7h.fsf@gitster.g/. Git trailer documentation currently allows whitespace in the token part of trailers, while no major Git implementation does. It appears that git documentation will be fixed and will no longer allow whitespace in git trailers.

GiteaMirror commented

2026-02-17 11:49:04 -06:00

@relaxdiego commented on GitHub (Feb 19, 2023):

It would be good if BREAKING CHANGE: was converted into a well-formed git trailer which complies with RFC 822. Specifically, the meta-syntax 1*<any CHAR, excluding CTLs, SPACE, and ":"> (e.g. BREAKING-CHANGE:) so that it becomes acceptable to a larger set of git users.

Being RFC 822 compliant would also mean breaking changes would show up when certain git log commands are executed. For example:

$ git log --format="%h %(trailers:separator=%x2C )" | \
    grep '^[0-9a-f]* [[:print:]].*'

ac6eee8 BREAKING-CHANGE: Foo no longer bars
e935b07 See: https://cbea.ms/git-commit/#seven-rules
696f1e6 Reference: https://example.com

@relaxdiego commented on GitHub (Feb 19, 2023): It would be good if `BREAKING CHANGE:` was converted into a well-formed git trailer which complies with [RFC 822](https://www.w3.org/Protocols/rfc822/3_Lexical.html#z1). Specifically, the meta-syntax `1*<any CHAR, excluding CTLs, SPACE, and ":">` (e.g. `BREAKING-CHANGE:`) so that it becomes acceptable to a larger set of git users. Being RFC 822 compliant would also mean breaking changes would show up when certain `git log` commands are executed. For example: ``` $ git log --format="%h %(trailers:separator=%x2C )" | \ grep '^[0-9a-f]* [[:print:]].*' ac6eee8 BREAKING-CHANGE: Foo no longer bars e935b07 See: https://cbea.ms/git-commit/#seven-rules 696f1e6 Reference: https://example.com ```

GiteaMirror commented

2026-02-17 11:49:05 -06:00

@LemmingAvalanche commented on GitHub (Mar 20, 2024):

@Conaclos (fwiw)

Multi-line git trailers are allowed, but they require a blank character at the beginning of every line and are generally discouraged

I haven’t seen it be discouraged.

You can’t have multiple paragraphs though. Like this.

feat!: foo

Fixes: Fusce sagittis, libero non molestie mollis, magna orci ultrices
  dolor, at vulputate neque nulla lacinia eros.

  Nullam eu ante vel est convallis dignissim.  Fusce suscipit, wisi nec
  facilisis facilisis, est dui fermentum leo, quis tempor ligula erat
  quis odio.  Nunc porta vulputate tellus.  Nunc rutrum turpis sed pede.
  Sed bibendum.  Aliquam posuere.  Nunc aliquet, augue nec adipiscing
  interdum, lacus tellus malesuada massa, quis varius mi purus non odio.
  Pellentesque condimentum, magna ut suscipit hendrerit, ipsum augue
  ornare nulla, non luctus diam neque sit amet urna.  Curabitur
  vulputate vestibulum lorem.  Fusce sagittis, libero non molestie
  mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia
  eros.  Sed id ligula quis est convallis tempor.  Curabitur lacinia
  pulvinar nibh.  Nam a sapien.

git interpret-trailer one-line them.

No, only if you explicitly ask for --unfold.

@LemmingAvalanche commented on GitHub (Mar 20, 2024): @Conaclos (fwiw) > Multi-line git trailers are allowed, but they require a blank character at the beginning of every line and are generally discouraged I haven’t seen it be discouraged. You can’t have multiple paragraphs though. Like this. ``` feat!: foo Fixes: Fusce sagittis, libero non molestie mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia eros. Nullam eu ante vel est convallis dignissim. Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. Nunc porta vulputate tellus. Nunc rutrum turpis sed pede. Sed bibendum. Aliquam posuere. Nunc aliquet, augue nec adipiscing interdum, lacus tellus malesuada massa, quis varius mi purus non odio. Pellentesque condimentum, magna ut suscipit hendrerit, ipsum augue ornare nulla, non luctus diam neque sit amet urna. Curabitur vulputate vestibulum lorem. Fusce sagittis, libero non molestie mollis, magna orci ultrices dolor, at vulputate neque nulla lacinia eros. Sed id ligula quis est convallis tempor. Curabitur lacinia pulvinar nibh. Nam a sapien. ``` > git interpret-trailer one-line them. No, only if you explicitly ask for `--unfold`.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/conventionalcommits.org#137