# 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
```bash
cargo install handling
```
Or build locally:
```bash
git clone https://github.com/handling-rs/handling
cd handling
cargo install --path .
```
## Usage
### Load/install a package
**From GitHub:**
```bash
cargo load example/cli
```
This will install the binary from `https://github.com/example/cli.git`
**With version/ref:**
```bash
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](https://github.com/handling-rs/registry):**
```bash
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:**
```bash
cargo load cli --token ghp_xxx # Explicit token
# Or set GITHUB_TOKEN env var
```
**Install specific binary:**
```bash
cargo load cli --bin binary-name
```
**Force reinstall:**
```bash
cargo load cli --force
```
**Use locked dependencies:**
```bash
cargo load cli --locked
```
### Unload/uninstall a package
```bash
cargo unload cli
```
This wraps behind the scenes:
```bash
cargo uninstall cli
```
**Uninstall specific binary:**
```bash
cargo unload cli --bin binary-name
```
## How It Works
### Registry Resolution
Default registry: `github.com/handling-rs/registry`
Registry structure (`registry.toml`):
```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:**
```bash
# 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:**
```bash
cargo build --release
```
**Install:**
```bash
cargo install --path .
```
**Test:**
```bash
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
```bash
# 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](https://github.com/itaibo)