dulwich.am

module documentation

Applying mailbox-style patches to a repository, similar to git am.

Supports state persistence in .git/rebase-apply/ for --continue, --skip, --abort, and --quit operations when a patch fails to apply.

Class	`DiskAmStateManager`	Manages git am state on disk in .git/rebase-apply/.
Exception	`AmConflict`	Raised when a patch fails to apply during am.
Exception	`AmError`	Base class for am errors.
Function	`am`	Apply patches from email messages to a repository, creating commits.
Function	`am_abort`	Abort the current am operation and restore the original state.
Function	`am_continue`	Continue applying patches after resolving a conflict.
Function	`am_quit`	Quit the current am operation without reverting changes.
Function	`am_skip`	Skip the current patch and continue with remaining patches.
Function	`_apply_remaining`	Apply patches from start to total, cleaning up state on success.
Function	`_apply_single_patch`	Apply a single patch from state and create a commit.
Function	`_get_state_manager`	Undocumented
Function	`_parse_author_date`	Parse an RFC 2822 date string into (timestamp, timezone_offset).
Function	`_reset_worktree_to_tree`	Hard-reset working tree and index to match a given tree.

def am(r: Repo, msgs: Iterable[email.message.Message], *, three_way: bool = False, keep_subject: bool = False, keep_non_patch: bool = False, scissors: bool = False, message_id: bool = False, strip: int = 1, committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Apply patches from email messages to a repository, creating commits.

Saves state to .git/rebase-apply/ so that if a patch fails, the user can resolve and use am_continue(), am_skip(), am_abort(), or am_quit().

Parameters
r:`Repo`	Repository object
msgs:`Iterable[email.message.Message]`	Iterable of email.message.Message objects containing patches
three_way:`bool`	Fall back to 3-way merge if patch does not apply cleanly
keep_subject:`bool`	If True, keep subject intact without munging
keep_non_patch:`bool`	If True, only strip [PATCH] from brackets
scissors:`bool`	If True, remove everything before scissors line
message_id:`bool`	If True, include Message-ID in commit message
strip:`int`	Number of leading path components to strip (default: 1)
committer:`bytes \| None`	Optional committer identity (bytes)
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs (bytes) created

Raises
`AmConflict`	If a patch fails to apply (state is saved for recovery)
`AmError`	If am state already exists (previous am in progress)

def am_abort(r: Repo): ¶

Abort the current am operation and restore the original state.

Resets HEAD to the original commit from before am started, and resets the working tree and index to match.

Parameters
r:`Repo`	Repository object

Raises
`AmError`	If no am is in progress

def am_continue(r: Repo, *, committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Continue applying patches after resolving a conflict.

The user should have resolved conflicts in the working tree and staged the result before calling this.

Parameters
r:`Repo`	Repository object
committer:`bytes \| None`	Optional committer identity
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs created (for current + remaining patches)

Raises
`AmError`	If no am is in progress
`AmConflict`	If a subsequent patch fails to apply

def am_quit(r: Repo): ¶

Quit the current am operation without reverting changes.

Removes the am state directory but keeps HEAD, index, and working tree as they are.

Parameters
r:`Repo`	Repository object

Raises
`AmError`	If no am is in progress

def am_skip(r: Repo, *, committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Skip the current patch and continue with remaining patches.

Resets the working tree and index to HEAD before continuing.

Parameters
r:`Repo`	Repository object
committer:`bytes \| None`	Optional committer identity
commit_timestamp:`float \| None`	Optional committer timestamp
commit_timezone:`int \| None`	Optional committer timezone offset

Returns
`list[ObjectID]`	List of commit SHAs created (for remaining patches)

Raises
`AmError`	If no am is in progress
`AmConflict`	If a subsequent patch fails to apply

def _apply_remaining(r: Repo, state: DiskAmStateManager, start: int, total: int, *, committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> list[ObjectID]: ¶

Apply patches from start to total, cleaning up state on success.

Raises
`AmConflict`	If a patch fails to apply (state preserved for recovery).

def _apply_single_patch(r: Repo, state: DiskAmStateManager, patch_number: int, total: int, *, committer: bytes | None = None, commit_timestamp: float | None = None, commit_timezone: int | None = None) -> ObjectID: ¶

Apply a single patch from state and create a commit.

Returns the commit SHA.

Raises
`AmConflict`	If the patch cannot be applied.

def _get_state_manager(r: Repo) -> DiskAmStateManager: ¶

Undocumented

def _parse_author_date(date_str: str | None) -> tuple[float | None, int | None]: ¶

Parse an RFC 2822 date string into (timestamp, timezone_offset).

def _reset_worktree_to_tree(r: Repo, target_tree_id: ObjectID): ¶

Hard-reset working tree and index to match a given tree.