Struct AllowOptions 

pub struct AllowOptions { /* private fields */ }

Options for --allow-* style safety checks before modifying files.

This is the main entry point for most users of this crate.

This type matches the semantics of cargo fix:

• allow_no_vcs treats modification as safe even when no supported VCS repository is found
• allow_dirty treats modification as safe even when the path is dirty or has staged changes
• allow_staged treats modification as safe even when the path has staged changes, but still considers dirty files unsafe

These options are not interpreted independently. Higher-precedence options imply lower-precedence ones, matching cargo fix:

• allow_no_vcs skips repository discovery and repository state checks entirely
• allow_dirty still requires repository discovery, but implies allow_staged and skips dirty and staged change checks
• allow_staged still requires repository discovery and change queries, but dirty files remain unsafe

By default, checks are scoped to the queried path. Use Self::check_entire_repository to check the containing repository as a whole instead.

Example

use std::path::Path;

use vcs_modify_guard::{AllowOptions, ModificationSafety, UnsafeModificationReason};

let safety = AllowOptions::new()
    .allow_staged(true)
    .check_safe_to_modify(Path::new("."))?;

match safety {
    ModificationSafety::Safe => {}
    ModificationSafety::Unsafe(reason) => match reason {
        UnsafeModificationReason::NoVcs => {
            eprintln!("The target path is not in a VCS repository.");
            return Err("blocked by no VCS".into());
        }
        UnsafeModificationReason::Dirty {
            dirty_files,
            staged_files,
            ..
        } => {
            eprintln!("Dirty files:");
            for wt_path in dirty_files {
                eprintln!("* {}", wt_path.display());
            }
            for wt_path in staged_files {
                eprintln!("* {} (staged)", wt_path.display());
            }
            return Err("blocked by dirty files".into());
        }
        UnsafeModificationReason::Staged { staged_files, .. } => {
            eprintln!("Staged files:");
            for wt_path in staged_files {
                eprintln!("* {}", wt_path.display());
            }
            return Err("blocked by staged changes".into());
        }
        _ => {
            eprintln!("The target path has unsafe modifications under it.");
            return Err("blocked by unsafe modifications".into());
        }
    },
}

Implementations

impl AllowOptions

pub const fn new() -> Self

Creates an AllowOptions value with all --allow-* options disabled.

pub const fn allow_no_vcs(self, enabled: bool) -> Self

Sets whether to use cargo fix-style --allow-no-vcs behavior.

When enabled, this skips repository discovery and repository state checks entirely, matching cargo fix. In other words, this does more than only relax the “no repository found” case.

pub const fn allow_dirty(self, enabled: bool) -> Self

Sets whether to use cargo fix-style --allow-dirty behavior.

When enabled, this still requires repository discovery unless Self::allow_no_vcs is enabled, but it treats both dirty files and staged changes as safe. This also implies Self::allow_staged.

pub const fn allow_staged(self, enabled: bool) -> Self

Sets whether to use cargo fix-style --allow-staged behavior.

When enabled, this still requires repository discovery and change queries unless Self::allow_no_vcs is enabled. Dirty files are still considered unsafe.

pub const fn check_entire_repository(self, enabled: bool) -> Self

Sets whether the safety check should cover the entire containing repository rather than only the queried path.

pub fn check_safe_to_modify<P>( &self, path: P, ) -> Result<ModificationSafety, ModifyGuardError>

where P: AsRef<Path>,

Checks whether modification of path is considered safe under the current --allow-* settings.

Flag handling matches cargo fix:

• Self::allow_no_vcs returns ModificationSafety::Safe and skips repository discovery and repository state checks
• Self::allow_dirty still requires repository discovery, but returns ModificationSafety::Safe and skips rejecting dirty or staged changes
• Self::allow_staged still requires repository discovery and change queries, but dirty files remain unsafe

When Self::check_entire_repository is disabled, the safety check is scoped to path after resolving it within the containing repository worktree. When enabled, the entire containing repository is checked.

Errors

Returns an error if repository discovery fails, if path cannot be resolved for change queries, or if the backend fails to query the relevant changes.

Trait Implementations

impl Clone for AllowOptions

fn clone(&self) -> AllowOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AllowOptions

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

Formats the value using the given formatter.

impl Default for AllowOptions

fn default() -> Self

Returns the “default value” for a type.