dulwich.trailers

module documentation

Git trailers parsing and manipulation.

This module provides functionality for parsing and manipulating Git trailers, which are structured information blocks appended to commit messages.

Trailers follow the format:: Token: value Token: value

They are similar to RFC 822 email headers and appear at the end of commit messages after free-form content.

Class	`Trailer`	Represents a single Git trailer.
Function	`add_trailer_to_message`	Add a trailer to a commit message.
Function	`format_trailers`	Format a list of trailers as bytes.
Function	`parse_trailers`	Parse trailers from a commit message.
Function	`_is_trailer_block`	Check if a group of lines forms a valid trailer block.
Function	`_parse_trailer_lines`	Parse individual trailer lines.

def add_trailer_to_message(message: bytes, key: str, value: str, separator: str = ':', where: str = 'end', if_exists: str = 'addIfDifferentNeighbor', if_missing: str = 'add') -> bytes: ¶

Add a trailer to a commit message.

Parameters
message:`bytes`	The original commit message
key:`str`	The trailer key
value:`str`	The trailer value
separator:`str`	The separator to use
where:`str`	Where to add the trailer ('end', 'start', 'after', 'before')
if_exists:`str`	How to handle existing trailers with the same key - 'add': Always add - 'replace': Replace all existing - 'addIfDifferent': Add only if value is different from all existing - 'addIfDifferentNeighbor': Add only if value differs from neighbors - 'doNothing': Don't add if key exists
if_missing:`str`	What to do if the key doesn't exist - 'add': Add the trailer - 'doNothing': Don't add the trailer

Returns
`bytes`	The message with the trailer added

def format_trailers(trailers: list[Trailer]) -> bytes: ¶

Format a list of trailers as bytes.

Parameters
trailers:`list[Trailer]`	List of Trailer objects

Returns
`bytes`	Formatted trailers as bytes

def parse_trailers(message: bytes, separators: str = ':') -> tuple[bytes, list[Trailer]]: ¶

Parse trailers from a commit message.

Trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers.

The group must be preceded by one or more empty (or whitespace-only) lines. The group must either be at the end of the input or be the last non-whitespace lines before a line that starts with '---'.

Parameters
message:`bytes`	The commit message as bytes
separators:`str`	Characters to recognize as trailer separators (default ':')

Returns
`tuple[bytes, list[Trailer]]`	A tuple of (message_without_trailers, list_of_trailers)

def _is_trailer_block(lines: list[str], separators: str) -> bool: ¶

Check if a group of lines forms a valid trailer block.

A trailer block must be composed entirely of trailer lines (with possible blank lines and continuation lines). A single non-trailer line invalidates the entire block.

Parameters
lines:`list[str]`	The lines to check
separators:`str`	Valid separator characters

Returns
`bool`	True if the lines form a valid trailer block

def _parse_trailer_lines(lines: list[str], separators: str) -> list[Trailer]: ¶

Parse individual trailer lines.

Parameters
lines:`list[str]`	The trailer lines to parse
separators:`str`	Valid separator characters

Returns
`list[Trailer]`	List of parsed Trailer objects