handling

A Cargo extension that adds cargo load and cargo unload commands for managing binary packages from custom registries and GitHub repositories.

Features

• Direct GitHub installation: Install binaries directly from GitHub repos
• Version control: Support for tags, branches, and commits
• Custom registries: Resolve package names from your own registry
• Automatic authentication: Auto-retries with GITHUB_TOKEN when needed
• Zero external dependencies: Pure Rust implementation

Installation

cargo install handling

Or build locally:

git clone https://github.com/handling-rs/handling
cd handling
cargo install --path .

Usage

Load/install a package

From GitHub:

cargo load example/cli

This will install the binary from https://github.com/example/cli.git

With version/ref:

cargo load example/cli@v1.2.3      # Tag
cargo load example/cli@1.2.3       # Tag (adds 'v' prefix automatically)
cargo load example/cli@fed6474     # Commit
cargo load example/cli@main        # Branch
cargo load example/cli@latest      # Latest

From registry:

cargo load cli                   # Resolves from default registry
cargo load cli --registry example  # Custom registry located in https://github.com/example/handling-registry
cargo load cli --registry example/registry  # Custom registry located in https://github.com/example/registry

With authentication:

cargo load cli --token ghp_xxx   # Explicit token
# Or set GITHUB_TOKEN env var

Install specific binary:

cargo load cli --bin binary-name

Force reinstall:

cargo load cli --force

Use locked dependencies:

cargo load cli --locked

Unload/uninstall a package

cargo unload cli

This wraps behind the scenes:

cargo uninstall cli

Uninstall specific binary:

cargo unload cli --bin binary-name

How It Works

Registry Resolution

Default registry: github.com/handling-rs/registry

Registry structure (registry.toml):

[packages.cli]
git = "https://github.com/example/cli.git"

[packages.another]
git = "https://github.com/example/tool.git"

Custom registry:

• --registry example → github.com/example/handling-registry
• --registry example/custom → github.com/example/custom

Fallback to crates.io

When you install a package by name (without /):

1. Default behavior (no --registry flag):

   • First tries to find the package in the default handling registry
   • If not found, automatically falls back to crates.io
   • Notifies you which source was used

2. Custom registry (with --registry flag):

   • Only searches the specified registry
   • If not found, fails with an error (no fallback)
   • This ensures you know exactly which source is being used

Examples:

# Tries handling registry first, falls back to crates.io if not found
cargo load ripgrep

# Only searches custom registry, fails if not found
cargo load my-tool --registry myorg

Ref Parsing

When you specify @version:

• @vX.Y.Z or @X.Y.Z → Git tag
• @<7+ hex chars> → Git commit
• Anything else → Git branch

Authentication

1. First attempts request without token
2. If 401 or 403 response:
   • If --token provided: uses that token
   • Otherwise: auto-retries with GITHUB_TOKEN env var
3. Token is injected into URL: https://<TOKEN>@github.com/...

This works for both registry fetching (private registries) and git cloning (private repos).

Building Locally

Prerequisites:

• Rust 1.70+ (2021 edition)

Build:

cargo build --release

Install:

cargo install --path .

Test:

cargo test
cargo run --bin cargo-load -- load --help
cargo run --bin cargo-unload -- unload --help

Project Structure

src/
├── lib.rs              # Entry point
├── bin/
│   ├── cargo-load.rs   # Load binary
│   └── cargo-unload.rs # Unload binary
├── commands/
│   ├── load.rs         # Load command logic
│   └── unload.rs       # Unload command logic
└── core/
    ├── parser.rs       # Spec & ref parsing
    ├── registry.rs     # Registry resolution
    ├── git.rs          # Git URL handling
    └── http.rs         # HTTP fetching

Examples

# Install from GitHub
cargo load example/cli

# Install specific version
cargo load example/cli@v1.2.3

# Install from custom registry
cargo load my-tool --registry myorg

# Install with authentication
export GITHUB_TOKEN=ghp_xxx
cargo load private-org/tool

# Install specific binary only
cargo load cli --bin binary-name

# Force reinstall
cargo load cli --force

# Use locked dependencies
cargo load cli --locked

# Uninstall
cargo unload cli

# Uninstall specific binary
cargo unload cli --bin binary-name

People

• Iñigo Taibo