Diff Engine

Core diff engine in `agentfs-diff` — content and metadata diffs, classification of additions, removals, and modifications.

Purpose

Filesystem diff engine with modes, streams, watchers, file metadata comparisons, and change details.

This page follows the real source shape for Agentfs Diff and explains the workflow a developer is likely to use first.

Start from the smallest constructor or builder, perform one meaningful operation, inspect the returned state, then add the relevant policy, storage, or network integration. The examples below should be expanded whenever the crate API changes.

Primary types to know

AgentFSWrapper — local/agentfs-diff/src/comparison.rs
Diff — local/agentfs-diff/src/diff.rs
DiffEngine — local/agentfs-diff/src/engine.rs
DiffOptions — local/agentfs-diff/src/engine.rs
DiffStream — local/agentfs-diff/src/stream.rs
DiffWatcher — local/agentfs-diff/src/watcher.rs
DirectoryDiff — local/agentfs-diff/src/diff.rs
EntryInfo — local/agentfs-diff/src/comparison.rs
FileDiff — local/agentfs-diff/src/diff.rs
MetadataDiff — local/agentfs-diff/src/diff.rs
SymlinkDiff — local/agentfs-diff/src/diff.rs
WatchOptions — local/agentfs-diff/src/watcher.rs

Example shape

use agentfs_diff::{ComparisonMode, DiffEngine, DiffKind, DiffOptions};
use std::sync::{Arc, atomic::AtomicBool};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // DiffEngine::with_parallel caps concurrent file hashing under a semaphore.
    let engine = DiffEngine::with_parallel(8);

    // Build a feature-rich options object: content + metadata, gitignore-style
    // ignore patterns, and a cooperative cancel flag for long compares.
    let cancel = Arc::new(AtomicBool::new(false));
    let mut options = DiffOptions::default()
        .with_mode(ComparisonMode::Full)
        .with_content_comparison(true)
        .with_metadata_comparison(true);
    options.ignore_patterns = vec!["target/".into(), "**/.DS_Store".into()];
    options.include_unchanged = false;
    options.cancel_flag = Some(Arc::clone(&cancel));

    // Possible DiffKind values the engine emits.
    let kinds = [
        DiffKind::Added,
        DiffKind::Deleted,
        DiffKind::Modified,
        DiffKind::Moved,
        DiffKind::MetadataOnly,
        DiffKind::ContentOnly,
    ];
    let _ = engine; // engine is ready to call `compare(source, target, options)`.
    println!("engine_ready=true parallelism=8 diff_kinds={}", kinds.len());
    Ok(())
}

Diff Engine

Purpose

Developer workflow

Primary types to know

Example shape

On this page