Import a snapshot from a directory¶

Turn a local directory tree into a READY, immutable, content-addressed snapshot (spec §5.2). Directory import is the launch-critical path and the one fully implemented import route.

Before you start

You need a running control plane. Set a tenant and project with --tenant and --project (or AWC_TENANT and AWC_PROJECT). Select an object store with --object-store-endpoint or AWC_CAS_URL (memory:// for local, s3:// for S3). The create command fails without these.

Choose the source directory and a normalization policy.

The policy is recorded in snapshot provenance and MUST be declared (spec §9.8).

source-normalized (the default) keeps only the file type and the executable bit. It zeroes mtime and collapses mode bits, so the same tree imports to the same digest every time. Build tools that key on mtime rebuild from the normalized timestamps.
environment-preserving keeps the captured mode bits and mtime; setuid and setgid are cleared by default. Use it for prepared build or dependency environments where tools read mtime. The digest is then sensitive to the captured timestamps.
Create the snapshot.

awcctl --output json snapshot create \
    --from-dir /path/to/prepared-dir \
    --name backend-main-8e3a2f \
    --label revision=8e3a2f

--from-dir is required. --source-type defaults to directory; you MAY omit it. Pass --normalization environment-preserving to override the default. Repeat --label KEY=VALUE to tag the snapshot.

Capture the snapshot id from the JSON.

The command returns the id and a VALIDATING state (spec §13.5).

{
  "snapshot_id": "snap_01J...",
  "state": "VALIDATING",
  "snapshot_manifest_digest": "sha256:...",
  "root_tree": "sha256:...",
  "logical_bytes": 2147483648,
  "file_count": 8123,
  "unique_objects": 9001,
  "unique_bytes": 1999348096
}

Poll until the state is READY.

awcctl snapshot inspect snap_01J...

The worker validates the object closure before publication (spec §13.5, §12.1). A snapshot becomes mountable only at READY. On a validation failure it moves to FAILED.

Confirm the totals.

Read files and bytes (the logical size) from the inspect output, with the manifest and root-tree digests. Compare them against your source tree to confirm the import captured what you expect.

Use the snapshot as a workspace base.

Only a READY snapshot can back a new workspace (spec §12.1). See fork a workspace.

Provenance variants¶

--source-type git and --source-type tar record a different source kind in provenance, but the create command always imports the directory at --from-dir. It does not clone a repository or extract an archive. For those flows, see import from Git and import from a tar archive.

Resumable uploads

Object writes are idempotent. If the create command is interrupted, re-run it. Objects already present in the store are reused and are not re-written.

Import a snapshot from a directory¶

Provenance variants¶

See also¶