ud
ud (Up to Date) — The two-letter answer to "are my dependencies current?"
ud is a small, fast, and universal dependency updater. It is designed to be headless-first and lossless by default, performing surgical updates on manifests (like Cargo.toml) without disturbing your comments, formatting, or inline tables.
By default, ud is safe: it runs in check-only mode and will never modify your files unless explicitly requested.
🚦 Getting Started
Installation
Quick Start
-
Check for updates in the current directory (dry-run):
-
Apply compatible updates losslessly:
-
Apply breaking updates as well:
-
List all dependencies and their current version details:
⚙️ CLI Reference
Usage
[PATH]: Path to the manifest file or directory containing one (defaults to.).
Options
-u, --update: Update the manifest file losslessly with compatible versions.--allow-breaking: Also apply breaking version bumps when updating (requires-u/--update).--pre: Include prerelease versions when resolving the latest available versions.--json: Output the report as JSON tostdout.-v, --verbose: Enable verbose debug logging (written tostderr).-h, --help: Print help information.-V, --version: Print version information.
Subcommands
tree: List all dependencies with their current status.
Exit Codes
ud returns the following exit codes:
0: Success. All dependencies are up to date (or were successfully updated).1: Outdated dependencies detected (in check/dry-run mode).2: Hard error (file not found, parse failure, network/index fetch error).
💡 Worked Example
Assume you have a Cargo.toml with the following dependencies:
[]
= "1.0.0" # compatible bump: 1.0.219 (latest: 1.0.219)
= "1.36.0" # current
= "^0.4.13" # compatible bump: 0.4.15 (latest breaking: 0.5.2)
Running different ud commands results in the following behaviors:
-
ud(Check Mode)- Outputs the status of each dependency to console.
- Does not edit the file.
- Exits with code
1because updates are available.
-
ud -u(Compatible Updates)- Bumps
serdeto"1.0.219". - Bumps
towerto"0.4.15". - Leaves
tokiounchanged. - Exits with code
0.
- Bumps
-
ud -u --allow-breaking(All Updates)- Bumps
serdeto"1.0.219". - Bumps
towerto"0.5.2"(a breaking update under semver since it's a0.xcrate). - Leaves
tokiounchanged. - Exits with code
0.
- Bumps
📊 JSON Schema
When run with the --json option, ud prints a JSON object to stdout containing the complete dependency analysis report.
Schema Structure
verdicts: An array of tuples, where each tuple is[Dependency, Verdict].- Dependency:
coordinate: Crate/package name (string).constraint: The version constraint declared in the manifest (string).span: Start and end byte indices in the file, if known (object or null).source_hint: Registry or repository hint, if known (string or null).section: Manifest section where it was declared (string or null).
- Verdict:
type: One of"Current","Outdated","Yanked","Unsatisfiable", or"Errored".- Fields depend on the
typetag (see example below).
- Dependency:
Example JSON Payload
🔒 Stability & Public API (v0.1.0+)
ud commits to a stable public surface to support scripting and tool integration.
Frozen Surface
The following items are frozen and subject to strict semver compatibility policies (additive changes are minor/patch bumps, breaking changes or removals require a major version bump):
- The Universal CLI JSON Output: The
--jsonpayload structure and the names/meanings of all fields. - The Universal Data Model (Rust types):
Coordinate,Constraint,Version,Span,Dependency,Availability,VersionMetadata,Verdict, andReport. - Core traits: The
EcosystemandSchemetraits.
Out of Scope / Unstable
The following components are implementation details and may change without warning:
- The internals of the dependency resolver.
- Formatting and colors of the human-readable CLI outputs.
- Sparse-index network protocols and transport details.
📄 License
This project is licensed under the MIT License. See the LICENSE file for details.