# cargo-update Explained

## Overview

`cargo-update` is a **community-maintained Cargo subcommand** that manages updates for binaries installed with `cargo install`.  
It is *not* part of the official Cargo distribution, but it’s widely trusted and behaves like a native command after installation.

---

## Installation

    cargo install cargo-update

Once installed, it exposes a new subcommand:

    cargo install-update

This naming pattern (`cargo-*`) is how Cargo automatically recognizes external plugins.  
Any binary named `cargo-foo` can be run as `cargo foo`.

---

## Common Usage

| Command | Description |
|----------|--------------|
| `cargo install-update -a` | Update **all** installed Cargo binaries |
| `cargo install-update atuin` | Update only the specified package |
| `cargo install-update --list` | Show available updates |
| `cargo install-update -a --force` | Rebuild everything even if versions match |

---

## The `-a` Flag

The `-a` (or `--all`) flag tells `cargo-update` to update *every* binary managed by `cargo install`.  
It reads your installed package list from:

    ~/.cargo/.crates.toml

Without `-a`, you’d need to name each crate individually:

    cargo install-update atuin cargo-update ripgrep

---

## Example Workflow

    # Install the plugin (one time only)
    cargo install cargo-update

    # Check what can be updated
    cargo install-update --list

    # Update all installed Cargo tools
    cargo install-update -a

---

## Safety and Behavior

- **Scope:** Only affects binaries installed via `cargo install` (e.g., CLI tools).  
- **Does not touch:** System libraries, dependencies, or Cargo core itself.  
- **Rebuilds:** Each updated crate from source, so expect CPU usage.  
- **Data storage:** Keeps metadata in `~/.cargo/.crates.toml` and `~/.cargo/.crates2.json`.

---

## Why It’s Hard to Find via Google

- `cargo-update` is **not official**, so it’s absent from the Rust-lang.org docs.  
- Its docs live on developer platforms with weak SEO:
  - Crates.io: https://crates.io/crates/cargo-update  
  - Docs.rs: https://docs.rs/cargo-update/latest/cargo_update/  
  - GitHub: https://github.com/nabijaczleweli/cargo-update
- The command name (`install-update`) overlaps with other package managers (Homebrew, apt, etc.), which confuses search results.

---

## Verification

Confirm installation and version:

    cargo search cargo-update
    cargo install-update --version

List all Cargo plugins on your system:

    ls ~/.cargo/bin | grep cargo-

---

## Summary

| Aspect | Description |
|--------|--------------|
| **Official?** | No — community-maintained plugin |
| **Trust level** | High; long-term stable crate |
| **Purpose** | Updates globally installed Cargo binaries |
| **Pattern** | `cargo install cargo-update` → `cargo install-update` |
| **Docs** | Available on crates.io, docs.rs, GitHub |
| **Safe to use?** | Yes, limited to Cargo-managed binaries |

---

_Last verified: October 2025_