+ """A stack transaction, used for making complex updates to an StGit
+ stack in one single operation that will either succeed or fail
+ cleanly.
+
+ The basic theory of operation is the following:
+
+ 1. Create a transaction object.
+
+ 2. Inside a::
+
+ try
+ ...
+ except TransactionHalted:
+ pass
+
+ block, update the transaction with e.g. methods like
+ L{pop_patches} and L{push_patch}. This may create new git
+ objects such as commits, but will not write any refs; this means
+ that in case of a fatal error we can just walk away, no clean-up
+ required.
+
+ (Some operations may need to touch your index and working tree,
+ though. But they are cleaned up when needed.)
+
+ 3. After the C{try} block -- wheher or not the setup ran to
+ completion or halted part-way through by raising a
+ L{TransactionHalted} exception -- call the transaction's L{run}
+ method. This will either succeed in writing the updated state to
+ your refs and index+worktree, or fail without having done
+ anything."""
+ def __init__(self, stack, msg, discard_changes = False,
+ allow_conflicts = False, allow_bad_head = False):
+ """Create a new L{StackTransaction}.
+
+ @param discard_changes: Discard any changes in index+worktree
+ @type discard_changes: bool
+ @param allow_conflicts: Whether to allow pre-existing conflicts
+ @type allow_conflicts: bool or function of L{StackTransaction}"""