Branching Workflows

One of Contree’s most powerful features is the ability to branch execution flows from a single base filesystem state (a snapshot of all files and directories in a container at a specific point in time). This is similar to Git branches, but for container execution states.

Why Branching Matters

Without Contree, running the same operations twice (like installing packages, creating files, or compiling code) requires rebuilding the entire filesystem state from scratch each time. Contree captures the exact filesystem state after each command, making it reproducible and allowing you to branch from that exact state.

Simple Branching Example

This example demonstrates creating a parent state with a random value, then branching into multiple child states from that fixed parent:

Async

base = await client.images.pull("alpine:latest")

child = await base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False)
print(f"Child created from base, UUID: {child.uuid}\n")

for i, letter in enumerate(["A", "B", "C"], 1):
    gc = await child.run(
        shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
        disposable=False,
    )
    print(f"Grandchild {i}: {gc.stdout.strip()}")

See run() for full API reference.

Sync

base = client.images.pull("alpine:latest")

child = base.run(shell='echo "$RANDOM" > /tmp/random.txt', disposable=False).wait()
print(f"Child created from base, UUID: {child.uuid}\n")

for i, letter in enumerate(["A", "B", "C"], 1):
    gc = child.run(
        shell=f"echo '{letter}' >> /tmp/random.txt && cat /tmp/random.txt",
        disposable=False,
    ).wait()
    print(f"Grandchild {i}: {gc.stdout.strip()}")

See run() for full API reference.

Key Points:

• The child state contains a random value that would be different on each execution without Contree

• All three grandchildren start from the exact same child state (same random value)

• Each grandchild branches independently, creating different execution paths

Advanced Branching Patterns

For more complex scenarios with multiple branching strategies:

Async

image = await client.images.pull("alpine:latest")
print(f"Pulled {image=}")

print("\nExample 1: Different commands from same image")
result1 = await image.run(shell="echo 'First branch'", disposable=False)
result2 = await image.run(shell="echo 'Second branch'", disposable=False)
result3 = await image.run(shell="ls /bin | head -3", disposable=False)

print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

print("\nExample 2: Random output command (different each time)")
random1 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)
random2 = await image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False)

print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

print("\nExample 3: Chain of operations from different branches")
base_result = await image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False)

sort_result = await base_result.run(shell="sort /tmp/fruits.txt", disposable=False)
reverse_result = await base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False)

print(f"Base: {base_result.uuid=}")
print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

print("\nExample 4: Same command twice - same UUID")
same1 = await image.run(shell="echo 'Same command'", disposable=False)
same2 = await image.run(shell="echo 'Same command'", disposable=False)

print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
print(f"UUIDs equal: {same1.uuid == same2.uuid}")

See ContreeImage for full API reference.

Sync

image = client.images.pull("alpine:latest")
print(f"Pulled {image=}")

print("\nExample 1: Different commands from same image")
result1 = image.run(shell="echo 'First branch'", disposable=False).wait()
result2 = image.run(shell="echo 'Second branch'", disposable=False).wait()
result3 = image.run(shell="ls /bin | head -3", disposable=False).wait()

print(f"Branch 1: {result1.stdout=}, {result1.uuid=}")
print(f"Branch 2: {result2.stdout=}, {result2.uuid=}")
print(f"Branch 3: {result3.stdout=}, {result3.uuid=}")

print("\nExample 2: Random output command (different each time)")
random1 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()
random2 = image.run(shell="od -An -N2 -tu2 /dev/urandom", disposable=False).wait()

print(f"Random 1: {random1.stdout=}, {random1.uuid=}")
print(f"Random 2: {random2.stdout=}, {random2.uuid=}")

print("\nExample 3: Chain of operations from different branches")
base_result = image.run(shell="echo 'apple\nbanana\ncherry' > /tmp/fruits.txt", disposable=False).wait()

sort_result = base_result.run(shell="sort /tmp/fruits.txt", disposable=False).wait()
reverse_result = base_result.run(shell="sort -r /tmp/fruits.txt", disposable=False).wait()

print(f"Base: {base_result.uuid=}")
print(f"Sorted: {sort_result.stdout=}, {sort_result.uuid=}")
print(f"Reverse sorted: {reverse_result.stdout=}, {reverse_result.uuid=}")

print("\nExample 4: Same command twice - same UUID")
same1 = image.run(shell="echo 'Same command'", disposable=False).wait()
same2 = image.run(shell="echo 'Same command'", disposable=False).wait()

print(f"Same 1: {same1.stdout=}, {same1.uuid=}")
print(f"Same 2: {same2.stdout=}, {same2.uuid=}")
print(f"UUIDs equal: {same1.uuid == same2.uuid}")

See ContreeImageSync for full API reference.

Use Cases

Branching is particularly useful for:

• Testing multiple scenarios: Run different operations from the same starting state

• Reproducible randomness: Capture random/non-deterministic operations and branch from them

• Parallel execution paths: Execute different workflows from a common checkpoint

• Version control for execution: Create branches like Git for different execution flows