# Reference Transactions

Reference transactions allow you to update multiple references atomically. All reference updates within a transaction either succeed together or fail together, ensuring repository consistency.

## Basic Usage

Use the `Repository.transaction()` method as a context manager. The transaction commits automatically when the context exits successfully, or rolls back if an exception is raised:

    with repo.transaction() as txn:
        txn.lock_ref('refs/heads/master')
        txn.set_target('refs/heads/master', new_oid, message='Update master')

## Atomic Multi-Reference Updates

Transactions are useful when you need to update multiple references atomically:

    # Swap two branches atomically
    with repo.transaction() as txn:
        txn.lock_ref('refs/heads/branch-a')
        txn.lock_ref('refs/heads/branch-b')

        # Get current targets
        ref_a = repo.lookup_reference('refs/heads/branch-a')
        ref_b = repo.lookup_reference('refs/heads/branch-b')

        # Swap them
        txn.set_target('refs/heads/branch-a', ref_b.target, message='Swap')
        txn.set_target('refs/heads/branch-b', ref_a.target, message='Swap')

## Automatic Rollback

If an exception occurs during the transaction, changes are automatically rolled back:

    try:
        with repo.transaction() as txn:
            txn.lock_ref('refs/heads/master')
            txn.set_target('refs/heads/master', new_oid)

            # If this raises an exception, the ref update is rolled back
            validate_commit(new_oid)
    except ValidationError:
        # Master still points to its original target
        pass

## Manual Commit

While the context manager is recommended, you can manually manage transactions:

    from pygit2 import ReferenceTransaction

    txn = ReferenceTransaction(repo)
    try:
        txn.lock_ref('refs/heads/master')
        txn.set_target('refs/heads/master', new_oid, message='Update')
        txn.commit()
    finally:
        del txn  # Ensure transaction is freed

## API Reference

### Repository Methods

Repository.transaction() → ReferenceTransaction

  Create a new reference transaction.

  Returns a context manager that commits all reference updates atomically when the context exits successfully, or performs no updates if an exception is raised.

  Example:

      with repo.transaction() as txn:
          txn.lock_ref('refs/heads/master')
          txn.set_target('refs/heads/master', new_oid, message='Update')

### The ReferenceTransaction Type

class pygit2.ReferenceTransaction(repository: BaseRepository)

  Context manager for transactional reference updates.

  A transaction allows multiple reference updates to be performed atomically. All updates are applied when the transaction is committed, or none are applied if the transaction is rolled back.

  Example:
    with repo.transaction() as txn:

      txn.lock_ref(‘refs/heads/master’) txn.set_target(‘refs/heads/master’, new_oid, message=’Update master’) # Changes committed automatically on context exit

  commit() → None

    Commit the transaction, applying all queued updates.

  lock_ref(refname: str) → None

    Lock a reference in preparation for updating it.

    Args:

      refname: Name of the reference to lock (e.g., ‘refs/heads/master’)

  remove(refname: str) → None

    Remove a reference.

    The reference must be locked first via lock_ref().

    Args:

      refname: Name of the reference to remove

  set_symbolic_target(refname: str, target: str, signature: Signature | None = None, message: str | None = None) → None

    Set the target of a symbolic reference.

    The reference must be locked first via lock_ref().

    Args:

      refname: Name of the reference to update target: Target reference name (e.g., ‘refs/heads/master’) signature: Signature for the reflog (None to use repo identity) message: Message for the reflog

  set_target(refname: str, target: Oid | str, signature: Signature | None = None, message: str | None = None) → None

    Set the target of a direct reference.

    The reference must be locked first via lock_ref().

    Args:

      refname: Name of the reference to update target: Target OID or hex string signature: Signature for the reflog (None to use repo identity) message: Message for the reflog

## Usage Notes

- Always lock a reference with `lock_ref()` before modifying it

- Transactions operate on reference names, not Reference objects

- Symbolic references can be updated with `set_symbolic_target()`

- References can be deleted with `remove()`

- The signature parameter defaults to the repository’s configured identity

## Thread Safety

Transactions are thread-local and must be used from the thread that created them. Attempting to use a transaction from a different thread raises `RuntimeError`:

    # This is safe - each thread has its own transaction
    def thread1():
        with repo.transaction() as txn:
            txn.lock_ref('refs/heads/branch1')
            txn.set_target('refs/heads/branch1', oid1)

    def thread2():
        with repo.transaction() as txn:
            txn.lock_ref('refs/heads/branch2')
            txn.set_target('refs/heads/branch2', oid2)

    # Both threads can run concurrently without conflicts

Different threads can hold transactions simultaneously as long as they don’t attempt to lock the same references. If two threads try to acquire locks in different orders, libgit2 will detect potential deadlocks and raise an error.