<h1 align="center">
<img src="https://raw.githubusercontent.com/Yrrrrrf/ud/main/resources/img/logo.svg" alt="ud Icon" width="128" height="128">
ud
</h1>
<div align="center">
[](https://github.com/Yrrrrrf/ud)
[](./LICENSE)
[](https://crates.io/crates/ud)
[](https://crates.io/crates/ud)
[](https://docs.rs/ud)
</div>
> **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
```sh
cargo install ud
```
### Quick Start
1. **Check for updates** in the current directory (dry-run):
```sh
ud
```
2. **Apply compatible updates** losslessly:
```sh
ud -u
```
3. **Apply breaking updates** as well:
```sh
ud -u --allow-breaking
```
4. **List all dependencies** and their current version details:
```sh
ud tree
```
---
## ⚙️ CLI Reference
### Usage
```sh
ud [OPTIONS] [PATH] [COMMAND]
```
- **`[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 to `stdout`.
- `-v, --verbose`: Enable verbose debug logging (written to `stderr`).
- `-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:
```toml
[dependencies]
serde = "1.0.0" # compatible bump: 1.0.219 (latest: 1.0.219)
tokio = "1.36.0" # current
tower = "^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 `1` because updates are available.
- **`ud -u`** (Compatible Updates)
- Bumps `serde` to `"1.0.219"`.
- Bumps `tower` to `"0.4.15"`.
- Leaves `tokio` unchanged.
- Exits with code `0`.
- **`ud -u --allow-breaking`** (All Updates)
- Bumps `serde` to `"1.0.219"`.
- Bumps `tower` to `"0.5.2"` (a breaking update under semver since it's a
`0.x` crate).
- Leaves `tokio` unchanged.
- Exits with code `0`.
---
## 📊 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 `type` tag (see example below).
### Example JSON Payload
```json
{
"verdicts": [
[
{
"coordinate": "serde",
"constraint": "1.0.0",
"span": { "start": 30, "end": 45 },
"source_hint": null,
"section": "dependencies"
},
{
"type": "Outdated",
"compatible": "1.0.219",
"latest": "1.0.219",
"latest_pre": null
}
],
[
{
"coordinate": "tokio",
"constraint": "1.36.0",
"span": { "start": 46, "end": 62 },
"source_hint": null,
"section": "dependencies"
},
{
"type": "Current",
"latest": "1.36.0",
"latest_pre": "1.37.0-rc.1"
}
],
[
{
"coordinate": "tower",
"constraint": "^0.4.13",
"span": { "start": 63, "end": 79 },
"source_hint": null,
"section": "dependencies"
},
{
"type": "Outdated",
"compatible": "0.4.15",
"latest": "0.5.2",
"latest_pre": null
}
]
]
}
```
---
## 🔒 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):
1. **The Universal CLI JSON Output:** The `--json` payload structure and the
names/meanings of all fields.
2. **The Universal Data Model (Rust types):** `Coordinate`, `Constraint`,
`Version`, `Span`, `Dependency`, `Availability`, `VersionMetadata`,
`Verdict`, and `Report`.
3. **Core traits:** The `Ecosystem` and `Scheme` traits.
### 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](./LICENSE)
file for details.