Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archil.com/llms.txt

Use this file to discover all available pages before exploring further.

Branches and checkpoints are currently in private beta. To request access, contact us at support@archil.com.
Branches and checkpoints let you capture the state of an Archil disk at a moment in time and then explore alternative histories without disturbing the original. A checkpoint is a named, point-in-time snapshot of the filesystem state on a disk. The filesystem state a checkpoint references is immutable. A branch is an independent, writable fork of a disk that starts from a specific checkpoint. Writes on a branch don’t affect the source branch. Branches form a tree. Every branch points back to the checkpoint on its parent it was forked from. Checkpoints, in turn, always belong to a specific branch (or to the root).
If you’re familiar with Git, Archil branches and checkpoints map fairly directly to Git branches and Git commits respectively.
For example: A timeline showing the root disk with checkpoints chk: x and chk: z, branch 1 forked from chk: x with its own checkpoint chk: y, and branch 2 forked from chk: z. Here, the root has two checkpoints: x and z. Branch 1 was forked from x and branch 2 was forked from z. Any mutations to the filesystem state on the root after x would not appear in branch 1 and vice versa.

​
Working with checkpoints

Checkpoints are taken from a mounted disk and capture the filesystem state at the time the command runs: 
# Mount the disk, then take a checkpoint
sudo archil mount myorg/mydisk /mnt/archil --region aws-us-east-1
archil checkpoints create /mnt/archil pre-migration
Checkpoint names must be unique within the branch they’re taken on. Once created, the state a checkpoint points to never changes. To see the checkpoints available on a disk: 
# Checkpoints on the root
archil checkpoints list dsk-0123456789abcdef --region aws-us-east-1

# Checkpoints on a specific branch
archil checkpoints list dsk-0123456789abcdef --region aws-us-east-1 --branch experiment-1
The list is rendered oldest-first, so the most recent checkpoint appears at the bottom.

​
Working with branches

Create a branch by naming the checkpoint you want it to fork from. 
# Branch from a checkpoint on the root
archil branches --region aws-us-east-1 create dsk-0123456789abcdef experiment-1 \
    --from-checkpoint pre-migration

# Branch from a checkpoint that lives on another branch
archil branches --region aws-us-east-1 create dsk-0123456789abcdef experiment-2 \
    --from-checkpoint v1 --from-branch experiment-1
To use a branch, mount it with --branch: 
sudo archil mount myorg/mydisk /mnt/branch --region aws-us-east-1 --branch experiment-1
A mounted branch behaves exactly like any other Archil disk. You can read, write, take additional checkpoints from it, and create further branches off of those checkpoints. Writes to a branch are isolated from its parent and from any sibling branches. For the full set of CLI flags, see archil checkpoints and archil branches in the CLI reference.