crab init

Initialize a new Crab repository.

Synopsis

crab init [OPTIONS] [URL]

Description

crab init creates or validates the canonical v1 remote layout and empty generation-0 manifest, then connects a local Git repository to that remote. It creates or updates .crab/ and crab.toml, registers the Crab filter and diff drivers, and adds a Git remote. It does not scan the working tree.

If no git repository exists in the current directory, crab init automatically runs git init first — no need to initialize git separately.

Run crab setup afterward to scan for large files and write .gitattributes tracking rules. With no URL, crab init re-applies the configuration from an existing crab.toml.

For conceptual background, see Creating a Repository.

Arguments

Options

What It Does

1. Creates a git repository (if .git doesn't exist)
2. Creates .crab/local.toml for machine-specific settings
3. Registers the filter and diff drivers in .git/config
4. Adds or updates a Git remote for the canonical crab:// URL
5. Creates or validates the canonical v1 layout descriptor remotely
6. Creates the generation-0 manifest atomically, or adopts the existing canonical manifest on repeat or concurrent initialization

There is no local-only selector. A non-empty prefix without a descriptor, a non-v1 descriptor, or a missing manifest during normal repository use fails closed. Reset isolated development data explicitly; push and clone do not convert or synthesize repository state.

Examples

New project from scratch

mkdir my-ml-project && cd my-ml-project
crab init crab://my-bucket/ml-models
# ✓ Initialized git repository
# ✓ Created .crab/local.toml
# ✓ Registered filter.crab driver
# Next: crab setup

Existing git repo

cd my-existing-repo
crab init s3://team-bucket/my-repo
# ✓ Created .crab/local.toml
# ✓ Registered filter.crab driver
# Next: crab setup

Configure tracking separately

crab init crab://bucket/repo
crab setup --no-auto-track
# Install the filter driver without scanning for patterns

Choose bucket-GC cost or latency policy

crab init --gc-list-profile adaptive crab://bucket/repo

adaptive keeps small listings on one low-cost stream and switches large namespaces to concurrent hash partitions. cost always minimizes LIST streams; latency immediately uses partition parallelism. The setting is local operational policy and does not change shared object keys.

Re-apply a committed project configuration

crab init

Auto-Tracked Extensions

When auto-tracking is enabled (the default), crab setup tracks extensions that meet either criterion:

• Size threshold: Any file above 1 MiB triggers tracking for its extension
• Well-known binary formats: These extensions are always tracked when found, regardless of size:

URL Format

Crab URLs follow the pattern crab://<bucket>/<repo-path>:

crab://my-bucket/my-project
crab://company-data/team-ml/experiment-42
s3://us-west-2-storage/repos/frontend-assets

Related Commands

• crab clone — clone an existing repository
• crab track — manually configure file patterns
• crab install — install filter driver globally
• crab ship — one-shot add + commit + push