Documentation
¶
Overview ¶
Package trailer reads git trailers from a commit message.
Extracted from package policy when a second consumer appeared: the version decision reads Release-As:, and release notes read Release-Note:. Two copies of a parser this fiddly would have drifted, and the fiddliness is the point — see Block on what "a trailer" actually means.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Block ¶
Block returns the lines of a commit message's git trailer block, or nil when it has none.
Why this is not "any line with a colon in it" ¶
An earlier implementation scanned every line of the body. A fenced example in a commit message —
Example: ```yaml Release-As: 9.0.0 ```
— was therefore read as an instruction, and a documentation snippet could cut a permanent major-version tag.
Git's rule is narrower and is the one applied here: the trailer block is the LAST paragraph of the message, and it qualifies only if every one of its non-continuation lines is a "Key: value" pair. Anything after it — prose, a closing fence, a stray sentence — means there is no trailer block at all.
The one place this reads MORE than git does ¶
A forge closing reference — "Closes #15", "Fixes cicd#42", "Refs !18" — is tolerated inside the block. Git refuses it, because it carries no colon, and refusing it discards every trailer above it: measured against git 2.43.0, a message ending "Release-As: 1.0.0" then "Closes #15" has no trailers at all. That is the form every repository in this estate writes, and it silently cost two release notes before it was noticed (colophon#16, spec 0013 D1).
This is a SUPERSET, not a different reading. Every message git accepts is accepted here with the same values; what is added is the message whose git form was got wrong by accident. A tolerated line contributes nothing itself — Values never returns one — it only stops disqualifying the paragraph it sits in.
The tolerance is deliberately narrow, because the rule it relaxes exists to stop a FENCED "Release-As:" cutting a permanent tag: see [isForgeReference].
func Orphaned ¶ added in v0.7.0
Orphaned reports which of the given keys the message mentions in a "Key: value" line that is NOT in its trailer block, and which therefore decides nothing.
This is the loud half of the same problem Block tolerates: a person wrote an annotation, colophon declined to read it, and a release shipped without it. Everything else colophon refuses, it refuses out loud (spec 0013 D3).
Keys are matched case-insensitively, as trailers are.
func Paragraphs ¶
Paragraphs breaks a message into blank-line-separated groups of non-empty lines.
func Values ¶
Values returns EVERY value for a key in the trailer block, matched case-insensitively.
All of them, not the last: a body carrying two Release-As lines is a caller stating two things, and silently keeping one hides both the conflict and any malformed value that happened to come first.
Continuation lines are FOLDED into the value above them, as git does, so
Release-As: 1.0.0
is one trailer whose value is "1.0.0". Verified against `git interpret-trailers --parse` rather than inferred.
Types ¶
This section is empty.