crab migrate

Rewrite history to move files into or out of crab tracking.

Synopsis

crab migrate info [OPTIONS]
crab migrate import [OPTIONS]
crab migrate export [OPTIONS]

Description

crab migrate rewrites git history to convert large files to crab pointers (import) or convert crab pointers back to full files (export). It also provides an analysis tool (info) to identify which file types would benefit from migration.

This is the crab equivalent of git lfs migrate. It uses git-filter-repo for the actual history rewrite.

Subcommands

crab migrate info

Analyze the repository to identify large files that would benefit from crab tracking.

crab migrate import

Convert large files in history to crab pointers.

crab migrate export

Convert crab pointers back to full files in history.

Examples

Analyze which files would benefit from migration

crab migrate info

Extension         Total Size    Count
-------------------------------------
*.bin              12.4 GB        42
*.safetensors       8.2 GB        15
*.h5                3.1 GB         8
*.onnx              1.5 GB         3
*.tar.gz            800 MB         5

Analyze with a higher size threshold

crab migrate info --above 10485760 --top 5

Only shows files above 10 MB, top 5 extensions.

Dry run import

crab migrate import --include '*.bin' --dry-run

migrate import (dry run):
  include: ["*.bin"]
  exclude: []
  above: 1048576 bytes
  everything: false
  (no changes will be made)

Import large files into crab tracking

crab migrate import --include '*.bin' --include '*.safetensors'

Import across all branches

crab migrate import --include '*.bin' --everything

Import with size threshold

crab migrate import --include '*' --above 5242880

Converts all files above 5 MB to crab pointers.

Export pointers back to full files

crab migrate export --include '*.bin'

Dry run export

crab migrate export --include '*.bin' --dry-run

Important Warnings

• History rewriting is a destructive operation. Always back up your repository before running migrate import or migrate export.
• After rewriting, all collaborators must re-clone the repository.
• Force-pushing rewritten history will break existing clones.
• --everything rewrites all branches — use with extreme caution.

Prerequisites

• git-filter-repo must be installed:

  pip install git-filter-repo

• The repository must be initialized with crab init (for import).
• AWS credentials must be configured (for import, to upload converted objects).

Workflow

Migrating an existing repository to crab

1. Analyze which files to migrate:

   crab migrate info

2. Back up the repository:

   cp -r my-repo my-repo-backup

3. Run the migration:

   crab migrate import --include '*.bin' --include '*.safetensors' --everything

4. Verify the result:

   crab status
   crab fsck

5. Force-push the rewritten history:

   git push --force origin --all

6. Notify collaborators to re-clone.

Related Commands

• crab track — track new files (without rewriting history).
• crab add — stage files for crab.
• crab lfs — LFS-compatible migration.