Struct SyncOptions 

#[non_exhaustive]
pub struct SyncOptions {

    pub dry_run: bool,
    pub validate: bool,
    pub workspace: Option<PathBuf>,
    pub ref_override: Option<String>,
    pub only_patterns: Option<Vec<String>>,
    pub force: bool,
    pub parallel: Option<usize>,
    pub force_prune: bool,
    pub force_prune_with_ignored: bool,
    pub quarantine: bool,
    pub migrate_lockfile: bool,
    pub recurse: bool,
    pub max_depth: Option<usize>,
    pub retain_days: Option<u32>,
}

Inputs to run.

Fields are public-writable so call sites can construct with struct literals and ..SyncOptions::default(). Marked #[non_exhaustive] so future knobs (parallelism, filter expressions, additional ref strategies) can land without breaking library consumers who constructed with explicit-literal syntax. Forces callers to use struct-update syntax (..Default::default()).

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

dry_run: bool

When true, use PlanExecutor (no filesystem mutations).

validate: bool

When false, skip plan-phase validators (manifest + graph). Debug escape hatch; production callers should leave this true.

workspace: Option<PathBuf>

Override workspace directory. None → derived from pack_root (the directory holding .grex/pack.yaml).

v1.2.1 path (iii) semantics: when Some, this path IS the canonical meta directory. Children resolve parent-relatively as <workspace>/<child.path> and <workspace>/.grex/pack.yaml is where the root manifest is read from. The path MUST exist; symlinks are resolved via fs::canonicalize to a single inode-stable form. Pre-v1.2.1 the override only re-anchored children — that legacy split is retired.

ref_override: Option<String>

Global ref override (grex sync --ref <sha|branch|tag>). When Some, every child pack clone/checkout uses this ref instead of the declared child.ref. Empty strings are rejected at the CLI layer.

only_patterns: Option<Vec<String>>

Pack-path filter patterns (grex sync --only <glob>). Raw glob strings — compiled internally via an in-crate globset helper so the globset crate version does not leak into the public API. None / empty means every pack runs (M3 semantics). Matching is against the pack’s workspace-relative path normalized to forward-slash form.

force: bool

Bypass the lockfile hash-match skip (grex sync --force). When true, every pack re-executes even if its actions_hash is unchanged from the prior lockfile.

parallel: Option<usize>

Max parallel pack ops for this sync run (feat-m6-1).

• None → callers default to num_cpus::get() at CLI layer. Library callers who construct SyncOptions directly and leave this None get num_cpus::get() semantics too — the sync driver resolves the default in one place so the scheduler slot on every ExecCtx is always populated.
• Some(0) → unbounded (Semaphore::MAX_PERMITS).
• Some(1) → serial fast-path.
• Some(n >= 2) → bounded parallel.

force_prune: bool

v1.2.0 Stage 1.l prep — when true, walker Phase 2 may drop dirty trees during prune. Still refuses ignored content unless SyncOptions::force_prune_with_ignored is also true. Default false preserves v1.1.1 behavior (refuse all dirty drops).

force_prune_with_ignored: bool

v1.2.0 Stage 1.l prep — when true (implies SyncOptions::force_prune), walker Phase 2 also drops ignored content. Hard override — the strongest level. Default false preserves v1.1.1 behavior.

quarantine: bool

v1.2.1 Item 5b — when true AND force_prune (or force_prune_with_ignored) is set, divert Phase 2 prunes through the snapshot-then-unlink quarantine pipeline. The dest’s full subtree is recursively copied to <workspace>/.grex/trash/<ISO8601>/<basename>/ BEFORE unlink(dest) fires. Snapshot or audit-fsync failure aborts the prune (no unlink). Lean theorem quarantine_snapshot_precedes_delete proves the safety contract. Default false preserves v1.2.0 direct-unlink behavior. Has no effect unless one of the force_prune* flags is also set (the CLI enforces this via requires = "force_prune"; library callers who set this with neither flag get a no-op since Phase 2 will not enter the override path at all).

migrate_lockfile: bool

v1.2.0 Stage 1.h opt-in — when true, the walker rewrites a legacy v1.1.1 lockfile in place to the v1.2.0 shape. When false (default), the walker errors on the legacy shape so migration is always an explicit caller decision.

recurse: bool

v1.2.0 Stage 1.j prep — when true (default), the walker descends into nested meta-children. doctor --shallow flips this to false so only the immediate workspace is inspected.

max_depth: Option<usize>

v1.2.0 Stage 1.j prep — pairs with SyncOptions::recurse for --shallow=N. None (default) is unbounded recursion when recurse is true. Some(n) caps depth at n levels of nesting.

retain_days: Option<u32>

v1.2.5 — when Some(N), every meta sync starts with a best-effort GC sweep over <meta>/.grex/trash/, deleting entries older than N days. None (default) preserves the v1.2.1 indefinite-retention behavior. The CLI surfaces this as grex sync --retain-days N; library callers wire it via SyncOptions::with_retain_days. Sweep failures log via tracing::warn! and DO NOT halt the sync.

Implementations

impl SyncOptions

pub fn new() -> Self

Default options: wet-run, validators enabled, default workspace path.

pub fn with_dry_run(self, dry_run: bool) -> Self

Set dry_run.

pub fn with_validate(self, validate: bool) -> Self

Set validate.

pub fn with_workspace(self, workspace: Option<PathBuf>) -> Self

Set workspace override.

pub fn with_ref_override(self, ref_override: Option<String>) -> Self

Set ref_override (--ref).

pub fn with_only_patterns(self, patterns: Option<Vec<String>>) -> Self

Set only_patterns (--only). Empty vector or None disables the filter.

pub fn with_force(self, force: bool) -> Self

Set force (--force).

pub fn with_parallel(self, parallel: Option<usize>) -> Self

Set parallel (--parallel). See SyncOptions::parallel for the None / Some(0) / Some(1) / Some(n) semantics.

pub fn with_force_prune(self, force_prune: bool) -> Self

Set force_prune (--force-prune). See SyncOptions::force_prune for the override matrix.

pub fn with_force_prune_with_ignored( self, force_prune_with_ignored: bool, ) -> Self

Set force_prune_with_ignored (--force-prune-with-ignored). See SyncOptions::force_prune_with_ignored for the override matrix.

pub fn with_quarantine(self, quarantine: bool) -> Self

Set quarantine (--quarantine). See SyncOptions::quarantine for the snapshot-before-delete contract. Has no effect unless SyncOptions::force_prune or SyncOptions::force_prune_with_ignored is also set.

pub fn with_retain_days(self, retain_days: Option<u32>) -> Self

Set retain_days (--retain-days N). See SyncOptions::retain_days for the GC-sweep contract. None preserves v1.2.1 indefinite-retention behavior; Some(N) triggers a best-effort sweep at the start of every meta sync.

Trait Implementations

impl Clone for SyncOptions

fn clone(&self) -> SyncOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SyncOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SyncOptions

fn default() -> Self

Returns the “default value” for a type.