Installation & Setup

Crab is a single binary that acts as both a git remote helper and a large-file filter driver. Once installed, it integrates transparently with git — no plugins, no extensions, no separate daemon to manage.

Install Crab

Quick install (recommended)

curl -fsSL https://crab.build/install.sh | bash

This downloads the latest release binary for your platform and places it in ~/.cargo/bin/ (or /usr/local/bin/ if cargo isn't available).

Verify installation

crab version

You should see output like:

crab 0.12.0 (abc1234 2026-05-20)

How Crab Integrates with Git

Crab works through two git extension points:

1. Filter driver — Routes tracked files through Crab's clean/smudge pipeline during checkout and commit. The clean filter replaces file content with pointer blobs; the smudge filter can reconstruct content or pass pointers through (lazy mode).

2. Remote helper — Handles crab:// URLs during push and fetch. Uploads xorbs to cloud storage on push, downloads them on fetch.

Both are registered automatically when you run crab init or crab clone. You rarely need to install them manually.

What Gets Configured

When Crab initializes a repository, it sets up:

The filter driver entry in .git/config looks like:

[filter "crab"]
    process = crab filter-process
    required = true

Installation Scopes

You can install the filter driver at different scopes:

Global install (recommended for teams)

If you work with multiple Crab repositories, install the filter driver globally once:

crab install --global

After this, any repository with .gitattributes containing filter=crab rules will work automatically — even repos cloned with plain git clone (no crab clone needed). This is the simplest setup for collaborators joining an existing project:

# One-time setup:
crab install --global

# Then just clone normally:
git clone git@github.com:team/ml-models.git
# Filter driver is already registered globally — crab tracking just works

For most individual users, the local scope (set automatically by crab init) is sufficient.

CI / Server Setup

For CI environments where you want fast checkouts without hydrating files:

crab install --skip-smudge

This configures the smudge filter to pass pointers through unchanged, so git checkout is instant. Files remain as pointers until you explicitly hydrate them:

crab hydrate --manifest .crab/manifests/ci.txt

Verifying Your Setup

Run the health check to confirm everything is configured correctly:

crab doctor

This checks:

• Binary is on PATH and accessible
• Filter driver is registered in git config
• Cloud credentials are valid
• Remote bucket is accessible
• Staging area is healthy

Next Steps

• Create a new repository — Set up Crab with your cloud bucket
• Clone an existing repository — Get started with a team's repo
• Track file patterns — Tell Crab which files to manage

CLI Reference

For complete crab install / crab uninstall command syntax and options, run crab install --help or crab uninstall --help.