Documentation
¶
Overview ¶
Package trailers provides parsing and formatting for Entire commit message trailers. Trailers are key-value metadata appended to git commit messages following the git trailer convention (key: value format after a blank line).
Index ¶
- Constants
- func AppendCheckpointTrailer(message, checkpointID string) string
- func AppendOPFAppliedTrailer(message string) string
- func FormatCheckpoint(message string, cpID checkpointID.CheckpointID) string
- func FormatMetadata(message, metadataDir string) string
- func FormatShadowCommit(message, metadataDir, sessionID string) string
- func FormatShadowTaskCommit(message, taskMetadataDir, sessionID string) string
- func FormatSourceRef(branch, commitHash string) string
- func FormatTaskMetadata(message, taskMetadataDir string) string
- func HasOPFApplied(commitMessage string) bool
- func IsTrailerLine(line string) bool
- func ParseAllCheckpoints(commitMessage string) []checkpointID.CheckpointID
- func ParseAllSessions(commitMessage string) []string
- func ParseBaseCommit(commitMessage string) (string, bool)
- func ParseCheckpoint(commitMessage string) (checkpointID.CheckpointID, bool)
- func ParseMetadata(commitMessage string) (string, bool)
- func ParseSession(commitMessage string) (string, bool)
- func ParseTaskMetadata(commitMessage string) (string, bool)
Constants ¶
const ( // MetadataTrailerKey points to the metadata directory within a commit tree. MetadataTrailerKey = "Entire-Metadata" // MetadataTaskTrailerKey points to the task metadata directory for subagent checkpoints. MetadataTaskTrailerKey = "Entire-Metadata-Task" // StrategyTrailerKey indicates which strategy created the commit. StrategyTrailerKey = "Entire-Strategy" // BaseCommitTrailerKey links shadow commits to their base code commit. BaseCommitTrailerKey = "Base-Commit" // SessionTrailerKey identifies which session created a commit. SessionTrailerKey = "Entire-Session" // CondensationTrailerKey identifies the condensation ID for a commit (legacy). CondensationTrailerKey = "Entire-Condensation" // SourceRefTrailerKey links code commits to their metadata on a shadow/metadata branch. // Format: "<branch>@<commit-hash>" e.g. "entire/metadata@abc123def456" SourceRefTrailerKey = "Entire-Source-Ref" // CheckpointTrailerKey links commits to their checkpoint metadata on entire/checkpoints/v1. // Format: a checkpoint ID — either a legacy 12-hex ID (e.g. "a3b2c4d5e6f7") // or a 26-char ULID (see checkpoint/id.CheckpointPattern). // This trailer survives git amend and rebase operations. CheckpointTrailerKey = "Entire-Checkpoint" // EphemeralBranchTrailerKey identifies the shadow branch that a checkpoint originated from. // Used in manual-commit strategy checkpoint commits on entire/checkpoints/v1 branch. // Format: full branch name e.g. "entire/2b4c177" EphemeralBranchTrailerKey = "Ephemeral-branch" // AgentTrailerKey identifies the agent that created a checkpoint. // Format: human-readable agent name e.g. "Claude Code", "Cursor" AgentTrailerKey = "Entire-Agent" // OPFAppliedTrailerKey marks an entire/checkpoints/v1 commit whose blobs // have been redacted by the OpenAI Privacy Filter (8-layer pipeline). // Format: literal "true"; the trailer is omitted entirely when OPF was // not applied. The pre-push rewrite path treats commits lacking this // trailer as candidates to OPF-redact before they reach the remote. OPFAppliedTrailerKey = "Entire-OPF-Applied" // OPFAppliedTrailerValue is the only value that means "OPF ran." Any // other value (or trailer absence) is treated as "not applied" so a // future "false" / "skipped" value never accidentally enables OPF. OPFAppliedTrailerValue = "true" )
Trailer key constants used in commit messages.
Variables ¶
This section is empty.
Functions ¶
func AppendCheckpointTrailer ¶ added in v0.5.3
AppendCheckpointTrailer appends Entire-Checkpoint in trailer-aware format. If the message already ends with a trailer paragraph, append directly to it; otherwise add a blank line before starting a new trailer block.
func AppendOPFAppliedTrailer ¶ added in v0.7.8
AppendOPFAppliedTrailer appends `Entire-OPF-Applied: true` in trailer-aware format. Idempotent: if the message already carries the trailer with value "true", the original message is returned unchanged so re-parenting an already-applied commit doesn't duplicate the trailer.
func FormatCheckpoint ¶
func FormatCheckpoint(message string, cpID checkpointID.CheckpointID) string
FormatCheckpoint creates a commit message with a checkpoint trailer. This links user commits to their checkpoint metadata on entire/checkpoints/v1 branch.
func FormatMetadata ¶
FormatMetadata creates a commit message with metadata trailer.
func FormatShadowCommit ¶
FormatShadowCommit creates a commit message for manual-commit strategy checkpoints. Includes Entire-Metadata, Entire-Session, and Entire-Strategy trailers.
func FormatShadowTaskCommit ¶
FormatShadowTaskCommit creates a commit message for manual-commit task checkpoints. Includes Entire-Metadata-Task, Entire-Session, and Entire-Strategy trailers.
func FormatSourceRef ¶
FormatSourceRef creates a formatted source ref string for the trailer. Format: "<branch>@<commit-hash-prefix>" (hash truncated to ShortIDLength chars)
func FormatTaskMetadata ¶
FormatTaskMetadata creates a commit message with task metadata trailer.
func HasOPFApplied ¶ added in v0.7.8
HasOPFApplied reports whether the commit message carries an `Entire-OPF-Applied: true` trailer. Any other value (or absence) is treated as "OPF not applied" so the pre-push rewrite considers the commit a candidate for OPF redaction. Pinning the value to literal "true" — rather than just trailer presence — prevents a future "Entire-OPF-Applied: false" or "skipped" from accidentally meaning "yes, applied."
func IsTrailerLine ¶ added in v0.5.3
IsTrailerLine reports whether a line matches git trailer format.
func ParseAllCheckpoints ¶ added in v0.5.0
func ParseAllCheckpoints(commitMessage string) []checkpointID.CheckpointID
ParseAllCheckpoints extracts all checkpoint IDs from a commit message. Returns a slice of CheckpointIDs (may be empty if none found). Duplicate IDs are deduplicated while preserving order. This is useful for squash merge commits that contain multiple Entire-Checkpoint trailers.
func ParseAllSessions ¶
ParseAllSessions extracts all session IDs from a commit message. Returns a slice of session IDs (may be empty if none found). Duplicate session IDs are deduplicated while preserving order. This is useful for commits that may have multiple Entire-Session trailers.
func ParseBaseCommit ¶
ParseBaseCommit extracts the base commit SHA from a commit message. Returns the full SHA and true if found, empty string and false otherwise.
func ParseCheckpoint ¶
func ParseCheckpoint(commitMessage string) (checkpointID.CheckpointID, bool)
ParseCheckpoint extracts the checkpoint ID from a commit message. Returns the CheckpointID and true if found, empty ID and false otherwise.
func ParseMetadata ¶
ParseMetadata extracts metadata dir from commit message. Returns the metadata directory and true if found, empty string and false otherwise.
func ParseSession ¶
ParseSession extracts the session ID from a commit message. Returns the session ID and true if found, empty string and false otherwise. Note: If multiple Entire-Session trailers exist, this returns only the first one. Use ParseAllSessions to get all session IDs.
func ParseTaskMetadata ¶
ParseTaskMetadata extracts task metadata dir from commit message. Returns the task metadata directory and true if found, empty string and false otherwise.
Types ¶
This section is empty.
Source Files