> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    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()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage.run) for full API reference.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    base = client.images.use("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()`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync.run) for full API reference.
  </Tab>
</Tabs>

**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:

<Tabs>
  <Tab title="Async">
    ```python theme={null}
    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`](./reference/image#contree_sdk.sdk.objects.image.ContreeImage) for full API reference.
  </Tab>

  <Tab title="Sync">
    ```python theme={null}
    image = client.images.use("alpine:latest")
    print(f"Using {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`](./reference/image#contree_sdk.sdk.objects.image.ContreeImageSync) for full API reference.
  </Tab>
</Tabs>

## 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