cargo-deltabuild

cargo-deltabuild detects which crates in a Cargo workspace are impacted by changes in a Git feature branch. Build, test, and benchmarks only the crates you need—saving time and resources in your CI/CD pipeline.

• Robust Detection: Uses code analysis, pattern matching and runtime heuristics to identify dependencies.
• Impact Categorization: Separates crates into Modified, Affected, and Required for precise targeting.
• Configurability: Highly customizable via config, with per-crate overrides for parsing and detection.
• Dual-branch Git Detection: Compares two branches or commits to find both modified and deleted files.
• File Control Mechanisms: Exclude files from analysis or trigger a full rebuild when critical files change.

Installation

cargo install cargo-deltabuild

Usage

1. Check out the baseline branch and analyze:

   git checkout main
   cargo deltabuild analyze > main.json
   

2. Check out your feature branch and analyze:

   git checkout feature-branch
   cargo deltabuild analyze > feature.json
   

3. Compare analyses to find impacted crates:

   cargo deltabuild run --baseline main.json --current feature.json
   

Configuration

You can customize cargo-deltabuild by providing a -c config.toml argument to the command.

cargo deltabuild analyze -c config.toml # ...
cargo deltabuild run -c config.toml # ...

Configuration options can be set globally and overridden per crate. For example:

[parser]
foo = true
foo_patterns = ["*.foo", "*.bar"]

[parser.my-crate]
foo_patterns = ["*.baz"] # Override for a specific crate

Default settings are provided in config.toml.example.

Robust Detection

Module Traversal

Follows mod declarations and #[path] attributes to discover all Rust modules in the workspace.

Mod Macros

Discovers modules declared via custom macros (e.g., my_mod!), assuming first argument is the name of the module.

Config default:

[parser]
mod_macros = []

Config example:

[parser]
mod_macros = ["my_mod"]  # my_mod!(foo)

Include Macros

Detects files included via macros such as include_str! and include_bytes!, assuming the first argument is the name of the file.

Config default:

[parser]
includes = true
include_macros = [
    "include_str",   # include_str!("file.txt")
    "include_bytes"  # include_bytes!("file.bin")
]

Pattern-based Assumptions

Assumes certain files are dependencies based on glob patterns (e.g., *.proto, *.snap).

Config default:

[parser]
assume = false
assume_patterns = []

Config example:

[parser.grpc_crate]
assume = true
assume_patterns = [".proto"]

File Method Matching

Detects files loaded at runtime by matching method names (e.g., from_file, load, open), assuming the first argument is the name of the file.

Config default:

[parser]
file_refs = true
file_methods = [
    "file",       # ::file(path, ...)
    "from_file",  # ::from_file(path, ...)
    "load",       # ::load(path, ...)
    "open",       # ::open(path, ...)
    "read",       # ::read(path, ...)
    "load_from"   # ::load_from(path, ...)
]

File Control Mechanisms

File Exclusion

Exclude files and folders from analysis using glob patterns. Useful for ignoring build artifacts, temp files, etc.

Config default:

file_exclude_patterns = ["target/**", "*.tmp"]

Trip Wire

If any changed or deleted file matches a configured trip wire pattern, all crates are considered impacted. Use this for critical files like top-level Cargo.toml, build scripts, or configuration files.

Config default:

trip_wire_patterns = []

Config example:

trip_wire_patterns = [
    "Cargo.toml",       # top-level Cargo.toml
    "deltabuild.toml"   # DeltaBuild config file
]

Understanding Output

Analyze

Analyze phase produces JSON file that's intended to be consumed by run phase.

• files: Nested tree of file dependencies as detected by all the heuristics.
• crates: Dependency relationships between crates within the workspace.

Run

Run phase produces JSON file that's intended to be consumed by your CI/CD.

• Modified: Crates directly modified by Git changes.

• Affected: Modified crates plus all their dependents, direct and indirect.

• Required: Affected crates plus all their dependencies, direct and indirect.

Limitations

This tool is best-effort and may not detect all dependencies:

• Dynamic file paths computed at runtime

• Conditional compilation dependencies

• Other dependencies not captured by the heuristics

Example

$ cargo deltabuild run --baseline main.json --current feature.json
Running deltabuild..

Looking up git changes..

Changed file: "src/api/mod.rs"
Changed file: "src/utils.rs"

Using baseline analysis : main.json
Using current analysis  : feature.json

{
  "Modified": [
    "my-api",
    "my-utils"
  ],
  "Affected": [
    "my-api",
    "my-utils",
    "my-app"
  ],
  "Required": [
    "my-api",
    "my-utils", 
    "my-app",
    "common-lib"
  ]
}

Modified      2 (Crates directly modified by Git changes.)
Affected      3 (Modified crates plus all their dependents, direct and indirect.)
Required      4 (Affected crates plus all their dependencies, direct and indirect.)
Total        15 (Total crates in this workspace.)

Contributing

Contributions are welcome! Please feel free to fork the repository and submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.