Skip to main content
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: 
base = await client.images.use("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.
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: 
image = await client.images.use("alpine:latest")
print(f"Using {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.

​
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