carapace-sh/carapace-bin / skills/cargo
cargo
VerifiedUse when working with the cargo CLI — Rust's package manager. Covers the manifest format (Cargo.toml), dependencies, features, workspaces, build profiles, build scripts, configuration (.cargo/config.toml), registries and publishing, environment variables, the lockfile and cache, and the command reference. Triggers on: "cargo", "cargo build", "cargo check", "cargo test", "cargo run", "cargo add", "cargo update", "cargo publish", "cargo new", "cargo init", "cargo install", "cargo doc", "cargo bench", "cargo tree", "cargo metadata", "Cargo.toml", "Cargo.lock", "crate", "workspace", "feature", "profile", "build script", "build.rs", "registry", "crates.io", "CARGO_HOME", "rustc", "rustdoc", "rust-version", "edition".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.8 KB |
| references/build-scripts.md | markdown | 8.9 KB |
| references/commands.md | markdown | 18.7 KB |
| references/concepts.md | markdown | 9.5 KB |
| references/config.md | markdown | 12.5 KB |
| references/dependencies.md | markdown | 8.3 KB |
| references/environment.md | markdown | 7.7 KB |
| references/features.md | markdown | 9.5 KB |
| references/lockfile.md | markdown | 9.0 KB |
| references/manifest.md | markdown | 9.4 KB |
| references/profiles.md | markdown | 8.0 KB |
| references/registries.md | markdown | 10.4 KB |
| references/workspaces.md | markdown | 5.8 KB |
references/lockfile.md
View on GitHub# The Lockfile and Cache
The `Cargo.lock` file, the Package ID Spec format, the `~/.cargo` cache layout, and reproducible build flags.
> **Source of truth**: <https://doc.rust-lang.org/cargo/reference/workflows.html> and the cargo source (`cargo/core/resolver/encode.rs`).
## Cargo.lock
`Cargo.lock` records the **exact versions** of all dependencies in a build. Cargo generates and maintains it — you should not edit it manually. It ensures reproducible builds by pinning dependencies.
### TOML Structure
```toml
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
[[package]]
name = "bitflags"
version = "1.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dcee6df3c840e5d4f92fe6a24b5f74f2c50cc8b2e979c6ec92b5dd5c4d65ed8"
dependencies = [
"cfg-if",
]
[[package]]
name = "my-crate"
version = "0.1.0"
dependencies = [
"bitflags",
]
```
### Top-Level Fields
| Field | Type | Description |
|-------|------|-------------|
| `version` | int | Lockfile format version (1, 2, 3, or 4). V4 is current default (since Rust 1.83). |
| `[[package]]` | array of tables | One entry per package in the resolved graph |
| `[metadata]` | table | Checksum storage in V1 format (inlined in `[[package]]` for V2+) |
| `[patch]` | table | Tracks which `[patch]` directives from `Cargo.toml` were applied |
### `[[package]]` Entry
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Package name |
| `version` | string | Exact SemVer version |
| `source` | string (optional) | Source identifier — `null`/absent for path/workspace deps |
| `checksum` | string (optional) | SHA-256 of the `.crate` archive (registry deps) |
| `dependencies` | array | List of dependency references (names or inline tables) |
| `replace` | table (optional) | Replace directive |
### Source Identifier Formats
| Source | Format |
|--------|--------|
| Registry (git index) | `registry+https://github.com/rust-lang/crates.io-index` |
| Registry (sparse) | `sparse+https://index.crates.io/` |
| Git | `git+https://github.com/user/repo?branch=dev#abc123` |
| Path / workspace member | (absent — no `source` field) |
### Dependency References
**V2+ (compact, default):**
```toml
dependencies = [
"cfg-if",
"log 0.4.20",
]
```
**V1 (inline tables with source):**
```toml
dependencies = [
{ name = "libc", version = "0.2.0", source = "registry+https://github.com/rust-lang/crates.io-index" },
]
```
## Lockfile Format Versions
| Version | Key change |
|---------|------------|
| **V1** | Original. Checksums in `[metadata]` table; full dependency arrays with version info |
| **V2** | Merge-friendly (PR [#7070](https://github.com/rust-lang/cargo/pull/7070)). Compact dependencies (just names); inline checksums; reduces merge conflicts |
| **V3** | Git branch encoding. `branch = 'master'` in manifest encoded as `?branch=master` in source URLs. Default from Rust 1.53 through 1.82 |
| **V4** | URL encoding fix (PR [#12852](https://github.com/rust-lang/cargo/pull/12852)). SourceId URL serialization aware of URL encoding. **Current default** (since Rust 1.83) |
Cargo reads all older formats and only upgrades the version when the default changes. Newer Cargo won't unnecessarily rewrite an older lockfile.
## Should You Commit Cargo.lock?
| Project type | Commit? | Why |
|--------------|---------|-----|
| Binary (application) | **Yes** | Ensures reproducible builds |
| Library | Convention says no, but increasingly yes | Downstream generates their own; committing is not harmful and many libraries now commit it |
## Reproducible Build Flags
| Flag | Lockfile must exist? | Must be unchanged? | Network allowed? |
|------|---------------------|-------------------|------------------|
| *(none)* | Optional | No (will update) | Yes |
| `--locked` | Yes | Yes | Yes |
| `--offline` | Optional | No (will update if possible) | No |
| `--frozen` | Yes | Yes | No |
`--frozen` is equivalent to `--locked` + `--offline`.
## Lockfile Management Commands
### `cargo generate-lockfile`
Generate a new `Cargo.lock` or update the existing one to the latest compatible versions. Does not build anything.
### `cargo update`
Update dependencies in `Cargo.lock`:
```sh
cargo update # update all deps to latest compatible
cargo update -p serde # update only serde
cargo update -p serde --precise 1.0.85 # pin to exact version
cargo update --dry-run # preview without writing
cargo update -w # only update workspace packages
cargo update -b serde # allow SemVer-breaking update (unstable)
```
| Flag | Description |
|------|-------------|
| `-p, --package <SPEC>` | Package to update (repeatable) |
| `--precise <VERSION>` | Pin to exact version |
| `--recursive` / `--aggressive` | Also update all deps of the spec |
| `-b, --breaking` | Allow SemVer-breaking updates (unstable) |
| `-w, --workspace` | Only update workspace packages |
| `-n, --dry-run` | Don't write the lockfile |
## Package ID Spec
A string that uniquely identifies a package within a dependency graph. Used by `-p` flags, `cargo pkgid`, and `cargo metadata`.
### Short-Form Patterns
| Pattern | Example | Matches |
|---------|---------|---------|
| `name` | `serde` | Any version of `serde` (must be unique in graph) |
| `name@version` | `serde@1.0` | Version requirement |
| `url#version` | `https://github.com/rust-lang/cargo#0.33.0` | URL + version |
| `url#name` | `https://github.com/rust-lang/crates.io-index#bitflags` | URL + name |
| `url#name@version` | `...#crates-io@0.21.0` | URL + name + version |
### Fully Qualified Examples (from `cargo metadata`)
| Source | Example |
|--------|---------|
| Path dependency | `file:///path/to/my-package#0.1.0` |
| Registry | `registry+https://github.com/rust-lang/crates.io-index#regex@1.4.3` |
| Git | `git+https://github.com/rust-lang/cargo?rev=abc123#abc123` |
### Grammar
```
spec := name [ ("@" | ":") version ] | url [ "#" (name | version | name "@" version) ]
url := [ kind "+" ] proto "://" host-and-path [ "?" query ]
query := ("branch" | "tag" | "rev") "=" ref
kind := "registry" | "git" | "path"
```
`cargo pkgid -p <spec>` prints the fully qualified form. See [commands.md](commands.md).
## The Cargo Home (`~/.cargo`)
Configurable via `CARGO_HOME` (default `~/.cargo`).
### `registry/`
| Path | Contents |
|------|----------|
| `registry/index/` | Cloned registry index (git repo for git protocol, or sparse HTTP cache) |
| `registry/cache/` | Downloaded `.crate` archives (gzip-compressed) |
| `registry/src/` | Extracted source code (unpacked from `.crate`) |
### `git/`
| Path | Contents |
|------|----------|
| `git/db/` | Bare git repos for git dependencies |
| `git/checkouts/` | Checked-out commits (one per rev); multiple checkouts of the same repo coexist |
### Other
| Path | Contents |
|------|----------|
| `bin/` | Executables installed via `cargo install` |
| `config.toml` | Global config — see [config.md](config.md) |
| `credentials.toml` | Auth tokens — see [registries.md](registries.md) |
| `.crates.toml` / `.crates2.json` | Tracking info for `cargo install` |
| `target/` | (per-project, not in `CARGO_HOME`) Build artifacts |
### CI Caching
Cache: `.crates.toml`, `.crates2.json`, `bin/`, `registry/index/`, `registry/cache/`, `git/db/`.
Do **not** cache: `registry/src/` (redundant with `registry/cache/`).
## Cache Auto-Cleaning
Cargo automatically cleans the global cache (configurable via `cache.auto-clean-frequency`):
- Network files (registry `.crate` archives, git checkouts) unused for **3 months** are deleted
- Non-network files unused for **1 month** are deleted
- Disabled when `--offline`
## The Target Directory
Build artifacts go to `target/` (configurable via `build.target-dir` or `CARGO_TARGET_DIR`):
| Path | Contents |
|------|----------|
| `target/debug/` | `dev` profile artifacts |
| `target/release/` | `release` profile artifacts |
| `target/<custom-profile>/` | Custom profile artifacts |
| `target/debug/deps/` | Compiled dependencies and test binaries |
| `target/doc/` | Generated documentation |
| `target/package/` | `.crate` tarballs from `cargo package` |
| `target/<profile>/.fingerprint/` | Fingerprint data for incremental builds |
| `target/<profile>/build/` | Build script output and artifacts |
See [profiles.md](profiles.md) for the profile-to-directory mapping.
## References
- <https://doc.rust-lang.org/cargo/reference/pkgid-spec.html>
- <https://doc.rust-lang.org/cargo/commands/cargo-pkgid.html>
- <https://doc.rust-lang.org/cargo/commands/cargo-update.html>
- <https://doc.rust-lang.org/cargo/guide/cargo-home.html>
- <https://docs.rs/cargo-lock/> (lockfile parsing library docs)
## Related
- [concepts.md](concepts.md) — manifest vs lockfile, build pipeline, `CARGO_HOME` overview
- [config.md](config.md) — `build.target-dir`, `CARGO_TARGET_DIR`
- [profiles.md](profiles.md) — target directory per profile
- [registries.md](registries.md) — registry cache and source replacement
- [commands.md](commands.md) — `cargo update`, `cargo generate-lockfile`, `cargo pkgid`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |